Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: mpp-agent
|
||||
description: Pay HTTP 402 APIs via Machine Payments Protocol (MPP).
|
||||
version: 0.1.0
|
||||
author: Teknium (teknium1), Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Payments, MPP, HTTP-402, Tempo, Stripe]
|
||||
related_skills: [stripe-link-cli, stripe-projects]
|
||||
---
|
||||
|
||||
# MPP Agent Skill
|
||||
|
||||
Wraps the Machine Payments Protocol (MPP, https://mpp.dev) clients so Hermes can pay for per-request API access against servers that respond with `HTTP 402 Payment Required`.
|
||||
|
||||
Three client options, all distributed via npm. Pick the lightest one that solves the user's need. Gated `[linux, macos]` while the broader payments tooling matures on Windows.
|
||||
|
||||
## When to Use
|
||||
|
||||
- A merchant API returns `HTTP 402` with a `www-authenticate` header — and the user wants to actually pay it, not just log the response.
|
||||
- The user asks to "pay per request", "set up an agent wallet", "use Tempo / Privy / AgentCash", or wants to discover MPP-priced services.
|
||||
- A Stripe Link spend has produced a Shared Payment Token (SPT) and the agent needs to attach it to the 402 challenge — in that flow, prefer `link-cli mpp pay` (see the `stripe-link-cli` skill).
|
||||
|
||||
## Choosing a client
|
||||
|
||||
| Tool | When | Setup |
|
||||
|---|---|---|
|
||||
| `link-cli` | User already has Stripe Link set up, or the 402 challenge advertises `method="stripe"` | see the `stripe-link-cli` skill |
|
||||
| Tempo Wallet | MPP services with spend controls, service discovery | `tempo wallet login` |
|
||||
| Privy Agent CLI | Multi-chain wallets, browser-based funding | `privy-agent-wallets login` |
|
||||
| AgentCash | 300+ pre-priced APIs via one USDC.e balance | `npx agentcash onboard` |
|
||||
| `mppx` | Dev + debugging, smallest dep surface | `npm install -g mppx` then `mppx account create` |
|
||||
|
||||
Default: if the user already has Stripe Link configured or the 402 challenge specifies `method="stripe"`, use `link-cli mpp pay` (the `stripe-link-cli` skill). Otherwise `mppx` for one-off paid calls and debugging, and Tempo Wallet when the user wants persistent spend controls.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+ on `PATH`
|
||||
- A funded wallet (Tempo / Privy / AgentCash) OR an `mppx` account
|
||||
- For Tempo / Privy / AgentCash: follow their respective onboarding skills:
|
||||
- `https://tempo.xyz/SKILL.md`
|
||||
- `https://agents.privy.io/skill.md`
|
||||
- `https://agentcash.dev/skill.md`
|
||||
|
||||
Use `web_extract` to fetch any of those SKILL.md files if the user picks one.
|
||||
|
||||
## Procedure (mppx, fastest path)
|
||||
|
||||
Run all commands through the `terminal` tool.
|
||||
|
||||
### 1. Install + create an account
|
||||
|
||||
```
|
||||
npm install -g mppx
|
||||
mppx account create
|
||||
```
|
||||
|
||||
Store the resulting account credentials wherever the CLI tells you (the CLI writes them under its own config — do not paste them into the agent transcript).
|
||||
|
||||
### 2. Inspect the merchant's 402 challenge
|
||||
|
||||
If the user gives you a URL, probe it first to confirm it actually speaks MPP:
|
||||
|
||||
```
|
||||
curl -i <url>
|
||||
```
|
||||
|
||||
A real MPP 402 looks like:
|
||||
|
||||
```
|
||||
HTTP/1.1 402 Payment Required
|
||||
www-authenticate: tempo amount=0.1 currency=...
|
||||
```
|
||||
|
||||
### 3. Pay the request
|
||||
|
||||
```
|
||||
mppx <url>
|
||||
```
|
||||
|
||||
For non-GET methods or request bodies:
|
||||
|
||||
```
|
||||
mppx <url> --method POST --data '<json>'
|
||||
```
|
||||
|
||||
`mppx` handles the 402 challenge/credential dance automatically and prints the merchant's actual response on success.
|
||||
|
||||
### 4. Verify the receipt
|
||||
|
||||
`mppx` attaches the receipt header automatically. To inspect:
|
||||
|
||||
```
|
||||
mppx <url> -v
|
||||
```
|
||||
|
||||
## Procedure (Tempo Wallet)
|
||||
|
||||
The Tempo Wallet skill at https://tempo.xyz/SKILL.md is the canonical reference; fetch it with `web_extract` and follow it. Headline:
|
||||
|
||||
```
|
||||
tempo wallet login
|
||||
tempo wallet pay <url>
|
||||
```
|
||||
|
||||
Spend controls and service discovery live in the wallet UI at https://wallet.tempo.xyz.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **`HTTP 402` without `method="stripe"` cannot be paid by Stripe Link.** If the challenge advertises only Tempo / other methods, use `mppx` (or whichever wallet matches) — Link will reject it. Conversely, if it advertises `method="stripe"`, prefer Link via the `stripe-link-cli` skill so the spend goes through the user's approved card.
|
||||
- **Multiple challenges in one header.** `www-authenticate` may list several methods (e.g. `tempo, stripe`). The Link CLI's `mpp decode` will pick the Stripe one; `mppx` will pick Tempo. There's no single "right" client — pick by which wallet the user has funded.
|
||||
- **Zero-amount challenges.** Some MPP endpoints charge `$0.00` and just want a proof credential. These work without a funded wallet. Don't refuse them as "broken."
|
||||
- **Wallet keys never enter agent context.** All four clients store keys under their own config dirs (or generate per-session ephemeral keypairs, in Privy's case). Do not `cat`/`read_file` them.
|
||||
- **Server-side MPP is a different skill.** If the user wants to ADD 402 to their own API, this skill is wrong — point them at https://mpp.dev/quickstart/server and the `mppx/nextjs` / `mppx/hono` / `mppx/express` / `mppx/elysia` middlewares. A dedicated `mpp-server` skill may land later.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
mppx --version && mppx account list
|
||||
```
|
||||
|
||||
Exit code 0 means installed and an account exists.
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
name: stripe-link-cli
|
||||
description: Agent payments via Stripe Link — cards, SPT, approvals.
|
||||
version: 0.1.0
|
||||
author: Teknium (teknium1), Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Payments, Stripe, Link, Checkout, MPP]
|
||||
related_skills: [mpp-agent, stripe-projects]
|
||||
---
|
||||
|
||||
# Stripe Link CLI Skill
|
||||
|
||||
Wraps [@stripe/link-cli](https://github.com/stripe/link-cli) so Hermes can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Hermes cannot self-approve.
|
||||
|
||||
US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated `[linux, macos]`.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger phrases:
|
||||
|
||||
- "buy X", "pay for X", "make a purchase", "complete checkout"
|
||||
- "get me a card", "I need a payment method"
|
||||
- "log in to Link", "connect my Link wallet"
|
||||
- HTTP 402 response from a merchant API with `www-authenticate: ... method="stripe"`
|
||||
|
||||
If the user wants a paid API call (HTTP 402, no checkout form), the `card` path is wrong — use SPT via this same skill, or hand off to the `mpp-agent` skill.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+ available on `PATH` (`node --version`)
|
||||
- US-based (Link account requirement)
|
||||
|
||||
The Link account, payment method, and spend-approval app do NOT need to be set up before Hermes attempts to pay — the CLI walks the user through them on first run:
|
||||
|
||||
- A Link account at https://app.link.com — created/linked during first `link-cli` auth
|
||||
- At least one payment method — added during first run at https://app.link.com/wallet
|
||||
- The Link mobile/web app — opened to approve the first spend request when it's made
|
||||
|
||||
No env vars required — auth state is stored locally by the CLI under its own config directory.
|
||||
|
||||
## Install
|
||||
|
||||
Install once, globally:
|
||||
|
||||
```
|
||||
npm install -g @stripe/link-cli
|
||||
```
|
||||
|
||||
Or invoke ad-hoc via `npx @stripe/link-cli`. The skill below uses the installed `link-cli` form.
|
||||
|
||||
## How to Run
|
||||
|
||||
All commands run through the `terminal` tool. The CLI auto-detects non-TTY callers and emits compact `toon` output by default — fine for the model. Pass `--format json` if a step needs structured fields.
|
||||
|
||||
Discover commands: `link-cli --llms-full`.
|
||||
Get a command's schema before invoking: `link-cli <command> --schema`.
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. Check / establish auth
|
||||
|
||||
```
|
||||
link-cli auth status
|
||||
```
|
||||
|
||||
If not authenticated, log in with a clear client name (this label shows in the user's Link app):
|
||||
|
||||
```
|
||||
link-cli auth login --client-name "Hermes" --interval 5 --timeout 300
|
||||
```
|
||||
|
||||
The `--interval`/`--timeout` form polls inline so the agent doesn't need to manage a `_next` step. Print the verification URL + phrase to the user and wait for the CLI to return.
|
||||
|
||||
**Do not proceed past this step until `auth status` confirms login.**
|
||||
|
||||
### 2. Evaluate the merchant before creating a spend request
|
||||
|
||||
Decide the credential type:
|
||||
|
||||
| Merchant surface | `--credential-type` |
|
||||
|---|---|
|
||||
| Standard web checkout form / Stripe Elements | `card` (default) |
|
||||
| Returns HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` |
|
||||
| Returns HTTP 402 without `method="stripe"` | unsupported — stop |
|
||||
|
||||
For 402 responses, do NOT decode the challenge manually. Pass the raw header:
|
||||
|
||||
```
|
||||
link-cli mpp decode --challenge '<full WWW-Authenticate header>'
|
||||
```
|
||||
|
||||
This validates the challenge and extracts the network ID + decoded request body.
|
||||
|
||||
### 3. List payment methods + shipping
|
||||
|
||||
```
|
||||
link-cli payment-methods list
|
||||
link-cli shipping-address list
|
||||
```
|
||||
|
||||
Use the first entry unless the user specifies otherwise. The `id` from `payment-methods list` is the `--payment-method-id` in the next step.
|
||||
|
||||
### 4. Create the spend request
|
||||
|
||||
Confirm the final total with the user before issuing this command. Amounts are in cents.
|
||||
|
||||
```
|
||||
link-cli spend-request create \
|
||||
--payment-method-id <pm_id> \
|
||||
--merchant-name "<name>" \
|
||||
--merchant-url "<url>" \
|
||||
--context "<one sentence: what is being purchased and why>" \
|
||||
--amount <cents> \
|
||||
--line-item "name:<item>,unit_amount:<cents>,quantity:1" \
|
||||
--total "type:total,display_text:Total,amount:<cents>" \
|
||||
--request-approval
|
||||
```
|
||||
|
||||
For MPP merchants add `--credential-type shared_payment_token`.
|
||||
|
||||
`--request-approval` pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout.
|
||||
|
||||
### 5. Retrieve the credential — SECURELY
|
||||
|
||||
**Do not print card details to stdout.** Use `--output-file` so the PAN never enters the agent's transcript or logs:
|
||||
|
||||
```
|
||||
link-cli spend-request retrieve <lsrq_id> \
|
||||
--include card \
|
||||
--output-file /tmp/link-card.json \
|
||||
--format json
|
||||
```
|
||||
|
||||
The file is written with `0600` perms; stdout shows only redacted fields (brand, last4, expiry) plus a `card_output_file` path.
|
||||
|
||||
### 6. Use the credential
|
||||
|
||||
- For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never `read_file` or `cat` the card file into the agent's reasoning context.
|
||||
- For MPP merchants:
|
||||
|
||||
```
|
||||
link-cli mpp pay <merchant-url> \
|
||||
--spend-request-id <lsrq_id> \
|
||||
--method POST \
|
||||
--data '<json body>'
|
||||
```
|
||||
|
||||
### 7. Clean up
|
||||
|
||||
Delete the card file as soon as the purchase is done:
|
||||
|
||||
```
|
||||
rm -f /tmp/link-card.json
|
||||
```
|
||||
|
||||
## Optional: run as an MCP server instead
|
||||
|
||||
`@stripe/link-cli --mcp` exposes the same commands as MCP tools over stdio. To register it with Hermes' native MCP:
|
||||
|
||||
```
|
||||
hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"
|
||||
```
|
||||
|
||||
Then `hermes mcp list` should show `stripe-link`. The same approval rules apply — MCP doesn't bypass the Link app approval step.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **US-only.** Outside the US, `auth login` will fail. Tell the user, don't keep retrying.
|
||||
- **Card PAN must never enter agent context.** Use `--output-file` every time. If you've already retrieved without it, immediately `link-cli auth logout` is not enough — the card is one-time-use but rotate hygiene matters.
|
||||
- **`--request-approval` blocks until the user acts.** If the user is asleep, the CLI will hit its timeout. Set expectations.
|
||||
- **Multi-step `_next` commands.** Some commands return `_next.command` that must be executed to continue. When in doubt, prefer the inline-polling flags (`--interval`/`--timeout`).
|
||||
- **Output format defaults to `toon`** in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass `--format json`.
|
||||
- **Don't default to `card`.** The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
link-cli --version && link-cli auth status
|
||||
```
|
||||
|
||||
Exit code 0 means installed and logged in.
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: stripe-projects
|
||||
description: Provision SaaS services + sync creds via Stripe Projects.
|
||||
version: 0.1.0
|
||||
author: Teknium (teknium1), Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Payments, Stripe, Projects, Provisioning, Infrastructure]
|
||||
related_skills: [stripe-link-cli, mpp-agent]
|
||||
---
|
||||
|
||||
# Stripe Projects Skill
|
||||
|
||||
Wraps the [Stripe Projects](https://projects.dev) CLI plugin so Hermes can provision SaaS services (Neon, Twilio, Vercel, etc.), generate and sync credentials into the user's `.env`, and manage billing across providers from one place.
|
||||
|
||||
Gated `[linux, macos]` while the broader payments cluster matures on Windows. The Stripe CLI itself is cross-platform; this gate is a posture for the cluster, not a hard limit.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger phrases:
|
||||
|
||||
- "set up <provider>", "provision <Neon|Twilio|Vercel|...>", "create a database"
|
||||
- "give me a <Postgres|Redis|Twilio number|...> for this project"
|
||||
- "manage my stack credentials", "rotate this key", "upgrade my plan"
|
||||
- "what providers can I add?"
|
||||
|
||||
If the user already has a provider account, this skill can still connect it with `stripe projects link <provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Stripe CLI installed (Homebrew on macOS, package manager on Linux, or download from https://docs.stripe.com/stripe-cli/install)
|
||||
- Stripe Projects plugin installed
|
||||
- A Stripe account. If the user doesn't have one yet, the CLI can guide them through sign-in or account creation in the browser during setup.
|
||||
|
||||
## Install
|
||||
|
||||
macOS:
|
||||
|
||||
```
|
||||
brew install stripe/stripe-cli/stripe
|
||||
stripe plugin install projects
|
||||
```
|
||||
|
||||
Linux: follow the platform-specific install at https://docs.stripe.com/stripe-cli/install, then:
|
||||
|
||||
```
|
||||
stripe plugin install projects
|
||||
```
|
||||
|
||||
## How to Run
|
||||
|
||||
All commands run through the `terminal` tool from inside the user's project directory (the CLI writes `.env` and `.projects/vault/vault.json` into the CWD).
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. Initialize the project
|
||||
|
||||
```
|
||||
cd <project-root>
|
||||
stripe projects init
|
||||
```
|
||||
|
||||
This creates `.projects/vault/vault.json` (encrypted credential store) and prepares the project to receive providers.
|
||||
|
||||
### 2. Discover available providers
|
||||
|
||||
```
|
||||
stripe projects catalog
|
||||
```
|
||||
|
||||
Lists every provider Stripe Projects supports — databases, hosting, auth, AI, analytics, messaging, etc.
|
||||
|
||||
### 3. Add a service
|
||||
|
||||
```
|
||||
stripe projects add <provider>/<service>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `stripe projects add neon/postgres`
|
||||
- `stripe projects add twilio/sms`
|
||||
- `stripe projects add runloop/sandbox`
|
||||
|
||||
The CLI provisions the service in the user's own account with the provider, generates credentials, syncs them into `.env`, and records the resource in the vault. The user may need to confirm a tier selection or pricing prompt.
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```
|
||||
stripe projects list
|
||||
```
|
||||
|
||||
Should show the newly added provider and its `.env` keys.
|
||||
|
||||
### 5. Manage / upgrade / remove
|
||||
|
||||
```
|
||||
stripe projects upgrade <provider> # tier change
|
||||
stripe projects remove <provider> # deprovision
|
||||
stripe projects rotate <provider> # rotate credentials
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **`.env` writes are real writes.** The CLI appends to whatever `.env` is in the project root. If the user's `.env` is gitignored (normal), the keys land safely; if not, this skill could be a credential-leak vector. Always check `.gitignore` first.
|
||||
- **Per-project state.** `.projects/vault/vault.json` is per-project. Provisioning the same service in two different projects creates two separate resources — and two bills.
|
||||
- **Billing happens on Stripe's side.** Tier prompts during `add`/`upgrade` are real charges; surface them to the user before confirming.
|
||||
- **Provider availability changes.** The catalog grows; if a provider the user names isn't listed, `stripe projects catalog | grep <name>` first instead of failing the `add` call.
|
||||
- **Credentials in vault are encrypted but `.env` is plaintext.** Standard `.env` hygiene applies — never commit it.
|
||||
- **Removing a service does NOT always destroy the underlying resource.** Some providers leave a paused/dormant resource behind. Check the provider's own dashboard after `remove` for high-cost services (managed databases especially).
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
stripe projects --version && stripe projects list
|
||||
```
|
||||
|
||||
Exit code 0 inside an initialized project means the plugin is healthy.
|
||||
Reference in New Issue
Block a user