@web42/w42 0.1.20 → 0.1.21

package/README.md

@@ -1,6 +1,6 @@
 # @web42/cli
 
-CLI for the Web42 Agent Network — authenticate, publish, discover, and interact with A2A agents.
+CLI for the Web42 Agent Network — authenticate, publish, discover, interact with A2A agents, and manage AP2 payments.
 
 ## Installation
 
@@ -11,20 +11,22 @@ npm install -g @web42/cli
 ## Authentication
 
 ```bash
-web42 auth login     # Sign in via GitHub OAuth
-web42 auth logout    # Sign out
-web42 auth whoami    # Show current user
+w42 auth login     # Sign in via GitHub OAuth
+w42 auth logout    # Sign out
+w42 auth whoami    # Show current user
 ```
 
+---
+
 ## Commands
 
-### `web42 search <query>`
+### `w42 search <query>`
 
 Search the network for agents.
 
 ```bash
-web42 search "data analysis"
-web42 search "image processing" --limit 20
+w42 search "data analysis"
+w42 search "pizza ordering" --limit 20
 ```
 
 | Option | Description |
@@ -33,13 +35,14 @@ web42 search "image processing" --limit 20
 
 ---
 
-### `web42 send <agent> <message>`
+### `w42 send <agent> <message>`
 
 Send a message to an A2A agent. `<agent>` can be a slug (`@user/agent`) or a direct URL (`http://localhost:3001`).
 
 ```bash
-web42 send @alice/summarizer "Summarize this document"
-web42 send http://localhost:3001 "Hello"
+w42 send @alice/summarizer "Summarize this document"
+w42 send http://localhost:3001 "Hello"
+w42 send @alice/pizza "Margherita please" --pay tx_a1b2c3d4
 ```
 
 | Option | Description |
@@ -47,134 +50,231 @@ web42 send http://localhost:3001 "Hello"
 | `--new` | Start a new conversation (clears saved context) |
 | `--context <id>` | Use a specific context ID |
 | `--task-id <id>` | Reply to a specific task (e.g. one in `input-required` state) |
-| `--pay <token>` | Attach AP2 payment token as PaymentMandate data part |
+| `--pay <tx_id>` | Attach a `PaymentMandate` from a local transaction (use a tx ID from `w42 cart list`) |
+
+When an agent sends a `CartMandate`, the CLI auto-saves it as a local transaction (`tx_xxx`) and prints the next step. If you have a matching intent locally cached, it prints the one-liner checkout command directly.
 
 ---
 
-### `web42 serve`
+### `w42 wallet`
 
-Start a local A2A server for your agent, bridging to an OpenClaw gateway.
+View your Web42 Wallet balance.
 
 ```bash
-web42 serve
-web42 serve --port 3001 --url https://my-agent.ngrok.io --verbose
+w42 wallet
+```
+
+#### `w42 wallet topup <amount>`
+
+Add funds to your wallet. Amount is in dollars.
+
+```bash
+w42 wallet topup 50.00
+```
+
+---
+
+### `w42 cart`
+
+Manage AP2 cart payments. Carts are auto-saved as local transactions (`tx_xxx`) when received from an agent via `w42 send`.
+
+#### `w42 cart list`
+
+List all local payment transactions.
+
+```bash
+w42 cart list
+w42 cart list --status cart_received
 ```
 
 | Option | Description |
 |---|---|
-| `--port <port>` | Port to listen on (default: 4000) |
-| `--url <url>` | Public URL for registration and AgentCard (e.g. from ngrok) |
-| `--openclaw-port <port>` | OpenClaw gateway port (default: 18789) |
-| `--openclaw-token <token>` | OpenClaw gateway auth token (or `OPENCLAW_GATEWAY_TOKEN`) |
-| `--openclaw-agent <id>` | OpenClaw agent ID to target (default: `main`) |
-| `--client-id <id>` | Developer app client ID (or `W42_CLIENT_ID`) |
-| `--client-secret <secret>` | Developer app client secret (or `W42_CLIENT_SECRET`) |
-| `--visibility <vis>` | Marketplace visibility: `public` or `private` |
-| `--verbose` | Enable verbose request/response logging |
+| `--status <status>` | Filter by status: `cart_received`, `session_created`, `approved`, `sent` |
 
----
+#### `w42 cart sign <tx_id>`
 
-### `web42 register <url>`
+Create a payment session for human approval. Opens a browser signing URL.
 
-Register an agent with the Web42 Network. The URL must serve `/.well-known/agent-card.json`.
+```bash
+w42 cart sign tx_a1b2c3d4
+```
+
+- Validates that the cart supports `WEB42_WALLET` before proceeding.
+- Stores `sessionCode` and `signingUrl` on the transaction.
+- Returns `{ tx, signing_url }` — present the URL to the user.
+
+#### `w42 cart poll <tx_id>`
+
+Check the status of a payment session. When completed, stores the full `PaymentMandate` on the transaction.
+
+```bash
+w42 cart poll tx_a1b2c3d4
+```
+
+#### `w42 cart checkout <tx_id> --intent <nick>`
+
+Execute a payment against a matching intent — no human approval needed.
 
 ```bash
-web42 register https://my-agent.example.com
-web42 register https://my-agent.example.com --visibility private --tags "nlp,summarization"
+w42 cart checkout tx_a1b2c3d4 --intent starbucks-daily
 ```
 
 | Option | Description |
 |---|---|
-| `--price <cents>` | Price in cents (default: 0 = free) |
-| `--license <license>` | License (e.g. `MIT`, `Apache-2.0`) |
-| `--visibility <vis>` | `public` or `private` (default: `public`) |
-| `--tags <tags>` | Comma-separated tags |
-| `--categories <cats>` | Comma-separated categories |
+| `--intent <nick>` | Intent nick to use (required) |
+
+- Validates that the cart supports `WEB42_WALLET` before proceeding.
+- Returns structured error codes when the intent is invalid (see below).
+- Stale intents (exhausted, expired, not found) are automatically evicted from the local cache.
+
+**Intent error codes:**
+
+| Code | Meaning |
+|---|---|
+| `INTENT_NOT_FOUND` | Intent doesn't exist on the platform |
+| `INTENT_INACTIVE` | Intent is exhausted or revoked |
+| `INTENT_EXPIRED` | Intent has passed its expiry date |
+| `INTENT_BUDGET_EXHAUSTED` | Lifetime budget fully consumed |
+| `INTENT_PERIOD_BUDGET_EXHAUSTED` | Daily/weekly/monthly budget hit |
+| `INTENT_AMOUNT_EXCEEDED` | Cart total exceeds the per-transaction cap |
+| `INTENT_AGENT_NOT_AUTHORIZED` | Merchant not covered by this intent |
+| `INTENT_CURRENCY_MISMATCH` | Cart currency doesn't match the intent |
 
 ---
 
-### `web42 pay`
+### `w42 intent`
 
-AP2 payment commands — intents, checkout, and human signing.
+Manage payment intents. Intents are pre-authorizations that let agents spend on your behalf without per-purchase approval.
 
-#### `web42 pay intent propose`
+#### `w42 intent propose`
 
-Generate an intent creation URL for the user to authorize in the browser.
+Generate an intent creation URL for the user to authorize in the browser (attaches a card for automatic charging).
 
 ```bash
-web42 pay intent propose --nick starbucks-daily --agents @x~starbucks --max-amount 5.00 --prompt-playback "Spend up to $5/day at Starbucks" --recurring daily
+w42 intent propose \
+  --nick starbucks-daily \
+  --agents @x~starbucks \
+  --max-amount 5.00 \
+  --prompt-playback "Spend up to $5/day at Starbucks" \
+  --recurring daily
 ```
 
 | Option | Description |
 |---|---|
-| `--nick <nick>` | Short identifier for the intent (required) |
+| `--nick <nick>` | Short identifier, 3–50 chars, lowercase alphanumeric + hyphens (required) |
 | `--agents <slugs>` | Comma-separated merchant agent slugs (required) |
 | `--max-amount <dollars>` | Max amount per transaction (required) |
 | `--prompt-playback <text>` | Human-readable description (required) |
 | `--currency <code>` | Currency code (default: `USD`) |
 | `--recurring <type>` | `once`, `daily`, `weekly`, or `monthly` (default: `once`) |
-| `--budget <dollars>` | Lifetime budget |
+| `--budget <dollars>` | Lifetime budget cap |
 | `--expires <date>` | Expiry date (ISO 8601) |
 
-#### `web42 pay intent get --nick <nick>`
+#### `w42 intent get <nick>`
 
-Fetch an intent by nick. Caches locally if active.
+Fetch an intent by nick. Caches it locally if active.
 
-#### `web42 pay intent list`
+```bash
+w42 intent get starbucks-daily
+```
 
-List all your payment intents.
+#### `w42 intent list`
 
-#### `web42 pay intent revoke --nick <nick>`
+List all your payment intents and sync the local cache.
+
+```bash
+w42 intent list
+```
+
+#### `w42 intent revoke <nick>`
 
 Revoke an active intent.
 
-#### `web42 pay checkout`
+```bash
+w42 intent revoke starbucks-daily
+```
 
-Execute a payment against a matching intent (no human approval needed).
+---
+
+### `w42 serve`
+
+Start a local A2A server for your agent, bridging to an OpenClaw gateway.
 
 ```bash
-web42 pay checkout --cart '<json>' --agent @x~starbucks --intent starbucks-daily
+w42 serve
+w42 serve --port 3001 --url https://my-agent.ngrok.io --verbose
 ```
 
 | Option | Description |
 |---|---|
-| `--cart <json>` | CartMandate JSON (required) |
-| `--agent <slug>` | Merchant agent slug (required) |
-| `--intent <nick>` | Intent nick to use (required) |
+| `--port <port>` | Port to listen on (default: 4000) |
+| `--url <url>` | Public URL for registration and AgentCard (e.g. from ngrok) |
+| `--openclaw-port <port>` | OpenClaw gateway port (default: 18789) |
+| `--openclaw-token <token>` | OpenClaw gateway auth token (or `OPENCLAW_GATEWAY_TOKEN`) |
+| `--openclaw-agent <id>` | OpenClaw agent ID to target (default: `main`) |
+| `--client-id <id>` | Developer app client ID (or `W42_CLIENT_ID`) |
+| `--client-secret <secret>` | Developer app client secret (or `W42_CLIENT_SECRET`) |
+| `--visibility <vis>` | Marketplace visibility: `public` or `private` |
+| `--verbose` | Enable verbose request/response logging |
+
+Requires an `agent-card.json` in the current directory with at least a `name` field.
 
-#### `web42 pay sign create`
+---
 
-Create a payment session for human approval (when no matching intent exists).
+### `w42 register <url>`
+
+Register an agent with the Web42 Network. The URL must serve `/.well-known/agent-card.json`.
 
 ```bash
-web42 pay sign create --cart '<json>' --agent @x~bookstore
+w42 register https://my-agent.example.com
+w42 register https://my-agent.example.com --tags "nlp,summarization"
 ```
 
 | Option | Description |
 |---|---|
-| `--cart <json>` | CartMandate JSON (required) |
-| `--agent <slug>` | Merchant agent slug (required) |
+| `--tags <tags>` | Comma-separated discovery tags |
+| `--categories <cats>` | Comma-separated categories |
 
-Returns `{ code, signing_url }`. Present the URL to the user.
+---
 
-#### `web42 pay sign get <code>`
+### `w42 telemetry`
 
-Check the status of a payment session.
+Control usage telemetry.
 
 ```bash
-web42 pay sign get a1b2c3d4e5f6g7h8
+w42 telemetry         # Show current state
+w42 telemetry on      # Enable
+w42 telemetry off     # Disable
 ```
 
 ---
 
-### `web42 telemetry`
+## AP2 Payment flow
 
-Control usage telemetry.
+The full end-to-end flow for session-based (human approval) payments:
 
-```bash
-web42 telemetry         # Show current state
-web42 telemetry on      # Enable
-web42 telemetry off     # Disable
+```
+1. w42 send @merchant/agent "I want to buy X"
+   → Agent sends back a CartMandate
+   → CLI auto-saves it as tx_xxx, prints next step
+
+2. w42 cart sign tx_xxx
+   → Creates a payment session, returns signing_url
+   → User opens the URL and approves in the browser
+
+3. w42 cart poll tx_xxx
+   → Polls until status = "completed"
+   → Stores the full PaymentMandate on tx_xxx
+
+4. w42 send @merchant/agent "paid" --pay tx_xxx
+   → Sends the PaymentMandate to the merchant agent
+```
+
+For intent-based (automatic) payments, replace steps 2–3 with:
+
+```
+2. w42 cart checkout tx_xxx --intent <nick>
+   → Charges the saved card, stores PaymentMandate immediately
 ```
 
 ---

package/dist/commands/auth.js

@@ -59,7 +59,8 @@ authCommand
     }
     catch (error) {
         spinner.fail("Failed to start auth flow");
-        console.error(error);
+        console.error(chalk.red(String(error)));
+        console.error(chalk.dim("Check your network connection and try again."));
         process.exit(1);
     }
 });

package/dist/commands/cart.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const cartCommand: Command;

package/dist/commands/cart.js

@@ -0,0 +1,219 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import ora from "ora";
+import { ApiError, apiGet, apiPost, hintForError } from "../utils/api.js";
+import { requireAuth, setConfigValue } from "../utils/config.js";
+import { getTx, listTxs, updateTx } from "../utils/tx-store.js";
+function handleIntentError(err, intentNick) {
+    const code = err instanceof ApiError ? err.code : undefined;
+    const msg = err instanceof Error ? err.message : String(err);
+    switch (code) {
+        case "INTENT_NOT_FOUND":
+            setConfigValue(`intents.${intentNick}`, "");
+            console.error(chalk.red(`Intent "${intentNick}" not found.`));
+            console.error(chalk.dim(`Run \`w42 intent list\` to see available intents.`));
+            break;
+        case "INTENT_INACTIVE":
+        case "INTENT_EXPIRED":
+        case "INTENT_BUDGET_EXHAUSTED":
+            setConfigValue(`intents.${intentNick}`, "");
+            console.error(chalk.red(`Intent "${intentNick}" is no longer valid: ${msg}`));
+            console.error(chalk.dim(`Run \`w42 intent list\` to see available intents.`));
+            break;
+        case "INTENT_PERIOD_BUDGET_EXHAUSTED":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            console.error(chalk.dim(`Try again later or run \`w42 intent list\` to find another intent.`));
+            break;
+        case "INTENT_AMOUNT_EXCEEDED":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            console.error(chalk.dim(`Use \`w42 cart sign\` for manual approval instead.`));
+            break;
+        case "INTENT_AGENT_NOT_AUTHORIZED":
+            console.error(chalk.red(`Intent "${intentNick}" does not cover this merchant.`));
+            console.error(chalk.dim(`Use \`w42 cart sign\` for manual approval instead.`));
+            break;
+        case "INTENT_CURRENCY_MISMATCH":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            break;
+        default:
+            console.error(chalk.red(`Checkout failed: ${msg}`));
+    }
+    process.exit(1);
+}
+export const cartCommand = new Command("cart").description("Manage AP2 cart payments — sign, poll, checkout, and list");
+// ─── sign ─────────────────────────────────────────────────
+cartCommand
+    .command("sign")
+    .description("Create a payment session for human approval")
+    .argument("<tx_id>", "Transaction ID from tx-store")
+    .action(async (txId) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    // Check that the cart supports WEB42_WALLET payment method
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const methodData = pr?.method_data;
+        const supportsWeb42 = methodData?.some((m) => m.supported_methods === "WEB42_WALLET");
+        if (!supportsWeb42) {
+            console.error(chalk.yellow(`⚠ This cart does not accept Web42 Wallet as a payment method.\n` +
+                `  Tell your shopping agent: "I cannot pay with Web42 Wallet — ` +
+                `please ask the user how they would like to proceed."`));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(chalk.red("Could not read payment method data from cart"));
+        process.exit(1);
+    }
+    // Extract total from stored cart
+    let totalCents = 0;
+    let currency = "usd";
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const details = pr?.details;
+        const total = details?.total;
+        totalCents = Math.round(total.amount.value * 100);
+        currency = total.amount.currency.toLowerCase();
+    }
+    catch {
+        console.error(chalk.red("Could not extract total from stored cart"));
+        process.exit(1);
+    }
+    const spinner = ora("Creating payment session...").start();
+    try {
+        const res = await apiPost("/api/pay/session", {
+            agent_slug: tx.agentSlug,
+            cart: tx.cartMandate,
+            total_cents: totalCents,
+            currency,
+        });
+        spinner.stop();
+        updateTx(txId, {
+            sessionCode: res.code,
+            signingUrl: res.signing_url,
+            status: "session_created",
+        });
+        console.log(JSON.stringify({ tx: txId, signing_url: res.signing_url }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to create session");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+// ─── poll ─────────────────────────────────────────────────
+cartCommand
+    .command("poll")
+    .description("Check the status of a payment session")
+    .argument("<tx_id>", "Transaction ID")
+    .action(async (txId) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    if (!tx.sessionCode) {
+        console.error(chalk.red(`No session created yet. Run: w42 cart sign ${txId}`));
+        process.exit(1);
+    }
+    const spinner = ora("Fetching session...").start();
+    try {
+        const res = await apiGet(`/api/pay/session/${encodeURIComponent(tx.sessionCode)}`);
+        spinner.stop();
+        if (res.status === "completed" && res.payment_mandate) {
+            updateTx(txId, {
+                paymentMandate: res.payment_mandate,
+                status: "approved",
+            });
+        }
+        console.log(JSON.stringify({ tx: txId, ...res }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to fetch session");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+// ─── checkout ─────────────────────────────────────────────
+cartCommand
+    .command("checkout")
+    .description("Execute a payment against a matching intent (no human needed)")
+    .argument("<tx_id>", "Transaction ID from tx-store")
+    .requiredOption("--intent <nick>", "Intent nick to use")
+    .action(async (txId, opts) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    // Check that the cart supports WEB42_WALLET payment method
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const methodData = pr?.method_data;
+        const supportsWeb42 = methodData?.some((m) => m.supported_methods === "WEB42_WALLET");
+        if (!supportsWeb42) {
+            console.error(chalk.yellow(`⚠ This cart does not accept Web42 Wallet as a payment method.\n` +
+                `  Tell your shopping agent: "I cannot pay with Web42 Wallet — ` +
+                `please ask the user how they would like to proceed."`));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(chalk.red("Could not read payment method data from cart"));
+        process.exit(1);
+    }
+    const spinner = ora("Processing checkout...").start();
+    try {
+        const res = await apiPost("/api/pay/checkout", {
+            cart: tx.cartMandate,
+            agent_slug: tx.agentSlug,
+            intent_nick: opts.intent,
+        });
+        spinner.stop();
+        if (res.payment_mandate) {
+            updateTx(txId, {
+                paymentMandate: res.payment_mandate,
+                status: "approved",
+            });
+        }
+        console.log(JSON.stringify({ tx: txId, ...res }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Checkout failed");
+        handleIntentError(err, opts.intent);
+    }
+});
+// ─── list ─────────────────────────────────────────────────
+cartCommand
+    .command("list")
+    .description("List local payment transactions")
+    .option("--status <status>", "Filter by status (cart_received, session_created, approved, sent)")
+    .action((opts) => {
+    const txs = listTxs(opts.status);
+    if (txs.length === 0) {
+        console.log(chalk.dim("No transactions found."));
+        return;
+    }
+    for (const tx of txs) {
+        const cart = tx.cartMandate;
+        const contents = cart?.contents;
+        const pr = contents?.payment_request;
+        const details = pr?.details;
+        const total = details?.total;
+        const amount = total?.amount
+            ? `${total.amount.currency} ${total.amount.value?.toFixed(2)}`
+            : "?";
+        console.log(`${chalk.cyan(tx.id)}  ${chalk.dim(tx.status.padEnd(16))}  ${amount}  ${chalk.dim(tx.agentSlug)}`);
+    }
+});

package/dist/commands/intent.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const intentCommand: Command;

package/dist/commands/intent.js

@@ -0,0 +1,105 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import ora from "ora";
+import { apiGet, apiPost, hintForError } from "../utils/api.js";
+import { requireAuth, setConfigValue } from "../utils/config.js";
+export const intentCommand = new Command("intent").description("Manage payment intents");
+intentCommand
+    .command("get")
+    .description("Fetch an intent by nick")
+    .argument("<nick>", "Intent nick")
+    .action(async (nick) => {
+    requireAuth();
+    const spinner = ora(`Fetching intent ${nick}...`).start();
+    try {
+        const res = await apiGet(`/api/pay/intent/${encodeURIComponent(nick)}`);
+        spinner.stop();
+        if (res.status === "active") {
+            setConfigValue(`intents.${nick}`, JSON.stringify(res));
+        }
+        console.log(JSON.stringify(res, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to fetch intent");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+intentCommand
+    .command("list")
+    .description("List all your intents")
+    .action(async () => {
+    requireAuth();
+    const spinner = ora("Fetching intents...").start();
+    try {
+        const intents = await apiGet("/api/pay/intent");
+        spinner.stop();
+        for (const intent of intents) {
+            if (intent.status === "active" && typeof intent.nick === "string") {
+                setConfigValue(`intents.${intent.nick}`, JSON.stringify(intent));
+            }
+        }
+        console.log(JSON.stringify(intents, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to list intents");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+intentCommand
+    .command("revoke")
+    .description("Revoke an active intent")
+    .argument("<nick>", "Intent nick")
+    .action(async (nick) => {
+    requireAuth();
+    const spinner = ora(`Revoking intent ${nick}...`).start();
+    try {
+        const res = await apiPost(`/api/pay/intent/${encodeURIComponent(nick)}/revoke`, {});
+        spinner.stop();
+        setConfigValue(`intents.${nick}`, "");
+        console.log(JSON.stringify(res, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to revoke intent");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+intentCommand
+    .command("propose")
+    .description("Generate an intent creation URL for the user to authorize in the browser")
+    .requiredOption("--nick <nick>", "Short identifier for the intent")
+    .requiredOption("--agents <slugs>", "Comma-separated merchant agent slugs (e.g. @x~starbucks)")
+    .requiredOption("--max-amount <dollars>", "Max amount per transaction in dollars")
+    .requiredOption("--prompt-playback <text>", "Human-readable description of the intent")
+    .option("--currency <code>", "Currency code", "USD")
+    .option("--recurring <type>", "Recurring type: once, daily, weekly, monthly", "once")
+    .option("--budget <dollars>", "Lifetime budget in dollars")
+    .option("--expires <date>", "Expiry date (ISO 8601)")
+    .action(async (opts) => {
+    const cfg = requireAuth();
+    const username = cfg.username;
+    if (!username) {
+        console.error(chalk.red("No username found. Please log in again."));
+        process.exit(1);
+    }
+    const baseUrl = cfg.apiUrl ?? "https://web42-network.vercel.app";
+    const params = new URLSearchParams({
+        nick: opts.nick,
+        agents: opts.agents,
+        max_amount: opts.maxAmount,
+        currency: opts.currency,
+        recurring: opts.recurring,
+        prompt_playback: opts.promptPlayback,
+    });
+    if (opts.budget)
+        params.set("budget", opts.budget);
+    if (opts.expires)
+        params.set("expires_at", opts.expires);
+    const url = `${baseUrl}/@${username}/intents/create?${params.toString()}`;
+    console.log(JSON.stringify({ url }, null, 2));
+});

package/dist/commands/register.js

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { Command } from "commander";
 import inquirer from "inquirer";
 import ora from "ora";
-import { apiGet, apiPost } from "../utils/api.js";
+import { apiGet, apiPost, hintForError } from "../utils/api.js";
 import { getConfig, isAuthenticated } from "../utils/config.js";
 function toSlugPart(name) {
     return name
@@ -35,6 +35,7 @@ export const registerCommand = new Command("register")
     catch (err) {
         cardSpinner.fail("Could not fetch agent card");
         console.error(chalk.red(`  ${cardUrl}: ${String(err)}`));
+        console.error(chalk.dim("  Make sure the agent server is running and serving /.well-known/agent-card.json"));
         process.exit(1);
     }
     cardSpinner.stop();
@@ -142,6 +143,7 @@ export const registerCommand = new Command("register")
     catch (err) {
         registerSpinner.fail("Registration failed");
         console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
         process.exit(1);
     }
 });

package/dist/commands/search.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
-import { apiGet } from "../utils/api.js";
+import { apiGet, hintForError } from "../utils/api.js";
 import { printBanner } from "../utils/banner.js";
 import { getConfig } from "../utils/config.js";
 function getCardName(card) {
@@ -71,6 +71,7 @@ export const searchCommand = new Command("search")
         spinner.stop();
         if (agents.length === 0) {
             console.log(chalk.yellow(`No agents found for "${query}".`));
+            console.log(chalk.dim("Try different keywords or a broader search term."));
             return;
         }
         const limit = parseInt(opts.limit, 10) || 10;
@@ -112,6 +113,7 @@ export const searchCommand = new Command("search")
     catch (error) {
         spinner.fail("Search failed");
         console.error(chalk.red(String(error)));
+        console.error(chalk.dim(hintForError(error)));
         process.exit(1);
     }
 });

package/dist/commands/send.js

@@ -4,8 +4,8 @@ import { Command } from "commander";
 import ora from "ora";
 import { v4 as uuidv4 } from "uuid";
 import { isCartMandatePart, parseCartMandate } from "@web42/auth";
-import { apiPost } from "../utils/api.js";
-import { getConfig, getConfigValue, isTelemetryEnabled, requireAuth, setConfigValue } from "../utils/config.js";
+import { apiPost, hintForError } from "../utils/api.js";
+import { getCachedIntents, getConfig, getConfigValue, isTelemetryEnabled, requireAuth, setConfigValue } from "../utils/config.js";
 import { getTx, saveTx, updateTx } from "../utils/tx-store.js";
 function isUrl(s) {
     return s.startsWith("http://") || s.startsWith("https://");
@@ -32,16 +32,42 @@ function printPart(part, agentSlug) {
             const cart = parseCartMandate(part);
             if (cart) {
                 const total = cart.contents.payment_request.details.total;
+                const slug = agentSlug ?? "unknown";
                 const txId = saveTx({
                     cartMandate: cart,
-                    agentSlug: agentSlug ?? "unknown",
+                    agentSlug: slug,
                 });
                 console.log(chalk.cyan(`\n[CartMandate] ${txId}`));
                 for (const item of cart.contents.payment_request.details.displayItems) {
                     console.log(`  ${item.label}: ${item.amount.currency} ${item.amount.value.toFixed(2)}`);
                 }
                 console.log(chalk.bold(`  Total: ${total.amount.currency} ${total.amount.value.toFixed(2)}`));
-                console.log(chalk.dim(`\nTo pay: w42 pay sign create --tx ${txId}`));
+                // Check locally-cached intents for auto-checkout hints
+                const totalCents = Math.round(total.amount.value * 100);
+                const cartCurrency = total.amount.currency.toLowerCase();
+                const now = new Date();
+                const matchingIntents = getCachedIntents().filter((intent) => {
+                    if (intent.status !== "active")
+                        return false;
+                    if (intent.expires_at && new Date(intent.expires_at) <= now)
+                        return false;
+                    if (!intent.agent_slugs.includes(slug))
+                        return false;
+                    if (totalCents > intent.max_amount_cents)
+                        return false;
+                    if (intent.currency.toLowerCase() !== cartCurrency)
+                        return false;
+                    return true;
+                });
+                if (matchingIntents.length > 0) {
+                    console.log(chalk.green(`\n  Auto-checkout available:`));
+                    for (const intent of matchingIntents) {
+                        console.log(chalk.green(`    w42 cart checkout ${txId} --intent ${intent.nick}`));
+                    }
+                }
+                else {
+                    console.log(chalk.dim(`\nTo pay: w42 cart sign ${txId}`));
+                }
                 return;
             }
         }
@@ -103,7 +129,7 @@ export const sendCommand = new Command("send")
     .option("--new", "Start a new conversation (clears saved context)")
     .option("--context <id>", "Use a specific context ID")
     .option("--task-id <id>", "Reply to a specific task (e.g. one in input-required state)")
-    .option("--pay <tx_id>", "Attach PaymentMandate from a transaction (use tx ID from w42 pay list)")
+    .option("--pay <tx_id>", "Attach PaymentMandate from a transaction (use tx ID from w42 cart list)")
     .action(async (rawAgent, userMessage, opts) => {
     // Normalize slug: @user/name → @user~name (DB format)
     const agent = rawAgent.includes("/") && !isUrl(rawAgent)
@@ -135,6 +161,7 @@ export const sendCommand = new Command("send")
             catch (err) {
                 spinner.fail("Failed to get auth token");
                 console.error(chalk.red(String(err)));
+                console.error(chalk.dim(hintForError(err)));
                 process.exit(1);
             }
         }
@@ -165,6 +192,7 @@ export const sendCommand = new Command("send")
             catch (err) {
                 spinner.fail(`Failed to authenticate with ${agent}`);
                 console.error(chalk.red(String(err)));
+                console.error(chalk.dim(hintForError(err)));
                 process.exit(1);
             }
         }
@@ -218,15 +246,15 @@ export const sendCommand = new Command("send")
         if (opts.pay) {
             const tx = getTx(opts.pay);
             if (!tx) {
-                console.error(chalk.red(`Transaction ${opts.pay} not found. Run: w42 pay list`));
+                console.error(chalk.red(`Transaction ${opts.pay} not found. Run: w42 cart list`));
                 process.exit(1);
             }
             if (tx.status === "cart_received") {
-                console.error(chalk.red(`Session not created yet. Run: w42 pay sign create --tx ${opts.pay}`));
+                console.error(chalk.red(`Session not created yet. Run: w42 cart sign ${opts.pay}`));
                 process.exit(1);
             }
             if (tx.status === "session_created") {
-                console.error(chalk.red(`Payment not yet approved. Run: w42 pay sign get ${opts.pay}`));
+                console.error(chalk.red(`Payment not yet approved. Run: w42 cart poll ${opts.pay}`));
                 process.exit(1);
             }
             if (!tx.paymentMandate) {

package/dist/commands/serve.js

@@ -135,6 +135,7 @@ export const serveCommand = new Command("serve")
     }
     catch {
         console.error(chalk.red("Failed to parse agent-card.json."));
+        console.error(chalk.dim("Validate the file with a JSON linter — it may have a syntax error."));
         process.exit(1);
     }
     const agentName = cardData.name ?? "Untitled Agent";

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { authCommand } from "./commands/auth.js";
-import { payCommand } from "./commands/pay.js";
+import { cartCommand } from "./commands/cart.js";
+import { intentCommand } from "./commands/intent.js";
 import { registerCommand } from "./commands/register.js";
 import { searchCommand } from "./commands/search.js";
 import { sendCommand } from "./commands/send.js";
@@ -22,7 +23,8 @@ program
     }
 });
 program.addCommand(authCommand);
-program.addCommand(payCommand);
+program.addCommand(cartCommand);
+program.addCommand(intentCommand);
 program.addCommand(registerCommand);
 program.addCommand(searchCommand);
 program.addCommand(sendCommand);

package/dist/utils/api.d.ts

@@ -1,5 +1,12 @@
 export declare function apiRequest(path: string, options?: RequestInit): Promise<Response>;
+export declare class ApiError extends Error {
+    readonly code: string | undefined;
+    readonly status: number;
+    constructor(message: string, code: string | undefined, status: number);
+}
 export declare function apiGet<T>(path: string): Promise<T>;
 export declare function apiPost<T>(path: string, data: unknown): Promise<T>;
+/** Returns a short contextual hint based on the error type. */
+export declare function hintForError(err: unknown): string;
 export declare function apiDelete<T>(path: string): Promise<T>;
 export declare function apiFormData<T>(path: string, formData: FormData): Promise<T>;

package/dist/utils/api.js

@@ -14,11 +14,21 @@ export async function apiRequest(path, options = {}) {
         headers,
     });
 }
+export class ApiError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "ApiError";
+    }
+}
 export async function apiGet(path) {
     const res = await apiRequest(path);
     if (!res.ok) {
         const body = await res.json().catch(() => ({}));
-        throw new Error(body.error || `API error: ${res.status}`);
+        throw new ApiError(body.error || `API error: ${res.status}`, body.code, res.status);
     }
     return res.json();
 }
@@ -29,10 +39,22 @@ export async function apiPost(path, data) {
     });
     if (!res.ok) {
         const body = await res.json().catch(() => ({}));
-        throw new Error(body.error || `API error: ${res.status}`);
+        throw new ApiError(body.error || `API error: ${res.status}`, body.code, res.status);
     }
     return res.json();
 }
+/** Returns a short contextual hint based on the error type. */
+export function hintForError(err) {
+    if (err instanceof ApiError) {
+        if (err.status === 401)
+            return "Run `w42 auth login` to reauthenticate.";
+        if (err.status === 403)
+            return "You don't have permission to do this.";
+        if (err.status >= 500)
+            return "Server error — try again later.";
+    }
+    return "Check your network connection and try again.";
+}
 export async function apiDelete(path) {
     const res = await apiRequest(path, { method: "DELETE" });
     if (!res.ok) {

package/dist/utils/config.d.ts

@@ -22,6 +22,18 @@ export declare function isAuthenticated(): boolean;
 export declare function requireAuth(): W42Config;
 export declare function setConfigValue(key: string, value: string): void;
 export declare function getConfigValue(key: string): string | undefined;
+export interface CachedIntent {
+    nick: string;
+    agent_slugs: string[];
+    max_amount_cents: number;
+    currency: string;
+    status: string;
+    expires_at?: string | null;
+    spent_cents: number;
+    budget_cents?: number | null;
+}
+/** Return all locally-cached intents that are still plausibly active. */
+export declare function getCachedIntents(): CachedIntent[];
 export declare function isTelemetryEnabled(): boolean;
 export declare function setTelemetry(enabled: boolean): void;
 export {};

package/dist/utils/config.js

@@ -59,6 +59,27 @@ export function getConfigValue(key) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return config.get(key);
 }
+/** Return all locally-cached intents that are still plausibly active. */
+export function getCachedIntents() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const intentsMap = config.get("intents");
+    if (!intentsMap)
+        return [];
+    const results = [];
+    for (const raw of Object.values(intentsMap)) {
+        if (!raw)
+            continue;
+        try {
+            const intent = typeof raw === "string" ? JSON.parse(raw) : raw;
+            if (intent && typeof intent === "object")
+                results.push(intent);
+        }
+        catch {
+            // skip corrupted entry
+        }
+    }
+    return results;
+}
 export function isTelemetryEnabled() {
     return config.get("telemetry") !== false;
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "0.1.20";
+export declare const CLI_VERSION = "0.1.21";

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.20";
+export const CLI_VERSION = "0.1.21";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web42/w42",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "CLI for the Web42 Agent Network — discover, register, and communicate with A2A agents",
   "type": "module",
   "bin": {

package/dist/commands/pay.d.ts

@@ -1,2 +0,0 @@
-import { Command } from "commander";
-export declare const payCommand: Command;

package/dist/commands/pay.js

@@ -1,260 +0,0 @@
-import chalk from "chalk";
-import { Command } from "commander";
-import ora from "ora";
-import { apiGet, apiPost } from "../utils/api.js";
-import { requireAuth, setConfigValue, } from "../utils/config.js";
-import { getTx, listTxs, updateTx } from "../utils/tx-store.js";
-// ─── Intent ───────────────────────────────────────────────
-const intentCommand = new Command("intent").description("Manage payment intents");
-intentCommand
-    .command("get")
-    .description("Fetch an intent by nick")
-    .requiredOption("--nick <nick>", "Intent nick")
-    .action(async (opts) => {
-    requireAuth();
-    const spinner = ora(`Fetching intent ${opts.nick}...`).start();
-    try {
-        const res = await apiGet(`/api/pay/intent/${encodeURIComponent(opts.nick)}`);
-        spinner.stop();
-        // Cache if active
-        if (res.status === "active") {
-            setConfigValue(`intents.${opts.nick}`, JSON.stringify(res));
-        }
-        console.log(JSON.stringify(res, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Failed to fetch intent");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-intentCommand
-    .command("list")
-    .description("List all your intents")
-    .action(async () => {
-    requireAuth();
-    const spinner = ora("Fetching intents...").start();
-    try {
-        const intents = await apiGet("/api/pay/intent");
-        spinner.stop();
-        // Sync active intents to cache, remove stale ones
-        const activeNicks = new Set();
-        for (const intent of intents) {
-            if (intent.status === "active" && typeof intent.nick === "string") {
-                activeNicks.add(intent.nick);
-                setConfigValue(`intents.${intent.nick}`, JSON.stringify(intent));
-            }
-        }
-        console.log(JSON.stringify(intents, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Failed to list intents");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-intentCommand
-    .command("revoke")
-    .description("Revoke an active intent")
-    .requiredOption("--nick <nick>", "Intent nick")
-    .action(async (opts) => {
-    requireAuth();
-    const spinner = ora(`Revoking intent ${opts.nick}...`).start();
-    try {
-        const res = await apiPost(`/api/pay/intent/${encodeURIComponent(opts.nick)}/revoke`, {});
-        spinner.stop();
-        // Remove from cache
-        setConfigValue(`intents.${opts.nick}`, "");
-        console.log(JSON.stringify(res, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Failed to revoke intent");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-intentCommand
-    .command("propose")
-    .description("Generate an intent creation URL for the user to authorize in the browser")
-    .requiredOption("--nick <nick>", "Short identifier for the intent")
-    .requiredOption("--agents <slugs>", "Comma-separated merchant agent slugs (e.g. @x~starbucks)")
-    .requiredOption("--max-amount <dollars>", "Max amount per transaction in dollars")
-    .requiredOption("--prompt-playback <text>", "Human-readable description of the intent")
-    .option("--currency <code>", "Currency code", "USD")
-    .option("--recurring <type>", "Recurring type: once, daily, weekly, monthly", "once")
-    .option("--budget <dollars>", "Lifetime budget in dollars")
-    .option("--expires <date>", "Expiry date (ISO 8601)")
-    .action(async (opts) => {
-    const cfg = requireAuth();
-    const username = cfg.username;
-    if (!username) {
-        console.error(chalk.red("No username found. Please log in again."));
-        process.exit(1);
-    }
-    const baseUrl = cfg.apiUrl ?? "https://web42-network.vercel.app";
-    const params = new URLSearchParams({
-        nick: opts.nick,
-        agents: opts.agents,
-        max_amount: opts.maxAmount,
-        currency: opts.currency,
-        recurring: opts.recurring,
-        prompt_playback: opts.promptPlayback,
-    });
-    if (opts.budget)
-        params.set("budget", opts.budget);
-    if (opts.expires)
-        params.set("expires_at", opts.expires);
-    const url = `${baseUrl}/@${username}/intents/create?${params.toString()}`;
-    console.log(JSON.stringify({ url }, null, 2));
-});
-// ─── Checkout ─────────────────────────────────────────────
-const checkoutCommand = new Command("checkout")
-    .description("Execute a payment against a matching intent (no human needed)")
-    .requiredOption("--tx <id>", "Transaction ID from tx-store")
-    .requiredOption("--intent <nick>", "Intent nick to use")
-    .action(async (opts) => {
-    requireAuth();
-    const tx = getTx(opts.tx);
-    if (!tx) {
-        console.error(chalk.red(`Transaction ${opts.tx} not found. Run: w42 pay list`));
-        process.exit(1);
-    }
-    const spinner = ora("Processing checkout...").start();
-    try {
-        const res = await apiPost("/api/pay/checkout", {
-            cart: tx.cartMandate,
-            agent_slug: tx.agentSlug,
-            intent_nick: opts.intent,
-        });
-        spinner.stop();
-        // Store the payment mandate on the tx
-        if (res.payment_mandate) {
-            updateTx(opts.tx, {
-                paymentMandate: res.payment_mandate,
-                status: "approved",
-            });
-        }
-        console.log(JSON.stringify({ tx: opts.tx, ...res }, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Checkout failed");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-// ─── Sign (payment session for human approval) ───────────
-const signCommand = new Command("sign").description("Create a payment session for human approval");
-signCommand
-    .command("create")
-    .description("Create a new payment session for human approval")
-    .requiredOption("--tx <id>", "Transaction ID from tx-store")
-    .action(async (opts) => {
-    requireAuth();
-    const tx = getTx(opts.tx);
-    if (!tx) {
-        console.error(chalk.red(`Transaction ${opts.tx} not found. Run: w42 pay list`));
-        process.exit(1);
-    }
-    // Extract total from stored cart
-    let totalCents = 0;
-    let currency = "usd";
-    try {
-        const contents = tx.cartMandate.contents;
-        const pr = contents?.payment_request;
-        const details = pr?.details;
-        const total = details?.total;
-        totalCents = Math.round(total.amount.value * 100);
-        currency = total.amount.currency.toLowerCase();
-    }
-    catch {
-        console.error(chalk.red("Could not extract total from stored cart"));
-        process.exit(1);
-    }
-    const spinner = ora("Creating payment session...").start();
-    try {
-        const res = await apiPost("/api/pay/session", {
-            agent_slug: tx.agentSlug,
-            cart: tx.cartMandate,
-            total_cents: totalCents,
-            currency,
-        });
-        spinner.stop();
-        updateTx(opts.tx, {
-            sessionCode: res.code,
-            signingUrl: res.signing_url,
-            status: "session_created",
-        });
-        console.log(JSON.stringify({ tx: opts.tx, signing_url: res.signing_url }, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Failed to create session");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-signCommand
-    .command("get")
-    .description("Check the status of a payment session")
-    .argument("<tx_id>", "Transaction ID")
-    .action(async (txId) => {
-    requireAuth();
-    const tx = getTx(txId);
-    if (!tx) {
-        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 pay list`));
-        process.exit(1);
-    }
-    if (!tx.sessionCode) {
-        console.error(chalk.red(`No session created yet. Run: w42 pay sign create --tx ${txId}`));
-        process.exit(1);
-    }
-    const spinner = ora("Fetching session...").start();
-    try {
-        const res = await apiGet(`/api/pay/session/${encodeURIComponent(tx.sessionCode)}`);
-        spinner.stop();
-        // If session is completed, store the payment mandate
-        if (res.status === "completed" && res.payment_token) {
-            updateTx(txId, {
-                paymentMandate: res.payment_mandate ?? {
-                    payment_mandate_contents: {},
-                    user_authorization: res.payment_token,
-                },
-                status: "approved",
-            });
-        }
-        console.log(JSON.stringify({ tx: txId, ...res }, null, 2));
-    }
-    catch (err) {
-        spinner.fail("Failed to fetch session");
-        console.error(chalk.red(String(err)));
-        process.exit(1);
-    }
-});
-// ─── List (transactions) ──────────────────────────────────
-const listCommand = new Command("list")
-    .description("List local payment transactions")
-    .option("--status <status>", "Filter by status (cart_received, session_created, approved, sent)")
-    .action((opts) => {
-    const txs = listTxs(opts.status);
-    if (txs.length === 0) {
-        console.log(chalk.dim("No transactions found."));
-        return;
-    }
-    for (const tx of txs) {
-        const cart = tx.cartMandate;
-        const contents = cart?.contents;
-        const pr = contents?.payment_request;
-        const details = pr?.details;
-        const total = details?.total;
-        const amount = total?.amount
-            ? `${total.amount.currency} ${total.amount.value?.toFixed(2)}`
-            : "?";
-        console.log(`${chalk.cyan(tx.id)}  ${chalk.dim(tx.status.padEnd(16))}  ${amount}  ${chalk.dim(tx.agentSlug)}`);
-    }
-});
-// ─── Root pay command ─────────────────────────────────────
-export const payCommand = new Command("pay")
-    .description("AP2 payment mandates — intents, checkout, signing")
-    .addCommand(intentCommand)
-    .addCommand(checkoutCommand)
-    .addCommand(signCommand)
-    .addCommand(listCommand);