@getbags/cash 0.3.0 → 0.4.0

package/README.md

@@ -13,7 +13,7 @@ bags --help
 
 ### Agent skill (prompt paste)
 
-Hosted skill: https://www.getbags.app/wallet/skill.md
+Hosted skill (agents): https://www.getbags.app/wallet/skill.md
 
 Paste into Cursor / Claude / Codex / etc.:
 
@@ -21,8 +21,9 @@ Paste into Cursor / Claude / Codex / etc.:
 Set up https://www.getbags.app/wallet/skill.md
 ```
 
+Human install guide: https://www.getbags.app/wallet/install  
 Human onboard (bonus + same prompt): https://www.getbags.app/wallet/onboard  
-Staging: use `https://staging.getbags.app/wallet/skill.md` (or set `BAGS_API_URL`).
+Staging skill (agents): use `https://staging.getbags.app/wallet/skill.md` (or set `BAGS_API_URL`).
 
 ## Workflow
 
@@ -39,6 +40,7 @@ Staging: use `https://staging.getbags.app/wallet/skill.md` (or set `BAGS_API_URL
 | `search <query>`            | NL search across BAGS + ecosystem index                         |
 | `check <url>`               | Probe schema + exact quote **without paying**                   |
 | `fetch <url> [flags]`       | Pay and proxy an x402 endpoint                                  |
+| `result <id> [flags]`       | Retrieve retained output without another paid call              |
 | `transactions`              | Spend / ledger history                                          |
 | `policies get\|set`         | Read or update spend policies                                   |
 | `keys create\|list\|revoke` | Per-agent wallet keys                                           |
@@ -49,7 +51,7 @@ Staging: use `https://staging.getbags.app/wallet/skill.md` (or set `BAGS_API_URL
 
 `init` flags: `--dry-run`, `--client cursor|claude|codex` (force-create even without a marker directory; repeatable or comma-separated), `--scope project|user` (default `user` — ambient on this machine; use `--scope project` for committable repo-local config). After a successful apply, restart the agent client, then run `bags doctor`.
 
-Fetch / check flags: `-m/--method`, `-b/--body` (JSON string), `--max-price-cents` (fetch), `--format json|pretty`.
+Fetch / check flags: `-m/--method`, `-b/--body` (JSON string), `--max-price-cents` and `--payment-protocol x402|mpp|auto` (fetch), `--format json|pretty` (check). Result flags: `--field`, `--offset`, `--limit`.
 
 ## Env
 
@@ -79,34 +81,49 @@ Token at `~/.bags/credentials.json`. Hosted custody — no local private keys. M
 
 ## Publishing `@getbags/cash`
 
-### Local (preferred dry-run)
+Preferred path is CI via OIDC trusted publishing (no long-lived npm token).
 
-From the repo root:
+### CI (tag or dispatch)
+
+GitHub Action: [`.github/workflows/publish-cash.yml`](../../.github/workflows/publish-cash.yml)
+
+1. Bump `version` in `packages/cli/package.json`
+2. Tag and push: `git tag cash-v0.3.1 && git push origin cash-v0.3.1` (tag must match package version)
+3. The workflow builds, tests, and `npm publish`s via GitHub Actions OIDC (`id-token: write`). Configure the trusted publisher once on npmjs.com → `@getbags/cash` → Settings → Trusted publisher (repo `getbagsapp/agentic-payments`, workflow `publish-cash.yml`).
+4. After publish it retries `npm view` until the version resolves (or fails), and reports whether provenance attestations exist.
+
+`workflow_dispatch` defaults to dry-run. To publish manually, always pass an explicit ref (dispatch without `--ref` uses the default branch tip):
 
 ```bash
-bun run publish:cash --dry-run   # install + build + test; never publishes
-bun run publish:cash             # same as dry-run unless NPM_TOKEN is set
-bun run publish:cash --publish   # requires NPM_TOKEN; runs npm publish --access public
+gh workflow run publish-cash.yml --ref cash-v0.3.1 -f dry_run=false
 ```
 
-Or manually:
+`NPM_TOKEN` is an optional emergency fallback only; OIDC is the primary auth. A missing token does not dry-run a real publish attempt — the job fails if OIDC fails and no fallback exists.
+
+**Provenance:** OIDC trusted publishing authenticates the publisher; provenance attestations are a separate Sigstore statement. npm does not issue provenance for packages built from a **private** source repository, so `@getbags/cash` will not show a Provenance badge while `getbagsapp/agentic-payments` is private — even though trusted publishing works. Do not add `--provenance` until the source repo is public (npm rejects private-source provenance with HTTP 422). After that cutover, look for the Provenance badge on the version page and a non-404 from `https://registry.npmjs.org/-/npm/v1/attestations/@getbags%2Fcash@<version>`.
+
+### Local dry-run
 
 ```bash
-cd packages/cli
-bun install && bun run build && bun run test
-# npm publish --access public   # only with npm auth for @getbags
+bun run publish:cash --dry-run   # install + build + test; never publishes
 ```
 
 `prepublishOnly` runs the build. Version bumps are manual in `packages/cli/package.json`.
 
-### CI (tag automation)
+## Precise payments and retained output
 
-GitHub Action: [`.github/workflows/publish-cash.yml`](../../.github/workflows/publish-cash.yml)
+Public `search` and `discover` work without credentials. Paid calls still require a wallet token. Receipts preserve six-decimal USDC and fractional cents. Catalog prices are indicative; check the selected operation's schemas, mode and network before execution. Provider success and target-content success are separate facts.
 
-1. Bump `version` in `packages/cli/package.json`
-2. Tag and push: `git tag cash-v0.2.0 && git push origin cash-v0.2.0` (tag must match package version)
-3. Workflow builds and tests. It publishes only when repo secret `NPM_TOKEN` is set; otherwise the job succeeds as a dry-run (no npm publish).
+`bags result <id> --field response.items --offset 0 --limit 20` and the `wallet_result` MCP tool read retained output without another provider call or payment. Results are private to the wallet and expire after 24 hours. Authentication fields are redacted; provider asset URLs may expire earlier. The fetch API and MCP accept `result_mode: "summary"`.
+
+MPP supports bounded one-shot `tempo:charge` with explicit chain/currency checks. Hosted session opening is disabled until durable close can be confirmed. `bags sessions list` shows existing session reservations. Hosted `sessions close` currently reports unsupported cleanup and keeps the hold; it does not report the channel closed. Existing channels and reservations remain owned when cleanup fails.
+
+### Task fit, accepted jobs and asset copies (0.4.0)
+
+`bags search "email from LinkedIn" --requirements '{"inputs":{"depth":"full"},"outputs":["email"],"unit":"contact"}' --format json` returns advertised capability fit, health and conservative cost comparisons. Unknown controls, contracts, units or funding remain unknown. Prices are indicative: check the exact method/body before paying.
+
+`bags result <id> --refresh` explicitly makes one unpaid GET to an advertised async status URL. It never repeats the initial request, pays a status challenge or forwards your wallet credentials. Providers without a safe polling contract remain explicit; terminal costs are separately labelled when provider-reported.
 
-`workflow_dispatch` defaults to dry-run (build/test only). Set `dry_run=false` to attempt publish (still skips cleanly if `NPM_TOKEN` is missing).
+`bags result <id> --retain-asset '<exact-advertised-url>'` explicitly requests a private copy. At most two assets per result, 2 MiB each; copies expire with the retained result. The response includes measured size/SHA256 and an authenticated download URL. Use this option separately from field/page/refresh flags. Plain `bags result <id>` remains a stored read.
 
-**Do not publish** unless `NPM_TOKEN` is available and you intend a release. Scoped packages typically need an automation token with 2FA bypass for CI. Add the secret under GitHub → Settings → Secrets and variables → Actions (`NPM_TOKEN`).
+Registration returns `reusable_skill.markdown`, a small origin/task pointer that refreshes discovery and contracts on each use. It includes no credential or spending authority.

package/SKILL.md

@@ -3,13 +3,14 @@ name: bags-cash
 description: |
     Pay x402-protected APIs with a BAGS hosted agent wallet (USDC credits, server-side policies).
     Use when the user has a BAGS invite code, wants to call paid APIs via BAGS Cash / BAGS Wallet,
-    or mentions bags wallet / bags cash / getbags / x402 micropayments.
+    or needs web research, scraping, enrichment, social data, or media generation with no suitable configured tool.
+    Prefer the user-selected provider and existing dedicated MCP/API tools; discover paid alternatives only within the user’s task and budget.
 
     TRIGGERS: x402, paid API, bags wallet, bags cash, getbags, invite code, redeem, micropayment,
-    agent wallet, check endpoint, wallet fetch
+    agent wallet, check endpoint, wallet fetch, research, scrape, enrich, social data, media generation
 homepage: https://www.getbags.app/wallet/skill.md
 metadata:
-    version: 0.2
+    version: 0.3
 ---
 
 # BAGS Cash — Hosted Agent Wallet
@@ -68,7 +69,7 @@ If there is no token yet, redeem (test or invite) first. If live balance is too
 
 ## Workflow: balance → discover → check → fetch
 
-Match AgentCash’s agent loop; prefer this order every time.
+Use existing dedicated tools first. Public search/discover works before wallet setup. For paid execution: balance → discover → check → fetch. Discovery is not permission to spend.
 
 ### 1. Balance
 
@@ -84,7 +85,7 @@ npx @getbags/cash discover weather forecast   # BAGS first, then open x402 index
 npx @getbags/cash search "send physical mail" # NL search (catalog + ecosystem)
 ```
 
-Bare `discover` lists BAGS’ own **$0.01** `GET /api/v1` showcase first — the natural first paid call for a new agent. Prefer `source: bags` results (refund-guaranteed on BAGS merchants when that guarantee is live). Then `source: bazaar`. Default table columns: `url`, `method`, `price`, `merchant`, `source`. Use `--format json` for the raw payload (includes schemas when present).
+Public catalog/search costs nothing. `GET /api/v1` is an optional paid protocol demonstration; use free `/openapi.json` for the API index. Prefer a useful task such as extracting a requested page or finding current weather for the first purchase. Compare method, required inputs, output, price ceiling, wallet mode and source coverage before selecting a provider. A catalog price is indicative; unknown pricing does not mean free. Use `--format json` to inspect schemas, freshness and source failures. Schema coverage is partial or unknown, never a guarantee of successful input/output conformance.
 
 ### 3. Check (exact quote, no payment)
 
@@ -103,11 +104,11 @@ npx @getbags/cash fetch '<url>' -m POST -b '{"key":"value"}'
 npx @getbags/cash fetch '<url>' --max-price-cents 25
 ```
 
-Payment receipt (amount, tx hash, network) → stderr; upstream body → stdout (pipe-friendly).
+Payment receipt (exact amount, tx hash, network) → stderr; upstream body → stdout (pipe-friendly). Receipts retain `amount_atomic` (six-decimal USDC) and fractional `amount_cents`. Network fees are platform-paid and marked unmeasured unless observed; do not infer total on-chain debit from the service amount. MPP supports one-shot `tempo:charge` on permitted USDC.e chains. Hosted MPP sessions are unavailable until durable close can be confirmed.
 
 **Latency:** wallet fetch often takes **~30–60 seconds** (paid ~30s; free/SIWX ~40–50s). Set agent-framework HTTP timeouts accordingly — do not treat a slow response as a hang until well past 60s.
 
-**Response envelope:** check top-level `status` / `code` first. `status: "success"` means the fetch completed as intended (including free/SIWX calls with `payment.paid: false`). A paid attempt that did not complete returns `status: "error"` with `PRE_PAYMENT_FAILED` or `NETWORK_NOT_ALLOWED` (nested `data.http_status` / `data.payment` keep the upstream diagnostic). Do not treat HTTP 200 alone as “paid OK” — and do not treat nested `http_status: 402` under `status: "success"` as a thing that happens anymore.
+**Response envelope:** check top-level `status` / `code` first. `status: "success"` means the HTTP fetch completed (including free/SIWX calls with `payment.paid: false`). A paid attempt that did not complete returns `status: "error"` with `PRE_PAYMENT_FAILED` or `NETWORK_NOT_ALLOWED` (nested `data.http_status` / `data.payment` keep the upstream diagnostic). Do not treat HTTP 200 alone as “paid OK” — and do not treat nested `http_status: 402` under `status: "success"` as a thing that happens anymore.
 
 ## Other commands
 
@@ -150,3 +151,13 @@ Env: `BAGS_API_URL` (default `https://www.getbags.app`; staging example `https:/
 Token path: `~/.bags/credentials.json`.
 
 MCP: wallet tools on `https://www.getbags.app/api/mcp/mcp` — pass `Authorization: Bearer bag_agent_sk_...` or a `wallet_token` argument on each tool.
+
+## Results and safe retries
+
+Read a retained result with `bags result <id> --field response.items --offset 0 --limit 20`, or the read-only `wallet_result` MCP tool. Neither performs another paid call.
+
+An upstream 200 can contain target-page 404 or unusable output. Inspect `outcomes` and the payload before claiming task success. Provider failures may still be billed. BAGS-network upstream 5xx may receive wallet credit; external provider billing rules apply. Unknown/submitted payment retains the reservation for reconciliation.
+
+Reuse `Idempotency-Key` for retries (24-hour replay); use a new key for an intentional new paid call. Fetch supports `result_mode: "summary"` through the API. `data.result.retrieval_url` retrieves retained output for 24 hours without paying again, with optional `field`, `offset` and `limit`. A result handle is not an async provider poll: accepted provider runs require their provider-specific status contract, which may be paid. Do not blindly execute again. Authentication fields are redacted in retained exports; signed asset URLs may expire before result retention ends.
+
+For a frequent origin/task, save only a thin pointer: task, origin and the current search/check workflow. Refresh live schemas and prices on use; never copy credentials or freeze endpoint contracts into a reusable skill.

package/dist/api.d.ts

@@ -9,6 +9,10 @@ export type RedeemResponse = {
     expires: null;
 };
 export type BalanceResponse = {
+    wallet_id?: string;
+    mode?: 'live' | 'test';
+    credential_scope?: string;
+    payment_readiness?: string;
     balance_cents: number;
     daily_spent_cents: number;
     daily_cap_cents: number;
@@ -24,6 +28,10 @@ export type DiscoverEndpoint = {
     source?: 'bags' | 'bazaar' | 'registered';
     input_schema?: unknown;
     output_schema?: unknown;
+    pricing?: {
+        kind?: string;
+        indicative?: boolean;
+    };
     score?: number;
     signals?: {
         text_match: number;
@@ -32,6 +40,7 @@ export type DiscoverEndpoint = {
     };
 };
 export type DiscoverResponse = {
+    coverage?: unknown;
     endpoints: DiscoverEndpoint[];
     query?: string | null;
 };
@@ -40,8 +49,16 @@ export type FetchPayment = {
     amount_cents: number;
     tx_hash: string;
     network: string;
+    input_schema_declared?: boolean;
+    upstream_4xx?: boolean;
 };
 export type FetchResponse = {
+    result?: unknown;
+    outcomes?: unknown;
+    billing?: unknown;
+    wallet_id?: string;
+    mode?: string;
+    request_id?: string;
     status: string;
     http_status: number;
     payment: FetchPayment | null;
@@ -110,7 +127,7 @@ export declare function redeem(opts: {
 }): Promise<RedeemResponse>;
 export declare function getBalance(token: string): Promise<BalanceResponse>;
 export declare function discover(token: string, query?: string): Promise<DiscoverResponse>;
-export declare function search(token: string, query: string): Promise<DiscoverResponse>;
+export declare function search(token: string, query: string, requirements?: Record<string, unknown>): Promise<DiscoverResponse>;
 export declare function checkEndpoint(token: string, input: {
     url: string;
     method?: string;
@@ -123,6 +140,7 @@ export declare function walletFetch(token: string, input: {
     body?: unknown;
     max_price_cents?: number;
     payment_protocol?: 'x402' | 'mpp' | 'auto';
+    result_mode?: 'inline' | 'summary';
 }): Promise<FetchResponse>;
 export type MppSessionSummary = {
     id: string;
@@ -168,3 +186,12 @@ export declare function registerOrigin(token: string, origin: string, opts?: {
     label?: string;
     description?: string;
 }): Promise<Record<string, unknown>>;
+/** Read an owned result; never starts another provider call or payment. */
+export declare function getResult(token: string, input: {
+    id: string;
+    field?: string;
+    offset?: number;
+    limit?: number;
+    refresh?: boolean;
+    retain_asset_url?: string;
+}): Promise<Record<string, unknown>>;

package/dist/api.js

@@ -1,5 +1,5 @@
 import { getBaseUrl } from './config.js';
-import { formatApiError } from './errors.js';
+import { formatApiError, withUpstreamDetail } from './errors.js';
 export class CliApiError extends Error {
     code;
     httpStatus;
@@ -50,7 +50,7 @@ export async function apiRequest(path, options = {}) {
     if (!res.ok || json.status === 'error') {
         const code = typeof json.code === 'string' ? json.code : res.status === 404 ? 'NOT_FOUND' : `HTTP_${res.status}`;
         const message = typeof json.message === 'string' ? json.message : res.statusText || 'request failed';
-        throw new CliApiError(code, message, res.status);
+        throw new CliApiError(code, withUpstreamDetail(message, json.data), res.status);
     }
     return json;
 }
@@ -77,6 +77,10 @@ export async function getBalance(token) {
             ? body.wallet_status
             : 'unknown';
     return {
+        ...(data.wallet_id ? { wallet_id: data.wallet_id } : {}),
+        ...(data.mode ? { mode: data.mode } : {}),
+        ...(data.credential_scope ? { credential_scope: data.credential_scope } : {}),
+        ...(data.payment_readiness ? { payment_readiness: data.payment_readiness } : {}),
         balance_cents: Number(data.balance_cents),
         daily_spent_cents: Number(data.daily_spent_cents),
         daily_cap_cents: Number(data.daily_cap_cents),
@@ -89,15 +93,17 @@ export async function discover(token, query) {
     const body = await apiRequest(path, { token });
     const data = unwrapPayload(body);
     return {
+        ...(data.coverage ? { coverage: data.coverage } : {}),
         endpoints: Array.isArray(data.endpoints) ? data.endpoints : [],
         query: data.query,
     };
 }
-export async function search(token, query) {
-    const path = `/api/wallet/search?q=${encodeURIComponent(query)}`;
+export async function search(token, query, requirements) {
+    const path = `/api/wallet/search?q=${encodeURIComponent(query)}${requirements ? '&requirements=' + encodeURIComponent(JSON.stringify(requirements)) : ''}`;
     const body = await apiRequest(path, { token });
     const data = unwrapPayload(body);
     return {
+        ...(data.coverage ? { coverage: data.coverage } : {}),
         endpoints: Array.isArray(data.endpoints) ? data.endpoints : [],
         query: typeof data.query === 'string' ? data.query : query,
     };
@@ -118,6 +124,7 @@ export async function walletFetch(token, input) {
     });
     const data = unwrapPayload(body);
     return {
+        ...data,
         status: typeof data.status === 'string' ? data.status : 'success',
         http_status: Number(data.http_status),
         payment: data.payment ?? null,
@@ -236,3 +243,25 @@ export async function registerOrigin(token, origin, opts = {}) {
     });
     return unwrapPayload(body);
 }
+/** Read an owned result; never starts another provider call or payment. */
+export async function getResult(token, input) {
+    if (input.retain_asset_url) {
+        if (input.refresh || input.field || input.offset !== undefined || input.limit !== undefined)
+            throw new Error('Asset retention cannot be combined with read/refresh options');
+        return unwrapPayload(await apiRequest('/api/wallet/results', {
+            method: 'POST',
+            token,
+            body: { id: input.id, retain_asset_url: input.retain_asset_url },
+        }));
+    }
+    const query = new URLSearchParams({ id: input.id });
+    if (input.refresh)
+        query.set('refresh', 'true');
+    if (input.field)
+        query.set('field', input.field);
+    if (input.offset !== undefined)
+        query.set('offset', String(input.offset));
+    if (input.limit !== undefined)
+        query.set('limit', String(input.limit));
+    return unwrapPayload(await apiRequest(`/api/wallet/results?${query}`, { token }));
+}

package/dist/errors.d.ts

@@ -1,2 +1,8 @@
 export declare const ERROR_REMEDIES: Record<string, string>;
 export declare function formatApiError(code: string, message: string): string;
+/**
+ * Surface the wallet API's nested upstream diagnostic (data.http_status +
+ * data.response) so PRE_PAYMENT_FAILED failures are legible from the CLI
+ * instead of requiring a raw API call to see why a merchant rejected payment.
+ */
+export declare function withUpstreamDetail(message: string, data: unknown): string;

package/dist/errors.js

@@ -26,3 +26,21 @@ export function formatApiError(code, message) {
     const line = `${code}: ${message}`;
     return remedy ? `${line}\n${remedy}` : line;
 }
+/**
+ * Surface the wallet API's nested upstream diagnostic (data.http_status +
+ * data.response) so PRE_PAYMENT_FAILED failures are legible from the CLI
+ * instead of requiring a raw API call to see why a merchant rejected payment.
+ */
+export function withUpstreamDetail(message, data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return message;
+    const record = data;
+    const status = record.http_status;
+    const response = record.response;
+    if (status === undefined && response === undefined)
+        return message;
+    const body = typeof response === 'string' ? response : response ? JSON.stringify(response) : '';
+    const head = status !== undefined ? `upstream http ${String(status)}` : 'upstream';
+    const detail = body ? `${head}: ${body.slice(0, 300)}` : head;
+    return `${message} (${detail})`;
+}

package/dist/fetch-hints.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fetch output diagnostics for failed paid attempts.
+ *
+ * A paid call can settle on-chain and then hit a merchant 4xx (e.g. a 422 for
+ * a bad request param) — money gone with nothing to show. When the 402
+ * challenge declared a bazaar input schema, point the agent at `bags check`
+ * so the retry carries the required fields.
+ */
+export declare const INPUT_SCHEMA_HINT = "this endpoint declares an input schema - run `bags check` to see required fields";
+/** True when payment settled but the upstream response was an error status. */
+export declare function isFailedPaidAttempt(payment: {
+    paid?: boolean;
+} | null | undefined, httpStatus: number): boolean;
+/** Should `bags fetch` print the input-schema hint for this fetch result? */
+export declare function shouldPrintInputSchemaHint(payment: {
+    paid?: boolean;
+    input_schema_declared?: boolean;
+} | null | undefined, httpStatus: number): boolean;

package/dist/fetch-hints.js

@@ -0,0 +1,17 @@
+/**
+ * Fetch output diagnostics for failed paid attempts.
+ *
+ * A paid call can settle on-chain and then hit a merchant 4xx (e.g. a 422 for
+ * a bad request param) — money gone with nothing to show. When the 402
+ * challenge declared a bazaar input schema, point the agent at `bags check`
+ * so the retry carries the required fields.
+ */
+export const INPUT_SCHEMA_HINT = 'this endpoint declares an input schema - run `bags check` to see required fields';
+/** True when payment settled but the upstream response was an error status. */
+export function isFailedPaidAttempt(payment, httpStatus) {
+    return payment?.paid === true && httpStatus >= 400;
+}
+/** Should `bags fetch` print the input-schema hint for this fetch result? */
+export function shouldPrintInputSchemaHint(payment, httpStatus) {
+    return isFailedPaidAttempt(payment, httpStatus) && payment?.input_schema_declared === true;
+}

package/dist/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-import { checkEndpoint, createDeposit, createKey, discover, getBalance, getFund, getPolicies, getTransactions, listKeys, redeem, revokeKey, registerOrigin, search, setPolicies, listSessions, closeSessions, walletFetch, CliApiError, } from './api.js';
-import { getBaseUrl, requireToken, saveCredentials } from './config.js';
+import { checkEndpoint, createDeposit, createKey, discover, getBalance, getResult, getFund, getPolicies, getTransactions, listKeys, redeem, revokeKey, registerOrigin, search, setPolicies, listSessions, closeSessions, walletFetch, CliApiError, } from './api.js';
+import { getBaseUrl, loadCredentials, requireToken, saveCredentials } from './config.js';
+import { INPUT_SCHEMA_HINT, shouldPrintInputSchemaHint } from './fetch-hints.js';
 import { formatDoctorSummary, runDoctor } from './doctor.js';
 import { runInitCommand } from './install-command.js';
 import { runStdioServer } from './mcp-server.js';
+import { policyPatchFromSets } from './policies.js';
 import { parseArgs, USAGE } from './parse.js';
 function centsToDollars(cents) {
-    return `$${(cents / 100).toFixed(2)}`;
+    return `$${(cents / 100).toFixed(Number.isInteger(cents) ? 2 : 6).replace(/(\.\d{2,}?)0+$/, '$1')}`;
 }
 function fail(message) {
     console.error(message);
@@ -20,7 +22,12 @@ function printDiscoverTable(endpoints) {
     const rows = endpoints.map((ep) => ({
         url: ep.url,
         method: ep.method,
-        price: typeof ep.price_usd === 'number' ? `$${ep.price_usd.toFixed(2)}` : String(ep.price_usd),
+        price: ep.pricing?.kind === 'unknown' ||
+            (ep.source === 'registered' && Number(ep.price_usd) === 0 && ep.pricing?.kind !== 'free')
+            ? 'unknown (check)'
+            : typeof ep.price_usd === 'number'
+                ? `$${ep.price_usd.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
+                : String(ep.price_usd),
         merchant: ep.merchant_name ?? '',
         source: ep.source ?? 'bags',
     }));
@@ -36,28 +43,16 @@ function printDiscoverTable(endpoints) {
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
-function policyPatchFromSets(sets) {
-    const patch = {};
-    for (const [key, value] of Object.entries(sets)) {
-        const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-        const num = Number(value);
-        patch[camel] =
-            Number.isFinite(num) && String(num) === value
-                ? num
-                : value === 'true'
-                    ? true
-                    : value === 'false'
-                        ? false
-                        : value;
-    }
-    return patch;
-}
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
     if (parsed.command === 'help') {
         console.log(USAGE);
         return;
     }
+    if (parsed.command === 'usage') {
+        console.log(parsed.message);
+        return;
+    }
     if (parsed.command === 'error') {
         fail(parsed.message);
     }
@@ -88,7 +83,7 @@ async function main() {
                 return;
             }
             case 'discover': {
-                const result = await discover(requireToken(), parsed.query);
+                const result = await discover(loadCredentials()?.token ?? '', parsed.query);
                 if (parsed.format === 'json') {
                     printJson(result);
                 }
@@ -98,7 +93,7 @@ async function main() {
                 return;
             }
             case 'search': {
-                const result = await search(requireToken(), parsed.query);
+                const result = await search(loadCredentials()?.token ?? '', parsed.query, parsed.requirements);
                 if (parsed.format === 'json') {
                     printJson(result);
                 }
@@ -165,7 +160,11 @@ async function main() {
                     payment_protocol: parsed.paymentProtocol,
                 });
                 if (result.payment?.paid) {
-                    console.error(`payment: ${centsToDollars(result.payment.amount_cents)} | tx ${result.payment.tx_hash} | ${result.payment.network}`);
+                    const upstreamNote = result.http_status >= 400 ? ` | upstream HTTP ${result.http_status}` : '';
+                    console.error(`payment: ${centsToDollars(result.payment.amount_cents)} | tx ${result.payment.tx_hash} | ${result.payment.network}${upstreamNote}`);
+                    if (shouldPrintInputSchemaHint(result.payment, result.http_status)) {
+                        console.error(INPUT_SCHEMA_HINT);
+                    }
                 }
                 else if (result.payment) {
                     console.error(`payment: not charged | tx ${result.payment.tx_hash || 'n/a'} | ${result.payment.network || 'n/a'}`);
@@ -229,6 +228,10 @@ async function main() {
                 }
                 return;
             }
+            case 'result': {
+                printJson(await getResult(requireToken(), parsed));
+                return;
+            }
             case 'transactions': {
                 try {
                     const result = await getTransactions(requireToken(), {

package/dist/mcp-server.d.ts

@@ -2,9 +2,17 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type CheckResponse, type DiscoverResponse, type FetchResponse, type BalanceResponse, type PoliciesResponse, type TransactionsResponse, type RedeemResponse, type MppSessionSummary } from './api.js';
 export declare const WALLET_MCP_TOOL_NAMES: readonly ["wallet_balance", "wallet_discover", "wallet_search", "wallet_check_endpoint", "wallet_fetch", "wallet_sessions_list", "wallet_sessions_close", "wallet_sessions_tick", "wallet_redeem", "wallet_transactions", "wallet_get_settings", "wallet_update_settings"];
 export type WalletMcpApi = {
+    getResult: (token: string, input: {
+        id: string;
+        field?: string;
+        offset?: number;
+        limit?: number;
+        refresh?: boolean;
+        retain_asset_url?: string;
+    }) => Promise<Record<string, unknown>>;
     getBalance: (token: string) => Promise<BalanceResponse>;
     discover: (token: string, query?: string) => Promise<DiscoverResponse>;
-    search: (token: string, query: string) => Promise<DiscoverResponse>;
+    search: (token: string, query: string, requirements?: Record<string, unknown>) => Promise<DiscoverResponse>;
     checkEndpoint: (token: string, input: {
         url: string;
         method?: string;
@@ -17,6 +25,7 @@ export type WalletMcpApi = {
         body?: unknown;
         max_price_cents?: number;
         payment_protocol?: 'x402' | 'mpp' | 'auto';
+        result_mode?: 'inline' | 'summary';
     }) => Promise<FetchResponse>;
     listSessions: (token: string) => Promise<{
         sessions: MppSessionSummary[];

package/dist/mcp-server.js

@@ -1,7 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'node:fs';
 import { z } from 'zod';
-import { CliApiError, apiRequest, checkEndpoint, closeSessions, discover, getBalance, getPolicies, getTransactions, listSessions, redeem, search, setPolicies, walletFetch, } from './api.js';
+import { CliApiError, apiRequest, checkEndpoint, closeSessions, discover, getBalance, getResult, getPolicies, getTransactions, listSessions, redeem, search, setPolicies, walletFetch, } from './api.js';
 import { loadCredentials, saveCredentials as defaultSaveCredentials } from './config.js';
 import { WALLET_MCP_INSTRUCTIONS } from './mcp-instructions.js';
 export const WALLET_MCP_TOOL_NAMES = [
@@ -47,6 +48,7 @@ function missingTokenResult() {
 function resolveApi(partial) {
     return {
         getBalance,
+        getResult,
         discover,
         search,
         checkEndpoint,
@@ -73,7 +75,8 @@ function resolveToken(deps) {
 export function createWalletMcpServer(deps = {}) {
     const api = resolveApi(deps.api);
     const persistCredentials = deps.saveCredentials ?? defaultSaveCredentials;
-    const server = new McpServer({ name: 'bags-cash', version: '0.3.0' }, { instructions: WALLET_MCP_INSTRUCTIONS });
+    const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const server = new McpServer({ name: 'bags-cash', version }, { instructions: WALLET_MCP_INSTRUCTIONS });
     async function withToken(run) {
         const token = resolveToken(deps);
         if (!token)
@@ -104,18 +107,30 @@ export function createWalletMcpServer(deps = {}) {
             query: z.string().optional().describe('Optional search keywords'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async (args) => withToken(async (token) => {
+    }, async (args) => (async () => {
+        const token = resolveToken(deps) ?? '';
         const q = typeof args.query === 'string' ? args.query.trim() : '';
         return textContent(await api.discover(token, q || undefined));
-    }));
+    })());
     server.registerTool('wallet_search', {
         title: 'Search payable endpoints',
         description: 'Natural-language search for x402 endpoints. BAGS catalog first, best-effort ecosystem (Bazaar) second. Returns price, description, schemas when available.',
         inputSchema: {
             query: z.string().min(1).describe('Natural-language or keyword query'),
+            requirements: z
+                .object({
+                inputs: z
+                    .record(z.string().min(1).max(100), z.union([z.string().max(256), z.number(), z.boolean(), z.null()]))
+                    .refine((v) => Object.keys(v).length <= 32, 'At most 32 input controls')
+                    .optional(),
+                outputs: z.array(z.string().min(1).max(100)).max(16).optional(),
+                unit: z.string().min(1).max(50).optional(),
+            })
+                .strict()
+                .optional(),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async (args) => withToken(async (token) => textContent(await api.search(token, String(args.query ?? '').trim()))));
+    }, async (args) => textContent(await api.search(resolveToken(deps) ?? '', String(args.query ?? '').trim(), args.requirements)));
     server.registerTool('wallet_check_endpoint', {
         title: 'Check endpoint quote',
         description: 'Probe an x402 URL for schema + exact price quote without paying (AgentCash check parity). Use before wallet_fetch.',
@@ -130,13 +145,35 @@ export function createWalletMcpServer(deps = {}) {
         method: typeof args.method === 'string' ? args.method : undefined,
         body: args.body,
     }))));
+    server.registerTool('wallet_result', {
+        title: 'Read retained wallet result',
+        description: 'Retrieve full output, fields or array pages from a previous wallet_fetch result for 24 hours. Does not execute or charge again. Provider asset URLs may expire earlier.',
+        inputSchema: {
+            id: z.string().uuid(),
+            refresh: z
+                .boolean()
+                .optional()
+                .describe('Make one unpaid GET to the advertised async status URL; never authorizes payment'),
+            retain_asset_url: z
+                .string()
+                .url()
+                .max(8192)
+                .optional()
+                .describe('Explicitly copy an advertised asset privately, at most two 2 MiB assets for the result lifetime'),
+            field: z.string().max(200).optional(),
+            offset: z.number().int().nonnegative().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => withToken(async (token) => textContent(await api.getResult(token, args))));
     server.registerTool('wallet_fetch', {
         title: 'Wallet fetch (pay + proxy)',
-        description: 'Pay for and proxy an x402- or MPP-protected HTTP request using the BAGS hosted wallet. MPP tempo:session channels stay open until wallet_sessions_close.',
+        description: 'Pay for an x402 or one-shot MPP tempo:charge HTTP request with the hosted wallet. Check the quote and wallet mode first. Hosted MPP sessions are currently unavailable.',
         inputSchema: {
             url: z.string().url(),
             method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional(),
             body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+            result_mode: z.enum(['inline', 'summary']).optional(),
             max_price_cents: z.number().int().positive().optional(),
             payment_protocol: z
                 .enum(['x402', 'mpp', 'auto'])
@@ -148,6 +185,7 @@ export function createWalletMcpServer(deps = {}) {
         url: String(args.url),
         method: typeof args.method === 'string' ? args.method : undefined,
         body: args.body,
+        result_mode: args.result_mode,
         max_price_cents: typeof args.max_price_cents === 'number' ? args.max_price_cents : undefined,
         payment_protocol: args.payment_protocol === 'x402' ||
             args.payment_protocol === 'mpp' ||
@@ -165,7 +203,7 @@ export function createWalletMcpServer(deps = {}) {
     }, async () => withToken(async (token) => textContent(await api.listSessions(token))));
     server.registerTool('wallet_sessions_close', {
         title: 'Close MPP session',
-        description: 'Close one or all open MPP tempo:session channels (settles reservation to cumulative spend). Pass all=true to close every open session.',
+        description: 'Request cleanup of existing MPP sessions. On-chain close is currently unsupported: the call reports failure and preserves the reservation and ownership. New sessions cannot be opened.',
         inputSchema: {
             session_id: z.string().uuid().optional(),
             channel_id: z.string().min(1).optional(),

package/dist/parse.d.ts

@@ -2,12 +2,23 @@ import type { ClientId, InstallScope } from './detect.js';
 export type PaymentProtocol = 'x402' | 'mpp' | 'auto';
 export type ParsedArgs = {
     command: 'help';
+} | {
+    command: 'usage';
+    message: string;
 } | {
     command: 'redeem';
     code?: string;
     test: boolean;
 } | {
     command: 'balance';
+} | {
+    command: 'result';
+    id: string;
+    field?: string;
+    offset?: number;
+    limit?: number;
+    refresh?: boolean;
+    retain_asset_url?: string;
 } | {
     command: 'discover';
     format: 'json' | 'pretty';
@@ -69,6 +80,7 @@ export type ParsedArgs = {
 } | {
     command: 'search';
     query: string;
+    requirements?: Record<string, unknown>;
     format: 'json' | 'pretty';
 } | {
     command: 'register';

package/dist/parse.js

@@ -1,5 +1,27 @@
 import { walletDepositsVisible } from './deposits-visible.js';
 const VALID_CLIENTS = ['cursor', 'claude', 'codex'];
+/**
+ * Per-command usage strings - the same text the flag-error paths print, so
+ * `bags <cmd> --help` never disagrees with a bad-flag error.
+ */
+const COMMAND_USAGE = {
+    redeem: 'usage: bags redeem <code> | bags redeem --test',
+    balance: 'usage: bags balance',
+    result: 'usage: bags result <id> [--field path] [--offset N] [--limit N] [--refresh] [--retain-asset URL]',
+    discover: 'usage: bags discover [query] [--format json|pretty]',
+    search: 'usage: bags search <query> [--format json|pretty]',
+    check: 'usage: bags check <url> [flags]',
+    fetch: 'usage: bags fetch <url> [flags]',
+    sessions: 'usage: bags sessions list|close [id] [--all --yes]',
+    init: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+    doctor: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+    fund: 'usage: bags fund [--open] [--create] [--network NAME]',
+    transactions: 'usage: bags transactions [--limit N] [--cursor C] [--format json|pretty]',
+    policies: 'usage: bags policies get|set [--key=value ...]',
+    keys: 'usage: bags keys create|list|revoke',
+    register: 'usage: bags register <origin>',
+    mcp: 'usage: bags mcp',
+};
 function parseClientList(raw) {
     const parts = raw
         .split(',')
@@ -48,6 +70,13 @@ export function parseArgs(argv) {
         return { command: 'help' };
     }
     const [cmd, ...rest] = argv;
+    // -h/--help on any command prints that command's usage (stdout, exit 0).
+    if (rest.includes('-h') || rest.includes('--help')) {
+        const known = cmd in COMMAND_USAGE;
+        if (!known)
+            return { command: 'error', message: `unknown command: ${cmd}` };
+        return { command: 'usage', message: COMMAND_USAGE[cmd] };
+    }
     switch (cmd) {
         case 'redeem': {
             let code;
@@ -411,6 +440,46 @@ export function parseArgs(argv) {
             }
             return { command: 'fund', open, create, network };
         }
+        case 'result': {
+            const id = rest[0];
+            if (!id || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id))
+                return { command: 'error', message: COMMAND_USAGE.result };
+            const out = {
+                command: 'result',
+                id,
+            };
+            for (let i = 1; i < rest.length; i += 2) {
+                if (rest[i] === '--refresh') {
+                    out.refresh = true;
+                    i--;
+                    continue;
+                }
+                const flag = rest[i], value = rest[i + 1];
+                if (!value || !['--field', '--offset', '--limit', '--retain-asset'].includes(flag))
+                    return { command: 'error', message: COMMAND_USAGE.result };
+                if (flag === '--retain-asset') {
+                    out.retain_asset_url = value;
+                    continue;
+                }
+                if (flag === '--field')
+                    out.field = value;
+                else {
+                    const n = Number(value);
+                    if (!Number.isSafeInteger(n) ||
+                        n < (flag === '--offset' ? 0 : 1) ||
+                        (flag === '--limit' && n > 100))
+                        return { command: 'error', message: COMMAND_USAGE.result };
+                    if (flag === '--offset')
+                        out.offset = n;
+                    else
+                        out.limit = n;
+                }
+            }
+            if (out.retain_asset_url &&
+                (out.refresh || out.field || out.offset !== undefined || out.limit !== undefined))
+                return { command: 'error', message: '--retain-asset cannot be combined with read/refresh flags' };
+            return out;
+        }
         case 'transactions': {
             const parsed = takeFormat(rest, 'usage: bags transactions [--limit N] [--cursor C] [--format json|pretty]');
             if ('error' in parsed)
@@ -590,7 +659,24 @@ export function parseArgs(argv) {
             if ('error' in parsed)
                 return { command: 'error', message: parsed.error };
             const queryWords = [];
-            for (const arg of parsed.rest) {
+            let requirements;
+            for (let i = 0; i < parsed.rest.length; i++) {
+                const arg = parsed.rest[i];
+                if (arg === '--requirements') {
+                    const value = parsed.rest[++i];
+                    try {
+                        if (!value || value.length > 4096)
+                            throw new Error();
+                        const obj = JSON.parse(value);
+                        if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+                            throw new Error();
+                        requirements = obj;
+                    }
+                    catch {
+                        return { command: 'error', message: '--requirements must be a bounded JSON object' };
+                    }
+                    continue;
+                }
                 if (arg.startsWith('-'))
                     return { command: 'error', message: `unknown flag: ${arg}` };
                 queryWords.push(arg);
@@ -598,7 +684,7 @@ export function parseArgs(argv) {
             const query = queryWords.join(' ').trim();
             if (!query)
                 return { command: 'error', message: 'usage: bags search <query>' };
-            return { command: 'search', query, format: parsed.format };
+            return { command: 'search', query, format: parsed.format, ...(requirements ? { requirements } : {}) };
         }
         case 'register': {
             const origin = rest[0];
@@ -621,7 +707,7 @@ Usage:
   npx @getbags/cash <command>
 
 Workflow: balance → discover|search → check → fetch
-MPP streams: fetch (opens session) → sessions close
+MPP: one-shot tempo:charge; new hosted sessions are unavailable
 
 Commands:
   redeem <code>                 Redeem an invite code and save the wallet token
@@ -631,7 +717,9 @@ ${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS fi
   search <query>                NL search: BAGS catalog + ecosystem index
   check <url>                   Probe an endpoint for schema + exact quote (no pay)
   fetch <url> [flags]           Pay and proxy an x402 / MPP endpoint
-  sessions list|close           List or close open MPP tempo:session channels
+  sessions list                 List existing MPP session reservations
+  sessions close <id>           Request cleanup; unsupported close preserves the hold
+  result <id> [flags]           Read retained output without another payment
   transactions                  List wallet ledger / spend history
   policies get|set              Read or update spend policies
   keys create|list|revoke       Manage per-agent wallet keys
@@ -661,7 +749,12 @@ Fetch / check flags:
   --payment-protocol x402|mpp|auto  Force rail (default: auto)
   --format json|pretty          Machine or human output
 
-Sessions:
+Result flags:
+  --field <path>                Select a retained field (e.g. response.items)
+  --offset <N>                  Array offset (default: 0)
+  --limit <N>                   Array page size (1–100; default: 20)
+
+Sessions (existing holds only; hosted close currently reports unsupported):
   npx @getbags/cash sessions list
   npx @getbags/cash sessions close <id>
   npx @getbags/cash sessions close --all --yes

package/dist/policies.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side policy patch construction for `bags policies set`.
+ *
+ * The wallet policies route validates a snake_case PatchSchema
+ * (src/app/api/wallet/policies/route.ts). Zod strips unknown keys there, so a
+ * misspelled or wrong-case flag used to return 200 with an unchanged policy —
+ * a silent no-op. This module normalizes every accepted spelling to
+ * snake_case and rejects unrecognized keys before the request leaves the CLI.
+ */
+export declare class PolicyPatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normalize a flag key to the server's snake_case spelling.
+ * Accepts kebab-case (`per-call-cap-cents`), camelCase (`perCallCapCents`),
+ * and snake_case (`per_call_cap_cents`).
+ */
+export declare function policyKeyToSnake(key: string): string;
+/**
+ * Build the PATCH body for `bags policies set --key=value ...`.
+ *
+ * Values coerce like before: integer-looking strings become numbers,
+ * `true`/`false` become booleans, anything else stays a string. Unknown keys
+ * throw (the server would silently strip them and report success).
+ */
+export declare function policyPatchFromSets(sets: Record<string, string>): Record<string, unknown>;

package/dist/policies.js

@@ -0,0 +1,69 @@
+/**
+ * Client-side policy patch construction for `bags policies set`.
+ *
+ * The wallet policies route validates a snake_case PatchSchema
+ * (src/app/api/wallet/policies/route.ts). Zod strips unknown keys there, so a
+ * misspelled or wrong-case flag used to return 200 with an unchanged policy —
+ * a silent no-op. This module normalizes every accepted spelling to
+ * snake_case and rejects unrecognized keys before the request leaves the CLI.
+ */
+/**
+ * Exact keys the server PatchSchema accepts. Keep in sync with
+ * src/app/api/wallet/policies/route.ts.
+ */
+const VALID_POLICY_KEYS = new Set([
+    'per_call_cap_cents',
+    'daily_cap_cents',
+    'weekly_cap_cents',
+    'monthly_cap_cents',
+    'total_cap_cents',
+    'human_approval_threshold_cents',
+    'origin_allowlist',
+    'origin_blocklist',
+    'status',
+]);
+export class PolicyPatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyPatchError';
+    }
+}
+/**
+ * Normalize a flag key to the server's snake_case spelling.
+ * Accepts kebab-case (`per-call-cap-cents`), camelCase (`perCallCapCents`),
+ * and snake_case (`per_call_cap_cents`).
+ */
+export function policyKeyToSnake(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/-/g, '_')
+        .toLowerCase();
+}
+/**
+ * Build the PATCH body for `bags policies set --key=value ...`.
+ *
+ * Values coerce like before: integer-looking strings become numbers,
+ * `true`/`false` become booleans, anything else stays a string. Unknown keys
+ * throw (the server would silently strip them and report success).
+ */
+export function policyPatchFromSets(sets) {
+    const patch = {};
+    for (const [key, value] of Object.entries(sets)) {
+        const snake = policyKeyToSnake(key);
+        if (!VALID_POLICY_KEYS.has(snake)) {
+            throw new PolicyPatchError(`unknown policy key: ${key}. ` +
+                `Valid keys: ${[...VALID_POLICY_KEYS].join(', ')}. ` +
+                `Example: bags policies set --per-call-cap-cents=100`);
+        }
+        const num = Number(value);
+        patch[snake] =
+            Number.isFinite(num) && String(num) === value
+                ? num
+                : value === 'true'
+                    ? true
+                    : value === 'false'
+                        ? false
+                        : value;
+    }
+    return patch;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getbags/cash",
-  "version": "0.3.0",
-  "description": "BAGS Cash CLI — hosted agent wallet for x402 (balance → discover → check → fetch)",
+  "version": "0.4.0",
+  "description": "BAGS Cash CLI \u2014 hosted agent wallet for x402 (balance \u2192 discover \u2192 check \u2192 fetch)",
   "type": "module",
   "bin": {
     "bags": "dist/index.js"
@@ -39,12 +39,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.26.0",
-    "zod": "^4.3.6"
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "typescript": "6.0.2",
-    "vitest": "^4.0.18"
-  }
+    "vitest": "^5.0.3"
+  },
+  "packageManager": "bun@1.4.2"
 }