@getbags/cash 0.2.1 → 0.3.1

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
 
@@ -30,21 +31,27 @@ Staging: use `https://staging.getbags.app/wallet/skill.md` (or set `BAGS_API_URL
 
 ## Commands
 
-| Command                     | Description                                                 |
-| --------------------------- | ----------------------------------------------------------- |
-| `redeem <code>`             | Redeem an invite; saves token to `~/.bags/credentials.json` |
-| `balance`                   | Show balance, daily spent/cap, status                       |
-| `discover [query]`          | List BAGS merchant endpoints (BAGS first)                   |
-| `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                              |
-| `transactions`              | Spend / ledger history                                      |
-| `policies get\|set`         | Read or update spend policies                               |
-| `keys create\|list\|revoke` | Per-agent wallet keys                                       |
-| `register <origin>`         | Persist an origin into the discover/search index            |
-| `init`                      | Write the `bags-cash` agent skill into this repo            |
-
-Fetch / check flags: `-m/--method`, `-b/--body` (JSON string), `--max-price-cents` (fetch), `--format json|pretty`.
+| Command                     | Description                                                     |
+| --------------------------- | --------------------------------------------------------------- |
+| `redeem <code>`             | Redeem an invite; saves token to `~/.bags/credentials.json`     |
+| `redeem --test`             | Mint a sandbox wallet (no invite; Base Sepolia + Solana devnet) |
+| `balance`                   | Show balance, daily spent/cap, status                           |
+| `discover [query]`          | List BAGS merchant endpoints (BAGS first)                       |
+| `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                                           |
+| `register <origin>`         | Persist an origin into the discover/search index                |
+| `init [flags]`              | Register MCP + skill + routing rule for detected clients        |
+| `mcp`                       | Serve wallet tools over stdio (JSON-RPC on stdout)              |
+| `doctor`                    | Verify token, MCP registration, skill, and routing rule         |
+
+`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` and `--payment-protocol x402|mpp|auto` (fetch), `--format json|pretty` (check). Result flags: `--field`, `--offset`, `--limit`.
 
 ## Env
 
@@ -56,13 +63,16 @@ Fetch / check flags: `-m/--method`, `-b/--body` (JSON string), `--max-price-cent
 
 ```bash
 export BAGS_API_URL=https://staging.getbags.app   # optional
-npx @getbags/cash redeem BAGS-XXXX-XXXX
+npx @getbags/cash redeem --test                   # sandbox (no invite burn)
+# or: npx @getbags/cash redeem BAGS-XXXX-XXXX
 npx @getbags/cash balance
-npx @getbags/cash search "weather forecast"
-npx @getbags/cash check 'https://example.com/paid'
-npx @getbags/cash fetch 'https://example.com/paid' -m POST -b '{"q":"hi"}'
+npx @getbags/cash discover                        # includes $0.01 /api/v1 showcase
+npx @getbags/cash check 'https://www.getbags.app/api/v1'
+npx @getbags/cash fetch 'https://www.getbags.app/api/v1'
 ```
 
+After `npm i -g @getbags/cash`, `bags` is an alias for `npx @getbags/cash`.
+
 Payment receipt prints on stderr; the upstream body prints on stdout.
 
 ## Auth
@@ -71,34 +81,39 @@ 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).
+
+### CI (tag or dispatch)
 
-From the repo root:
+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)
-
-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).
+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.
 
-`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> --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"`.
 
-**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`).
+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.

package/SKILL.md

@@ -3,40 +3,73 @@ 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
 
 > Hosted skill URL: https://www.getbags.app/wallet/skill.md  
+> Human install guide: https://www.getbags.app/wallet/install  
 > Onboard (humans): https://www.getbags.app/wallet/onboard  
 > Staging: replace the host with `https://staging.getbags.app`.
 
-Call x402-protected APIs with a **hosted** BAGS wallet. Redeem an invite, discover services, **check** the exact quote + schema, then `fetch`. No local private keys — the agent holds only a token (`bag_agent_sk_*`).
+Call x402-protected APIs with a **hosted** BAGS wallet. Redeem an invite (or mint a sandbox wallet), discover services, **check** the exact quote + schema, then `fetch`. No local private keys — the agent holds only a token (`bag_agent_sk_*`).
+
+CLI examples below use `npx @getbags/cash …`. After a global install (`npm i -g @getbags/cash`), the `bags` binary is the same command.
 
 ## Why hosted (vs local-key wallets)
 
 Local plaintext / keychain wallets break in ephemeral sandboxes (Claude Cowork, CI, short-lived VMs): the key dies with the machine. BAGS keeps custody + ledger server-side. Your agent only needs the token in `~/.bags/credentials.json` (or `Authorization: Bearer`). Policies (caps, allowlists, kill switch) are enforced on the server — the agent cannot bypass them by editing a local file.
 
+## First-time setup (do in order)
+
+1. **Get a token** — sandbox (no invite) or live invite:
+
+```bash
+npx @getbags/cash redeem --test
+# or: npx @getbags/cash redeem <code>
+```
+
+`redeem --test` calls `POST /api/wallet/redeem` with `{"mode":"test"}`. That mints a test wallet with fake **$100,000** promo credit, restricted to **Base Sepolia + Solana devnet**, and burns **no** invite. Use a live invite (`redeem <code>`) only when you need mainnet spend.
+
+2. **Register the wallet with your agent client:**
+
+```bash
+npx @getbags/cash init
+```
+
+Bare `init` writes **user-scope** config under `~` so the wallet is ambient on this machine (Cursor / Claude Code / Codex). Use `--scope project` to write **committable, repo-local** config (`.cursor/mcp.json`, `.mcp.json`, `AGENTS.md`, etc.) for a team. Other flags: `--dry-run`, `--client cursor|claude|codex` (force-create even without a marker directory).
+
+3. **Restart the agent client** (Cursor / Claude Code / Codex) so it loads the new MCP server. MCP configs are not hot-reloaded — skipping this leaves the wallet invisible.
+
+4. **Verify:**
+
+```bash
+npx @getbags/cash doctor
+```
+
 ## Wallet
 
-| Task                           | Command                           |
-| ------------------------------ | --------------------------------- |
-| Redeem invite (saves token)    | `npx @getbags/cash redeem <code>` |
-| Check balance + caps           | `npx @getbags/cash balance`       |
-| Install this skill into a repo | `npx @getbags/cash init`          |
+| Task                        | Command                           |
+| --------------------------- | --------------------------------- |
+| Sandbox wallet (no invite)  | `npx @getbags/cash redeem --test` |
+| Redeem invite (saves token) | `npx @getbags/cash redeem <code>` |
+| One-command agent setup     | `npx @getbags/cash init`          |
+| Verify agent visibility     | `npx @getbags/cash doctor`        |
+| Check balance + caps        | `npx @getbags/cash balance`       |
 
-If there is no token yet, redeem first. If balance is too low, ask for another invite.
+If there is no token yet, redeem (test or invite) first. If live balance is too low, ask for another invite.
 
 ## 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
 
@@ -47,12 +80,12 @@ npx @getbags/cash balance
 ### 2. Discover or search
 
 ```bash
-npx @getbags/cash discover                    # BAGS merchant catalog
+npx @getbags/cash discover                    # BAGS catalog (includes $0.01 /api/v1 showcase)
 npx @getbags/cash discover weather forecast   # BAGS first, then open x402 index
 npx @getbags/cash search "send physical mail" # NL search (catalog + ecosystem)
 ```
 
-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)
 
@@ -71,9 +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
 
@@ -83,6 +118,8 @@ Payment receipt (amount, tx hash, network) → stderr; upstream body → stdout
 | `policies get` / `policies set --per-call-cap-cents=50` | Read/update spend caps              |
 | `keys create\|list\|revoke`                             | Per-agent sub-keys                  |
 | `register <origin>`                                     | Register origin into discover index |
+| `mcp`                                                   | Serve wallet tools over stdio       |
+| `doctor`                                                | Verify wallet visibility to agents  |
 
 ## Important rules
 
@@ -91,25 +128,36 @@ Payment receipt (amount, tx hash, network) → stderr; upstream body → stdout
 - **Prefer `source: bags`**, then bazaar, then any trusted x402 URL via `fetch`.
 - **Failed pre-payment requests cost nothing.** If payment settled and upstream still errored, read the stderr receipt / `transactions`.
 - **Do not invent endpoints.** Use `discover` / `search` / `check` or a URL the user provided.
+- **Sandbox first.** Prefer `redeem --test` while integrating; switch to a live invite for mainnet.
 
 ## Troubleshooting
 
-| Code                                | Fix                                                                           |
-| ----------------------------------- | ----------------------------------------------------------------------------- |
-| `INSUFFICIENT_BALANCE`              | `bags balance` then redeem another invite                                     |
-| `INVITE_INVALID` / `INVITE_EXPIRED` | Ask for a new invite code                                                     |
-| `URL_BLOCKED`                       | Use a public `https` endpoint (SSRF gate)                                     |
-| `CAP_EXCEEDED`                      | Wait, lower `--max-price-cents`, or `policies set`                            |
-| `WALLET_SUSPENDED`                  | Dashboard / support                                                           |
-| `WALLET_FETCH_DISABLED`             | Retry later (global kill switch)                                              |
-| `VALIDATION_FAILED`                 | Fix url/method/body JSON                                                      |
-| `NOT_FOUND`                         | Route not live on this env — set `BAGS_API_URL` or upgrade                    |
-| `UPSTREAM_ERROR` / `TIMEOUT`        | Retry; `bags check <url>` for a fresh quote                                   |
-| `NETWORK_NOT_ALLOWED`               | Test wallet vs mainnet (or vice versa) — use matching mode                    |
-| `PRE_PAYMENT_FAILED`                | Payment did not broadcast; reservation reversed — fix quote / network / funds |
-| `AUTH_MISSING_CREDENTIALS`          | `bags redeem <code>`                                                          |
+| Code                                | Fix                                                                                    |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| `INSUFFICIENT_BALANCE`              | `npx @getbags/cash balance` then redeem another invite (or use `redeem --test` to try) |
+| `INVITE_INVALID` / `INVITE_EXPIRED` | Ask for a new invite code                                                              |
+| `URL_BLOCKED`                       | Use a public `https` endpoint (SSRF gate)                                              |
+| `CAP_EXCEEDED`                      | Wait, lower `--max-price-cents`, or `policies set`                                     |
+| `WALLET_SUSPENDED`                  | Dashboard / support                                                                    |
+| `WALLET_FETCH_DISABLED`             | Retry later (global kill switch)                                                       |
+| `VALIDATION_FAILED`                 | Fix url/method/body JSON                                                               |
+| `NOT_FOUND`                         | Route not live on this env — set `BAGS_API_URL` or upgrade                             |
+| `UPSTREAM_ERROR` / `TIMEOUT`        | Retry; `npx @getbags/cash check <url>` for a fresh quote (fetch can take 30–60s)       |
+| `NETWORK_NOT_ALLOWED`               | Test wallet vs mainnet (or vice versa) — use matching mode                             |
+| `PRE_PAYMENT_FAILED`                | Payment did not broadcast; reservation reversed — fix quote / network / funds          |
+| `AUTH_MISSING_CREDENTIALS`          | `npx @getbags/cash redeem --test` or `npx @getbags/cash redeem <code>`                 |
 
 Env: `BAGS_API_URL` (default `https://www.getbags.app`; staging example `https://staging.getbags.app`).  
 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;
@@ -32,6 +36,7 @@ export type DiscoverEndpoint = {
     };
 };
 export type DiscoverResponse = {
+    coverage?: unknown;
     endpoints: DiscoverEndpoint[];
     query?: string | null;
 };
@@ -40,8 +45,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;
@@ -104,7 +117,10 @@ export declare function apiRequest(path: string, options?: {
     body?: unknown;
     token?: string;
 }): Promise<Record<string, unknown>>;
-export declare function redeem(code: string): Promise<RedeemResponse>;
+export declare function redeem(opts: {
+    code?: string;
+    mode?: 'live' | 'test';
+}): 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>;
@@ -120,6 +136,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;
@@ -165,3 +182,10 @@ 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;
+}): 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,14 +50,17 @@ 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;
 }
-export async function redeem(code) {
+export async function redeem(opts) {
+    const payload = opts.mode === 'test' && !opts.code
+        ? { mode: 'test' }
+        : { code: opts.code, ...(opts.mode ? { mode: opts.mode } : {}) };
     const body = await apiRequest('/api/wallet/redeem', {
         method: 'POST',
-        body: { code },
+        body: payload,
     });
     const data = unwrapPayload(body);
     if (typeof data.token !== 'string') {
@@ -74,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),
@@ -86,6 +93,7 @@ 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,
     };
@@ -95,6 +103,7 @@ export async function search(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: typeof data.query === 'string' ? data.query : query,
     };
@@ -115,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,
@@ -233,3 +243,14 @@ 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) {
+    const query = new URLSearchParams({ id: input.id });
+    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/detect.d.ts

@@ -0,0 +1,33 @@
+export type ClientId = 'cursor' | 'claude' | 'codex';
+export type InstallScope = 'project' | 'user';
+export type McpConfigFormat = 'json' | 'claude-json' | 'toml';
+export type ClientPaths = {
+    client: ClientId;
+    mcpConfigPath: string;
+    mcpConfigFormat: McpConfigFormat;
+    /** Parent skills directory; skill file lives at `${skillsDir}/bags-cash/SKILL.md`. */
+    skillsDir: string;
+    instructionsPath: string;
+};
+export type DetectedEnvironment = {
+    scope: InstallScope;
+    clients: ClientPaths[];
+    /** Absolute marker paths that were probed (for no-client diagnostics). */
+    lookedFor: string[];
+};
+export type FsExists = (path: string) => boolean;
+export type DetectOptions = {
+    cwd: string;
+    home: string;
+    scope: InstallScope;
+    exists: FsExists;
+    requestedClients?: ClientId[];
+};
+/**
+ * Detect every supported agent client whose marker path exists.
+ * Detect-all (not first-match-wins). Pure: filesystem access is injected.
+ *
+ * Explicit `requestedClients` (`--client`) is user intent: include those clients
+ * even when their marker directory is missing, so init can force-create config.
+ */
+export declare function detectClients(opts: DetectOptions): DetectedEnvironment;

package/dist/detect.js

@@ -0,0 +1,105 @@
+import { join } from 'node:path';
+const ALL_CLIENTS = ['cursor', 'claude', 'codex'];
+function projectPaths(cwd, client) {
+    switch (client) {
+        case 'cursor':
+            return {
+                client,
+                mcpConfigPath: join(cwd, '.cursor', 'mcp.json'),
+                mcpConfigFormat: 'json',
+                skillsDir: join(cwd, '.cursor', 'skills'),
+                instructionsPath: join(cwd, 'AGENTS.md'),
+            };
+        case 'claude':
+            return {
+                client,
+                mcpConfigPath: join(cwd, '.mcp.json'),
+                mcpConfigFormat: 'json',
+                skillsDir: join(cwd, '.claude', 'skills'),
+                instructionsPath: join(cwd, 'CLAUDE.md'),
+            };
+        case 'codex':
+            return {
+                client,
+                mcpConfigPath: join(cwd, '.codex', 'config.toml'),
+                mcpConfigFormat: 'toml',
+                skillsDir: join(cwd, '.agents', 'skills'),
+                instructionsPath: join(cwd, 'AGENTS.md'),
+            };
+    }
+}
+function userPaths(home, client) {
+    switch (client) {
+        case 'cursor':
+            return {
+                client,
+                mcpConfigPath: join(home, '.cursor', 'mcp.json'),
+                mcpConfigFormat: 'json',
+                skillsDir: join(home, '.cursor', 'skills'),
+                // Assumed: Cursor has no documented global AGENTS.md; we use this path
+                // so user-scope installs still get a fenced routing rule on disk.
+                instructionsPath: join(home, '.cursor', 'AGENTS.md'),
+            };
+        case 'claude':
+            return {
+                client,
+                mcpConfigPath: join(home, '.claude.json'),
+                mcpConfigFormat: 'claude-json',
+                skillsDir: join(home, '.claude', 'skills'),
+                instructionsPath: join(home, '.claude', 'CLAUDE.md'),
+            };
+        case 'codex':
+            return {
+                client,
+                mcpConfigPath: join(home, '.codex', 'config.toml'),
+                mcpConfigFormat: 'toml',
+                skillsDir: join(home, '.agents', 'skills'),
+                instructionsPath: join(home, '.codex', 'AGENTS.md'),
+            };
+    }
+}
+function markerPaths(cwd, home, scope, client) {
+    if (scope === 'project') {
+        switch (client) {
+            case 'cursor':
+                return [join(cwd, '.cursor')];
+            case 'claude':
+                return [join(cwd, '.claude')];
+            case 'codex':
+                return [join(cwd, '.codex')];
+        }
+    }
+    switch (client) {
+        case 'cursor':
+            return [join(home, '.cursor')];
+        case 'claude':
+            // Prefer the config dir; also accept the standalone user config file.
+            return [join(home, '.claude'), join(home, '.claude.json')];
+        case 'codex':
+            return [join(home, '.codex')];
+    }
+}
+/**
+ * Detect every supported agent client whose marker path exists.
+ * Detect-all (not first-match-wins). Pure: filesystem access is injected.
+ *
+ * Explicit `requestedClients` (`--client`) is user intent: include those clients
+ * even when their marker directory is missing, so init can force-create config.
+ */
+export function detectClients(opts) {
+    const forced = Boolean(opts.requestedClients?.length);
+    const wanted = forced ? ALL_CLIENTS.filter((id) => opts.requestedClients.includes(id)) : ALL_CLIENTS;
+    const lookedFor = [];
+    const clients = [];
+    for (const client of wanted) {
+        const markers = markerPaths(opts.cwd, opts.home, opts.scope, client);
+        for (const marker of markers) {
+            if (!lookedFor.includes(marker))
+                lookedFor.push(marker);
+        }
+        if (forced || markers.some((m) => opts.exists(m))) {
+            clients.push(opts.scope === 'project' ? projectPaths(opts.cwd, client) : userPaths(opts.home, client));
+        }
+    }
+    return { scope: opts.scope, clients, lookedFor };
+}