@oneshot-agent/sdk 0.59.0 → 0.61.0

package/dist/index.js

@@ -37,6 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.ReadOnlyWalletProvider = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
+const untrusted_content_1 = require("./untrusted-content");
 const hunts_1 = require("./hunts");
 __exportStar(require("./solve"), exports);
 __exportStar(require("./predict"), exports);
@@ -61,13 +62,9 @@ Object.defineProperty(exports, "getSwapQuote", { enumerable: true, get: function
 Object.defineProperty(exports, "executeSwap", { enumerable: true, get: function () { return swap_1.executeSwap; } });
 __exportStar(require("./errors"), exports);
 const approvals_1 = require("./approvals");
-// `./receipt` is NOT re-exported here, values or types: it statically imports
-// `node:crypto`, which would force a hard Node dependency on every consumer
-// including browser bundles; and its `SignableReceipt.providerCost` field must
-// stay off this public surface (see tests/unit/sdk-provider-cost-removed.test.ts).
-// Import from the `@oneshot-agent/sdk/receipt` subpath instead.
+// Keep receipt on its subpath: node:crypto breaks browser bundles, and providerCost is not public.
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.59.0';
+const SDK_VERSION = '0.61.0';
 /** HTTP poll cadence while push is unconfirmed: fast first checks, settling at 2s. */
 const HTTP_POLL_BACKOFF_MS = [300, 600, 1000, 2000];
 /** HTTP poll cadence once the WebSocket has delivered for this request. */
@@ -106,12 +103,7 @@ function chainIdFromNetwork(network) {
     return m ? Number(m[1]) : undefined;
 }
 const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
-// ETH-currency mode. A payment is an EIP-3009 authorization that the
-// facilitator settles AFTER the API has responded, so for seconds after a
-// successful call `balanceOf` still shows pre-payment funds. The SDK therefore
-// keeps a ledger of signed-but-unsettled authorizations and works from
-// `balanceOf − pending`, over-reserving (one early buffered swap) rather than
-// under-reserving (a failed settlement).
+// Reserve signed-but-unsettled payments against balanceOf so delayed settlement cannot overspend USDC.
 /** One balanceOf read per paid call, deduped within roughly one Base block. */
 const USDC_BALANCE_CACHE_MS = 2000;
 /** How long a signed authorization stays subtracted from the on-chain balance (settlement lands well within this). */
@@ -139,10 +131,7 @@ __exportStar(require("./types"), exports);
  * await agent.email({ to: 'user@example.com', subject: 'Hi', body: 'Hello' });
  * ```
  */
-/**
- * Reject a budget config the server would reject, at construction rather than
- * on the first paid call — a typo'd cap must not become "no cap".
- */
+/** Reject invalid budgets at construction so a typo cannot silently remove the cap. */
 function validateBudgetConfig(budgets) {
     if (!budgets)
         return undefined;
@@ -174,13 +163,13 @@ function validateBudgetConfig(budgets) {
 }
 /** The keys executeToolRequestImpl takes out of a request as SDK options, so they never reach the API body. */
 const PAID_ROUTE_OPTION_KEYS = ['timeout', 'totalTimeoutMs', 'onRequestCreated', 'onAccepted', 'signal', 'onStatusUpdate', 'wait', 'waitForPhones', 'phoneTimeoutSec', 'idempotencyKey', 'approvalId', 'maxCost'];
-/** ETH mode is unsupported on CDP wallets (#2153): the swap path needs a confirmed receipt CDP never returns. */
+/** ETH mode is unsupported on CDP wallets: the swap path needs a confirmed receipt CDP never returns. */
 function cdpEthModeError() {
     return new errors_2.ValidationError("ETH currency mode is not supported with CDP wallets; fund the CDP wallet with USDC or use currency: 'USDC' (or a privateKey / custom walletProvider for ETH mode)", 'currency');
 }
 class OneShot {
     /**
-     * Async factory — required for CDP wallets (account creation is async).
+     * Async factory, required for CDP wallets (account creation is async).
      * Also works with privateKey and custom walletProvider.
      *
      * @example
@@ -196,8 +185,7 @@ class OneShot {
         if (config.accessToken) {
             if (config.address)
                 return new OneShot(config);
-            // The API keys job status and the WebSocket on X-Agent-ID, so the
-            // session needs its wallet address even though it never signs with it.
+            // Job status and WebSocket requests need the wallet address even when the session never signs.
             const address = await OneShot.resolveTokenAddress(config);
             return new OneShot({ ...config, address });
         }
@@ -205,7 +193,7 @@ class OneShot {
             return new OneShot(config, config.walletProvider);
         }
         if (config.cdp) {
-            // Reject before the CDP SDK is imported or an account is created (#2153).
+            // Reject before importing the CDP SDK or creating an account.
             if ((config.currency ?? 'USDC') === 'ETH')
                 throw cdpEthModeError();
             const { CdpWalletProvider } = await Promise.resolve().then(() => __importStar(require('./providers/cdp')));
@@ -221,7 +209,7 @@ class OneShot {
         throw new errors_2.ValidationError('Provide one of: privateKey, cdp, or walletProvider', 'config');
     }
     /**
-     * Sync constructor — works with privateKey (backwards compatible).
+     * Sync constructor; works with privateKey.
      * For CDP wallets, use OneShot.create() instead.
      */
     constructor(config, walletProvider) {
@@ -260,9 +248,7 @@ class OneShot {
         this._stagingKey = config.stagingKey;
         this.rpcProvider = new ethers_1.ethers.JsonRpcProvider(config.rpcUrl ?? RPC_URL);
         if (config.accessToken) {
-            // Option D: access-token session. Exclusive with every wallet option,
-            // and budgets are read-only (a delegated credential that could raise its
-            // own cap would make the cap meaningless) — set them from a wallet.
+            // Delegated tokens cannot change their own budgets; caps must be set from a wallet session.
             if (!/^oneshot_[0-9a-f]{64}$/.test(config.accessToken)) {
                 throw new errors_2.ValidationError('accessToken must be oneshot_<64 lowercase hex characters>', 'accessToken');
             }
@@ -297,9 +283,7 @@ class OneShot {
         else {
             throw new errors_2.ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
         }
-        // CDP wallets cannot run ETH mode even though CdpWalletProvider exposes
-        // sendTransaction: its wait() never observes a receipt, so the swap path
-        // cannot confirm the ETH→USDC trade (#2153).
+        // CDP wait() never confirms a receipt, so ETH mode cannot confirm the swap.
         if (config.cdp && this._currency === 'ETH')
             throw cdpEthModeError();
         if (this._currency === 'ETH' && !this.provider.sendTransaction) {
@@ -342,16 +326,8 @@ class OneShot {
             this.validate(options.subject, 'subject');
         }
         this.validate(options.body, 'body');
-        // Rotation mode: when the caller passes neither from_domain nor
-        // from_mailbox, omit from_address entirely so the server picks from
-        // the agent's domain pool. The chosen address comes back on the
-        // quote response (`quote.from_address`) and we replay it on /send.
-        // When the caller pins from_domain (with or without from_mailbox), we
-        // build `${mailbox ?? 'agent'}@${from_domain}`. Pinning from_mailbox
-        // alone has no domain to attach it to — `oneshotagent.com` is OneShot's
-        // own domain and no agent can send from it — so that combination is a
-        // client-side validation error rather than a guaranteed domain_not_owned
-        // rejection from the server.
+        // Without a pinned sender, the quote locks an address from the agent's domain pool.
+        // A mailbox alone has no owned domain to send from.
         if (options.from_mailbox && !options.from_domain) {
             throw new errors_2.ValidationError('from_mailbox was pinned without from_domain. Pass from_domain (a domain you own) as well, or omit both to rotate across your warmed domains.', 'from_domain');
         }
@@ -359,24 +335,14 @@ class OneShot {
         const fromAddress = useRotation
             ? undefined
             : `${options.from_mailbox ?? 'agent'}@${options.from_domain}`;
-        // Confirming a new-domain registration (#1070): the caller passes back the
-        // quote_id of the `confirmation_required` result it was shown. That quote
-        // is sent as-is — no second quote — so the server charges the stored total
-        // of the quote the user saw (x402-legacy validates the id and takes the
-        // amount from the stored quote). A bare `true` is not a confirmation: it
-        // names no amount, so it falls through to the quote-only path below. An
-        // expired or already-used quote is refused by the server, and the next
-        // unconfirmed call produces a fresh quote to show again.
+        // Reuse the confirmed quote so the charge matches the amount shown; true alone confirms no amount.
         const confirmedQuote = typeof options.confirmNewDomain === 'string' && options.confirmNewDomain.trim()
             ? options.confirmNewDomain.trim() : undefined;
         if (confirmedQuote) {
             this.log(`Email: sending against confirmed quote ${confirmedQuote}`);
             return this.executeToolRequest('/v1/tools/email/send', this.emailSendPayload(options, fromAddress), confirmedQuote);
         }
-        // `mailbox_provisioning_fee` (>0) means `from_address` is a new address that
-        // provisions a mailbox on first send — a one-time fee folded into `total_cost`.
-        // `is_new` (true) means this quote would register a brand-new domain, which
-        // drives the confirm-before-charge gate below (#1070 round 2).
+        // Mailbox provisioning and domain registration are distinct fees; only a new domain needs confirmation.
         const quote = await this.tool('email/quote', {
             ...(fromAddress ? { from_address: fromAddress } : {}),
             ...(options.to !== undefined ? { to_address: options.to } : {}),
@@ -384,23 +350,12 @@ class OneShot {
             ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
             ...(options.mailbox_mode ? { mailbox_mode: options.mailbox_mode } : {}),
             body: options.body,
-            // Forward maxCost so the server-side X-Max-Cost-USDC header is set on
-            // the quote fetch (executeToolRequest destructures + threads it).
             maxCost: options.maxCost,
         });
         this.log(`Email quote: $${quote.total_cost}`);
-        // Local fast-fail — matches the per-tool check on commerce/voice/sms/build/
-        // browser/compute. If the server-side header guard fired we'd never reach
-        // here; this catches the case where the server's enforcement is bypassed
-        // (e.g. a future API revision without the header check) or skipped (cap
-        // un-set so the server returned a 200 with the quote and the caller still
-        // wants the local guard to apply).
+        // Enforce the cap locally even if the server did not check the header.
         this.assertWithinMaxCost(quote.total_cost, options.maxCost);
-        // Registering a brand-new domain is charged only after its exact quote has
-        // been shown and explicitly authorized (#1070 round 2) — this call stops
-        // here, before /email/send, and charges nothing. Pass confirmNewDomain:
-        // true (with the same from_domain) to register the domain, pay the quoted
-        // total, and send the email in one follow-up call.
+        // A new domain must be explicitly authorized against its exact quote before any charge or send.
         if (quote.is_new) {
             const domainName = quote.domain ?? options.from_domain ?? '';
             const breakdown = quote.registration_fee !== undefined && quote.service_fee !== undefined
@@ -423,16 +378,11 @@ class OneShot {
     /** The /email/send body for `email()`: the same whether it follows a fresh quote or a confirmed one. */
     emailSendPayload(options, resolvedFromAddress) {
         const payload = {
-            // Server replays the locked address from the quote when from_address
-            // is absent, but sending it anyway is harmless and forward-compatible
-            // with future SDK versions that talk directly to /send without quoting.
             ...(resolvedFromAddress ? { from_address: resolvedFromAddress } : {}),
             ...(options.to !== undefined ? { to_address: options.to } : {}),
             ...(options.subject !== undefined ? { subject: options.subject } : {}),
             ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
-            // Re-passed on /send so a new-domain mailbox quote still provisions a real
-            // mailbox even though the domain row doesn't exist yet (server also falls back
-            // to 'mailbox' when a provisioning fee was paid on the quote).
+            // Preserve mailbox provisioning when the new domain does not yet have a stored mode.
             ...(options.mailbox_mode ? { mailbox_mode: options.mailbox_mode } : {}),
             body: options.body,
             signal: options.signal,
@@ -446,15 +396,14 @@ class OneShot {
             payload.attachments = options.attachments;
         }
         if (options.idempotencyKey) {
-            // Only the send call carries the key — the quote call has no side effects.
+            // Only sends need idempotency; quoting has no side effects.
             payload.idempotencyKey = options.idempotencyKey;
         }
         if (options.approvalId) {
             // Releases a send the action policy held (see ApprovalRequiredError).
             payload.approvalId = options.approvalId;
         }
-        // Forward maxCost so the server-side X-Max-Cost-USDC header also guards
-        // the send, which matters on a confirmed send that skipped the quote.
+        // Confirmed sends skip quoting, so the send must also carry the cap.
         if (options.maxCost !== undefined)
             payload.maxCost = options.maxCost;
         return payload;
@@ -515,7 +464,7 @@ class OneShot {
         const { includePhone, ...payload } = options;
         return this.tool('find/person', { ...payload, include_phone: includePhone, limit: options.limit ?? 100 });
     }
-    /** At least one identity (#1899): name, email, phone or a profile URL under any of its names. */
+    /** At least one identity: name, email, phone or a profile URL under any of its names. */
     requirePersonIdentity(options) {
         const hasName = options.name || options.full_name || (options.first_name && options.last_name);
         if (!hasName && !options.email && !options.phone && !options.profile_url && !options.linkedin_url && !options.social_media_url) {
@@ -562,7 +511,7 @@ class OneShot {
         return this.tool('resolve/business', { ...options });
     }
     /**
-     * Federal contract opportunities (SAM.gov) by NAICS code — Sources Sought
+     * Federal contract opportunities (SAM.gov) by NAICS code - Sources Sought
      * and Presolicitation notices with the contracting officer's published
      * contact. Flat price per search; zero notices is a completed result.
      * `data_as_of` on the result is the snapshot behind the rows (SAM.gov's
@@ -593,7 +542,7 @@ class OneShot {
     async personDossier(options) {
         this.requirePersonIdentity(options);
         const { includePhone, ...payload } = options;
-        // The dossier takes 2 to 5 minutes; the generic 120 second poll gives up on a normal run (#1913).
+        // The dossier takes 2 to 5 minutes; the generic 120 second poll gives up on a normal run.
         return this.tool('lookup/person-dossier', { ...payload, include_phone: includePhone, timeout: options.timeout ?? 300 });
     }
     async personSocialAccounts(options) {
@@ -629,7 +578,7 @@ class OneShot {
         if (!response.ok) {
             throw new errors_2.ToolError('Failed to list inbox', response.status, await response.text(), response.headers.get('retry-after'));
         }
-        return response.json();
+        return (0, untrusted_content_1.markUntrusted)(await response.json(), 'inbox_list');
     }
     async inboxGet(emailId) {
         this.validate(emailId, 'emailId');
@@ -642,7 +591,7 @@ class OneShot {
         if (!response.ok) {
             throw new errors_2.ToolError('Failed to get email', response.status, await response.text(), response.headers.get('retry-after'));
         }
-        return response.json();
+        return (0, untrusted_content_1.markUntrusted)(await response.json(), 'inbox_get');
     }
     async commerceBuy(options) {
         this.validate(options.product_url, 'product_url');
@@ -754,9 +703,9 @@ class OneShot {
         if (options.wait !== false && result.request_id) {
             // Wait for the longest the call may run, plus two minutes to dial and settle.
             const timeout = options.timeout ?? (options.max_duration_minutes ?? 10) * 60 + 120;
-            return this.pollJob(result.request_id, timeout, options.signal, options.onStatusUpdate);
+            return this.pollJob(result.request_id, timeout, options.signal, options.onStatusUpdate, undefined, 'voice');
         }
-        return result;
+        return (0, untrusted_content_1.markUntrusted)(result, 'voice');
     }
     /**
      * Send an SMS message
@@ -947,8 +896,6 @@ class OneShot {
             payload.session_id = options.session_id;
         if (options.profile_id)
             payload.profile_id = options.profile_id;
-        if (options.secrets !== undefined)
-            throw new errors_2.ValidationError('secrets is unsupported; import cookies or storage_state with createBrowserProfile', 'secrets');
         if (options.max_steps)
             payload.max_steps = options.max_steps;
         const { execResp } = await this.runQuoteToPay({
@@ -972,9 +919,9 @@ class OneShot {
         const result = await execResp.json();
         this.log(`Browser task initiated: ${result.request_id}`);
         if (options.wait !== false && result.request_id) {
-            return this.pollJob(result.request_id, options.timeout ?? 300, options.signal, options.onStatusUpdate);
+            return this.pollJob(result.request_id, options.timeout ?? 300, options.signal, options.onStatusUpdate, undefined, 'browser');
         }
-        return result;
+        return (0, untrusted_content_1.markUntrusted)(result, 'browser');
     }
     /**
      * Create a persistent browser profile for reusing cookies/localStorage across sessions
@@ -1094,7 +1041,7 @@ class OneShot {
                 throw new errors_1.LinkedInConnectRequiredError(body);
             throw new errors_2.ToolError(`LinkedIn ${opts.what} failed`, response.status, body, response.headers.get('retry-after'));
         }
-        return response.json();
+        return (0, untrusted_content_1.markUntrusted)(await response.json(), `/v1/tools/linkedin${path}`, method);
     }
     /**
      * Create a hosted LinkedIn login link. Show `url` to the human once; it
@@ -1222,7 +1169,6 @@ class OneShot {
         this.validate(options.identifier, 'identifier');
         const { accountId, identifier, notify, sections, ...rest } = options;
         const body = { ...rest, account_id: accountId, identifier, notify: !!notify, timeout: options.timeout ?? 180 };
-        // Left off the wire when empty, so a view without sections is the request it always was.
         if (sections?.length)
             body.sections = sections;
         const result = await this.tool('linkedin/profile-view', body);
@@ -1285,7 +1231,7 @@ class OneShot {
         if (!response.ok) {
             throw new errors_2.ToolError('Failed to list SMS inbox', response.status, await response.text(), response.headers.get('retry-after'));
         }
-        return response.json();
+        return (0, untrusted_content_1.markUntrusted)(await response.json(), 'sms_inbox_list');
     }
     /**
      * Get this agent a voice number without placing a call. Returns the existing
@@ -1368,7 +1314,7 @@ class OneShot {
         return this.signedJson('GET', `/v1/tools/voice/inbound/${encodeURIComponent(callId)}`, undefined, 'read', 'Failed to get inbound call');
     }
     /**
-     * Call a declared route of the API by method and path (#1580), the one generic call for a route that has no
+     * Call a declared route of the API by method and path, the one generic call for a route that has no
      * typed method. Follows the Python client's `call_free_get/post/patch/put/delete`:
      *
      * - `path` is the route, with `{name}` (or `:name`) for a path parameter, filled from `params` and URL-encoded
@@ -1448,7 +1394,7 @@ class OneShot {
                 if (response.status === 204 || !text)
                     return { success: true };
                 const json = JSON.parse(text);
-                return (json && typeof json === 'object' && 'data' in json ? json.data : json);
+                return (0, untrusted_content_1.markUntrusted)(json && typeof json === 'object' && 'data' in json ? json.data : json, target, method);
             })();
             return await (0, deadline_1.abortable)(request, scope.signal);
         }
@@ -1470,7 +1416,7 @@ class OneShot {
             throw new errors_2.ToolError(failure, response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
-        return (json.data ?? json);
+        return (0, untrusted_content_1.markUntrusted)(json.data ?? json, path, method);
     }
     /**
      * Get a specific inbound SMS message
@@ -1492,7 +1438,7 @@ class OneShot {
         if (!response.ok) {
             throw new errors_2.ToolError('Failed to get SMS message', response.status, await response.text(), response.headers.get('retry-after'));
         }
-        return response.json();
+        return (0, untrusted_content_1.markUntrusted)(await response.json(), 'sms_inbox_get');
     }
     /**
      * List notifications for the agent
@@ -1541,7 +1487,7 @@ class OneShot {
         }
     }
     /**
-     * The agent's connections (#2403): GitHub and business systems, each with `id`, `system`, `account_label` and
+     * The agent's connections: GitHub and business systems, each with `id`, `system`, `account_label` and
      * `status`. Free. A connected-system read (ledger, CRM, shipping, tax, procurement) takes the `id` of an active
      * one as `connection_id`; pick it by `system` and `account_label`, then call the read with the generic
      * {@link OneShot.route}.
@@ -1570,12 +1516,10 @@ class OneShot {
         return response.json();
     }
     async getBalance(tokenAddress) {
-        // Use unified API endpoint for USDC (default) balance
         if (!tokenAddress || tokenAddress === this.usdcAddress) {
             const unified = await this.getUnifiedBalance();
             return unified.on_chain_balance;
         }
-        // Custom token: keep existing RPC logic
         const contract = new ethers_1.ethers.Contract(tokenAddress, ['function balanceOf(address) view returns (uint256)', 'function decimals() view returns (uint8)'], this.rpcProvider);
         const [balance, decimals] = await Promise.all([
             contract.balanceOf(this.provider.address),
@@ -1584,7 +1528,7 @@ class OneShot {
         return ethers_1.ethers.formatUnits(balance, decimals);
     }
     /**
-     * Create a compute goal — the orchestrator will plan, execute, and iterate autonomously.
+     * Create a compute goal - the orchestrator will plan, execute, and iterate autonomously.
      *
      * Uses the quote-then-pay flow: first call gets a 402 with a budget estimate,
      * second call (with payment) creates the goal.
@@ -1623,7 +1567,9 @@ class OneShot {
             payload.approvals = options.approvals;
         if (options.done_check)
             payload.done_check = options.done_check;
-        // Compute returns the goal directly on 202 — no job polling, unlike the
+        if (options.egress_allowlist)
+            payload.egress_allowlist = options.egress_allowlist;
+        // Compute returns the goal directly on 202 - no job polling, unlike the
         // other paid tools.
         const { execResp: createResp } = await this.runQuoteToPay({
             endpoint: '/v1/compute',
@@ -1681,7 +1627,7 @@ class OneShot {
      * with JobError (goal ID, end_reason code, snapshot in partialResult).
      * Budget exhaustion ends this wait; after fundComputeGoal revives the goal,
      * call waitForComputeGoal again with the same ID to observe the new run.
-     * Paused/awaiting_confirmation and recurring goals keep waiting until the
+     * Paused/awaiting_confirmation/awaiting_connection and recurring goals keep waiting until the
      * goal ends or the timeout (seconds, default 120) expires with JobTimeoutError.
      * Infinity disables the local deadline.
      * onStatusUpdate receives each distinct observed status before settlement.
@@ -1907,6 +1853,30 @@ class OneShot {
         const json = await response.json();
         return json.data;
     }
+    /**
+     * Dispute a goal that ended `impossible_unverified`: the loop claimed it
+     * cannot be done with no proof code could check. The dispute is recorded
+     * on the goal and its receipt; nothing is refunded.
+     *
+     * @example
+     * ```typescript
+     * await agent.disputeComputeGoal(goalId, { reason: 'The data is public.' });
+     * ```
+     */
+    async disputeComputeGoal(goalId, input = {}) {
+        this.validate(goalId, 'goalId');
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/respond`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
+            body: JSON.stringify({ dispute: true, ...(input.reason ? { response: input.reason } : {}) }),
+        });
+        if (response.status === 404)
+            throw new errors_2.ToolError('Goal not found', 404, await response.text(), response.headers.get('retry-after'));
+        if (!response.ok)
+            throw new errors_2.ToolError('Failed to dispute compute goal', response.status, await response.text(), response.headers.get('retry-after'));
+        const json = await response.json();
+        return json.data;
+    }
     /**
      * Pause a recurring compute goal
      *
@@ -2106,7 +2076,7 @@ class OneShot {
      * List receipts with optional filtering
      *
      * Paginate with `limit`/`offset`, or page through an explicit time window with
-     * `since`/`until` (ISO string or Date) — useful for reaching receipts older than
+     * `since`/`until` (ISO string or Date) - useful for reaching receipts older than
      * the server's 100-row cap when tagging value weeks after the originating call.
      *
      * @example
@@ -2144,8 +2114,8 @@ class OneShot {
      * Three ways to address the value:
      * - `rcpt_…` receipt id (from `result.receipt_id` or `receiptsList`), or
      * - the `request_id` returned by the originating tool call (`result.request_id`,
-     *   resolved server-side via `Receipt.job_id`) — annotate without a list lookup, or
-     * - a `goalId` correlation key — attributes a whole *cadence* outcome (the email,
+     *   resolved server-side via `Receipt.job_id`) - annotate without a list lookup, or
+     * - a `goalId` correlation key - attributes a whole *cadence* outcome (the email,
      *   the follow-ups, the find/verify/enrich calls that share `decisionContext.goalId`)
      *   in one call. The value is recorded once in the outcome ledger, so it can't
      *   double-count across the cadence's receipts. Read it back with `rocsByGoal()`.
@@ -2159,13 +2129,12 @@ class OneShot {
      * const r = await agent.personEmailStatus({ email: 'x@y.com' });
      * await agent.tagReceiptValue({ requestId: r.request_id }, { type: 'lead', amount: 1 });
      *
-     * // By cadence correlation key — one call attributes a closed deal to the whole sequence:
+     * // By cadence correlation key - one call attributes a closed deal to the whole sequence:
      * await agent.tagReceiptValue({ goalId: 'goal_q2_acme' }, { type: 'revenue', amount: 5000, label: 'Closed deal' });
      * ```
      */
     async tagReceiptValue(ref, valueTag) {
         this.validate(valueTag.type, 'valueTag.type');
-        // Cadence-level: route to the outcome ledger by correlation key.
         if (typeof ref === 'object' && ref.goalId && !ref.receiptId && !ref.requestId) {
             const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/outcomes`, {
                 method: 'POST',
@@ -2192,7 +2161,7 @@ class OneShot {
         }
     }
     /**
-     * Per-cadence RoCS rollup — spend (from receipts) vs. value (from outcomes)
+     * Per-cadence RoCS rollup - spend (from receipts) vs. value (from outcomes)
      * grouped by `decisionContext.goalId`. Answers "what did this cadence cost vs.
      * earn" in one query. `value` counts judge-confirmed outcomes; `pending_value`
      * surfaces self-reported outcomes not yet confirmed.
@@ -2273,15 +2242,8 @@ class OneShot {
     jsonHeaders() {
         return { 'Content-Type': 'application/json', ...this.headers() };
     }
-    /**
-     * Auth headers plus a signed EIP-712 proof (`x-agent-proof`) for the read
-     * routes (inbox, sms inbox, notifications, balance). These identify the caller
-     * by wallet, and wallet addresses are public, so without a proof anyone could
-     * read another agent's data by supplying its address. The proof binds this
-     * request to the wallet the SDK controls; the server verifies the signature
-     * locally. A fresh nonce per call prevents replay. Signing failure falls back
-     * to plain headers, with a one-time warning.
-     */
+    /** Signed, single-use proofs bind requests to the wallet; an address alone cannot authenticate reads.
+     * Signing failure falls back to plain headers with a one-time warning. */
     async signedReadHeaders(scope = 'read', domainName = 'OneShot Agent Auth') {
         const base = this.headers();
         // The bearer token already binds the request to the agent (and is
@@ -2293,12 +2255,7 @@ class OneShot {
             const issuedAt = Math.floor(Date.now() / 1000) + (domainName === 'OneShot Agent Auth' ? this.proofClockOffsetSec : 0);
             const nonce = ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(32));
             const signature = await this.provider.signTypedData(
-            // `domainName` lets a different origin (e.g. Soul Hunt, which keeps
-            // its own nonce store — see hunts.ts) use a DIFFERENT EIP-712 domain
-            // than api-service's. EIP-712 mixes the domain into the signed hash,
-            // so a proof is only valid for the one origin it was signed for and
-            // can't be replayed across service boundaries (security finding
-            // F-t_d4805d6f-3, round 2).
+            // Separate EIP-712 domains prevent proof replay across services with independent nonce stores.
             { name: domainName, version: '1' }, {
                 AgentReadAuth: [
                     { name: 'agent', type: 'address' },
@@ -2312,9 +2269,7 @@ class OneShot {
             return { ...base, 'x-agent-proof': proof };
         }
         catch (err) {
-            // Once per client, even without debug: when the API enforces proofs,
-            // these requests will be rejected, and a silent fallback would leave
-            // the caller with a 401 and no idea why.
+            // Warn once even without debug so a failed proof explains the ensuing authentication failure.
             if (!this.readProofWarned) {
                 this.readProofWarned = true;
                 this.logger(`[OneShot] Warning: could not sign the x-agent-proof read proof, so requests go without it and will be rejected where the API enforces proofs. Pass a signer that supports signTypedData, or use an access token. Cause: ${err}`);
@@ -2325,14 +2280,15 @@ class OneShot {
             return base;
         }
     }
-    /** Retry a clock-window refusal once, before the API has dispatched the request.
-     * Only this API's proof clock changes; payments and other services keep their own clocks.
-     * Callers supply replayable JSON bodies and retain their original abort/deadline signal.
-     */
+    /** Retry a clock-window refusal once using the API's server_time, or a spent nonce on GET/HEAD.
+     * Never retry a spent nonce on a write: the first delivery may already have executed it.
+     * Callers supply replayable JSON bodies and retain their original abort/deadline signal. */
     async fetchApi(url, init) {
-        const response = await fetch(url, init);
-        const headers = new Headers(init.headers);
-        const proof = headers.get('x-agent-proof');
+        const proof = new Headers(init.headers).get('x-agent-proof');
+        // Disable connection reuse where supported to prevent transport retries from replaying a single-use proof.
+        // Browsers control their own pooling; only replayed reads can be safely retried there.
+        const deliver = (headers) => fetch(url, proof ? { ...init, headers: OneShot.singleDelivery(headers), keepalive: false } : init);
+        const response = await deliver(init.headers);
         if (response.status !== 401 || !proof || this._accessToken)
             return response;
         const origin = new URL(this.baseUrl).origin;
@@ -2342,30 +2298,50 @@ class OneShot {
         let serverTime;
         try {
             const body = await response.clone().json();
-            if (body?.error !== 'proof_required' ||
-                !['proof expired', 'proof issued in the future'].some(reason => body.message === `This endpoint requires a signed agent proof (x-agent-proof): ${reason}`) ||
-                typeof body.server_time !== 'number' || !Number.isSafeInteger(body.server_time) || body.server_time <= 0)
+            if (body?.error !== 'proof_required' || typeof body.message !== 'string')
+                return response;
+            const prefix = 'This endpoint requires a signed agent proof (x-agent-proof): ';
+            const reason = body.message.startsWith(prefix) ? body.message.slice(prefix.length) : '';
+            const clockRefusal = reason === 'proof expired' || reason === 'proof issued in the future';
+            const method = (init.method ?? 'GET').toUpperCase();
+            const replayedRead = reason === 'proof nonce already used (replay)' && (method === 'GET' || method === 'HEAD');
+            if (!clockRefusal && !replayedRead)
                 return response;
+            if (clockRefusal) {
+                if (typeof body.server_time !== 'number' || !Number.isSafeInteger(body.server_time) || body.server_time <= 0)
+                    return response;
+                serverTime = body.server_time;
+            }
             const sent = JSON.parse(typeof Buffer !== 'undefined' ? Buffer.from(proof, 'base64').toString('utf-8') : atob(proof));
             if (typeof sent.scope !== 'string')
                 return response;
             scope = sent.scope;
-            serverTime = body.server_time;
         }
         catch {
             return response;
         }
         init.signal?.throwIfAborted();
-        this.proofClockOffsetSec = serverTime - Math.floor(Date.now() / 1000);
+        if (serverTime !== undefined)
+            this.proofClockOffsetSec = serverTime - Math.floor(Date.now() / 1000);
         const refreshed = await this.signedReadHeaders(scope);
         init.signal?.throwIfAborted();
         if (!refreshed['x-agent-proof'])
             return response;
-        headers.set('x-agent-proof', refreshed['x-agent-proof']);
-        return fetch(url, { ...init, headers });
+        const retryHeaders = new Headers(init.headers); // Keep the caller's headers intact.
+        retryHeaders.set('x-agent-proof', refreshed['x-agent-proof']);
+        return deliver(retryHeaders);
+    }
+    /** The caller's headers plus `Connection: close`, in the caller's own shape (a plain record stays a record).
+     * Runtimes that treat `Connection` as a forbidden request header (browsers) drop it silently; nothing throws. */
+    static singleDelivery(headers) {
+        if (headers instanceof Headers || Array.isArray(headers)) {
+            const copy = new Headers(headers);
+            copy.set('connection', 'close');
+            return copy;
+        }
+        return { ...Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => name.toLowerCase() !== 'connection')), Connection: 'close' };
     }
-    /** Build a query string, skipping null/undefined values. Pass falsy-but-valid
-     *  values (0, '') as undefined at the call site to match prior `if (x)` guards. */
+    /** Skip null/undefined query values; callers must explicitly omit other unwanted falsy values. */
     buildQuery(params) {
         const qs = new URLSearchParams();
         for (const [k, v] of Object.entries(params)) {
@@ -2374,20 +2350,8 @@ class OneShot {
         }
         return qs.toString();
     }
-    /**
-     * Push `config.budgets` to the server once, before the first paid call.
-     *
-     * Lazy rather than in the constructor because the PUT is signed (async) and
-     * the constructor is sync. Idempotent per instance via the cached promise,
-     * which is only kept once the sync SUCCEEDS.
-     *
-     * FAILS CLOSED. If the server can't confirm the budget — network error,
-     * 5xx, 429, or a rejected config — this throws BudgetSyncError and the paid
-     * call is not made. Proceeding would silently drop the guardrail the
-     * developer configured, which is exactly the "empty wallet at 3am" the
-     * budget exists to prevent. The marker is cleared so the next paid call
-     * retries.
-     */
+    /** Sync budgets lazily because signing is async; concurrent calls share the cached promise.
+     * Fail closed until the server confirms the budget, and clear failed syncs so the next call retries. */
     async ensureBudgetsSynced() {
         if (!this._budgets && !this._alertEmail)
             return;
@@ -2427,19 +2391,12 @@ class OneShot {
             await attempt;
         }
         catch (err) {
-            // Not synced: clear the marker so the next paid call retries, then
-            // refuse this one rather than run it unguarded.
             this._budgetSync = undefined;
             this.log(`${err.message} — paid call refused until the budget is confirmed`);
             throw err;
         }
     }
-    /**
-     * Local fast-fail on the per-transaction cap, so an oversized call fails
-     * without a network round-trip. The server enforces the same cap (and the
-     * daily one, which needs the ledger) regardless of which client calls —
-     * this is the same SDK-checks/server-enforces split as maxCost.
-     */
+    /** Fail oversized calls locally before a round-trip; the server also enforces shared daily spend. */
     assertWithinBudget(total) {
         const cap = this._budgets?.perTransaction;
         if (!cap || cap <= 0)
@@ -2509,7 +2466,7 @@ class OneShot {
         const body = await response.json();
         return body.data;
     }
-    /** List this agent's access tokens (prefix, label, last use, spend today — never the token). */
+    /** List this agent's access tokens (prefix, label, last use, spend today - never the token). */
     async listAccessTokens(opts = {}) {
         this.assertWalletSession('list access tokens');
         const response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/access-tokens${opts.activeOnly ? '?active=true' : ''}`, {
@@ -2539,41 +2496,10 @@ class OneShot {
             throw new errors_2.OneShotError(`Quote $${total} exceeds maxCost $${maxCost}`);
         }
     }
-    /**
-     * Header that asks the API to reject the request when the computed quote
-     * exceeds the caller-supplied cap (commit 8f328a7). The SDK still does its
-     * own local `quote.total > maxCost` check after the 402 returns — this is
-     * a server-side enforcement layer so non-SDK callers (MCP server, custom
-     * integrations) can't ignore the cap.
-     */
-    /**
-     * The amount to sign, in decimal USDC.
-     *
-     * A 402 advertises its price twice: the x402 v2 `PAYMENT-REQUIRED` header
-     * (`accepts[0].amount`, atomic units) and the legacy JSON body
-     * (`payment_request.amount`, decimal). The header is authoritative — it is
-     * what the server rebuilds its requirement from and what
-     * `findMatchingRequirements` compares the signature against.
-     *
-     * Preferring the body is how quote-based routes (email/send, sms, voice,
-     * build, commerce/buy, compute) silently failed: the body carried a
-     * hardcoded "0.00", so the SDK signed a zero-cost authorization against a
-     * real charge and the server answered with a bodiless 402. It stayed hidden
-     * for as long as credits covered those calls, since the credit path returns
-     * 202 without any payment handshake.
-     *
-     * Falls back to the body when the header is missing or unparseable.
-     */
-    /**
-     * Throw the most specific error a failed response supports.
-     *
-     * A 402 arriving on the PAID retry means the facilitator refused the
-     * signature — not the ordinary "here is your quote" 402. The API names the
-     * cause in that body (`payment_verification_failed` + reason + expected vs
-     * received amount); surface it as a `PaymentError` so callers can branch on
-     * `err.reason` instead of string-matching. Anything else keeps the existing
-     * `ToolError` shape.
-     */
+    /** Ask the API to enforce the caller's cap before payment, in addition to the local quote check. */
+    /** Resolve decimal USDC from the authoritative PAYMENT-REQUIRED header (atomic units);
+     * fall back to the legacy body only when the header is missing or unparseable. */
+    /** A 402 on the paid retry is a payment rejection, not a quote; expose its cause as PaymentError. */
     async failFromResponse(message, response) {
         const text = await response.text();
         const credits = response.status === 402 ? this.parseInsufficientCredits(text) : undefined;
@@ -2607,14 +2533,7 @@ class OneShot {
         const num = (v) => (typeof v === 'string' || typeof v === 'number') && Number.isFinite(parseFloat(String(v))) ? parseFloat(String(v)) : undefined;
         return new errors_1.InsufficientCreditsError(body.message ?? 'Credit balance does not cover this call', num(body.required_usdc), num(body.credits_balance), num(body.shortfall_usdc));
     }
-    /**
-     * Access-token sessions never sign. When a paid call answers 402 the SDK
-     * either got the server's `insufficient_credits` verdict (throw it) or a
-     * quote (re-POST with `x-quote-id` and no payment: the server executes
-     * when the quote's credits cover it, otherwise answers `insufficient_credits`
-     * with the balance and shortfall, which failFromResponse turns into the
-     * typed error). Server-decided on purpose — the SDK holds no ledger.
-     */
+    /** Token sessions never sign: retry the quote against credits and let the server ledger decide sufficiency. */
     async retryAsCreditsSession(body, endpoint, payload, quoteId, signal, timeoutMs, extraHeaders) {
         const credits = body ? this.parseInsufficientCredits(body) : undefined;
         if (credits)
@@ -2723,10 +2642,7 @@ class OneShot {
             return bodyAmount ?? '0';
         }
         const fromHeader = ethers_1.ethers.formatUnits(accepted.amount, 6);
-        // When the two agree (every fixed-price route), keep the body's string
-        // verbatim — downstream consumers such as the ETH auto-swap pass this
-        // value along, and there is no reason to reformat it. Only a genuine
-        // disagreement flips to the header.
+        // Preserve the body's amount formatting when it agrees with the authoritative header.
         if (bodyAmount != null && parseFloat(bodyAmount) === parseFloat(fromHeader)) {
             return bodyAmount;
         }
@@ -2737,11 +2653,7 @@ class OneShot {
             return undefined;
         return { 'X-Max-Cost-USDC': maxCost.toString() };
     }
-    /**
-     * Idempotency-Key header, sent on both legs (pre-402 and paid retry) so
-     * the server can replay a cached result instead of double-charging and
-     * double-executing on a client retry.
-     */
+    /** Send the idempotency key on both legs so retries cannot double-charge or repeat the action. */
     idempotencyHeader(idempotencyKey) {
         if (!idempotencyKey)
             return undefined;
@@ -2792,7 +2704,7 @@ class OneShot {
                 throw new errors_2.OneShotError('Operation cancelled');
             if (key)
                 options.onRequestCreated?.({ idempotencyKey: key });
-            return await (0, deadline_1.abortable)(this.executeToolRequestImpl(endpoint, { ...options, idempotencyKey: key, signal: scope.signal }, quoteId, context), scope.signal);
+            return (0, untrusted_content_1.markUntrusted)(await (0, deadline_1.abortable)(this.executeToolRequestImpl(endpoint, { ...options, idempotencyKey: key, signal: scope.signal }, quoteId, context), scope.signal), endpoint);
         }
         catch (error) {
             if (scope.timedOut())
@@ -2815,7 +2727,7 @@ class OneShot {
         Object.assign(extraHeaders, this.approvalHeader(approvalId));
         if (payload.memo !== undefined) {
             if (typeof payload.memo !== 'string' || payload.memo.trim().length === 0) {
-                delete payload.memo; // Drop invalid memo silently
+                delete payload.memo; // Invalid optional metadata must not block the call.
             }
             else if (payload.memo.length > 1000) {
                 payload.memo = payload.memo.slice(0, 1000);
@@ -2839,8 +2751,7 @@ class OneShot {
         if (signal?.aborted) {
             throw new errors_2.OneShotError('Operation cancelled');
         }
-        // One-time push of config.budgets before the first paid call, so the
-        // server-side gate knows about them on this very request.
+        // The server must know the configured budget before the first paid request.
         await this.ensureBudgetsSynced();
         if (signal?.aborted)
             throw new errors_2.OneShotError('Operation cancelled');
@@ -2850,7 +2761,6 @@ class OneShot {
             throw new errors_2.OneShotError('Operation cancelled');
         context.phase = 'submission';
         let response = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
-        // Handle 402 Payment Required
         if (response.status === 402 && /\/v1\/tools\/(solve|predict|find\/person|lookup\/person-(profile|dossier))$/.test(endpoint)) {
             ({ execResp: response } = await this.runQuoteToPay({
                 endpoint, payload, signal, maxCost, quoteResponse: response, extraHeaders,
@@ -2860,10 +2770,8 @@ class OneShot {
             context.phase = 'submission';
         }
         else if (response.status === 402) {
-            // Parse x402 v2 PaymentRequired from PAYMENT-REQUIRED header
             const paymentRequiredHeader = response.headers.get('payment-required');
             const { accepted, resource, extensions } = this.parsePaymentRequired(paymentRequiredHeader);
-            // Fallback: parse legacy body format for amount display
             const data = await response.json();
             quoteId ?? (quoteId = data.context?.quote_id);
             if (this._accessToken) {
@@ -2903,7 +2811,6 @@ class OneShot {
             await this.failFromResponse('Tool request failed', response);
         }
         const result = await response.json();
-        // Handle async jobs
         if ((result.status === 'pending' || result.status === 'processing') && result.request_id) {
             context.requestId = String(result.request_id);
             context.receiptId = typeof result.receipt_id === 'string' ? result.receipt_id : undefined;
@@ -2913,7 +2820,7 @@ class OneShot {
             if (!wait) {
                 return { ...result, idempotencyKey };
             }
-            const completed = await this.pollJob(result.request_id, timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined);
+            const completed = await this.pollJob(result.request_id, timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined, endpoint);
             if (completed && typeof completed === 'object' && !Array.isArray(completed)) {
                 return { ...completed, request_id: context.requestId, receipt_id: completed.receipt_id ?? context.receiptId, idempotencyKey };
             }
@@ -2921,13 +2828,7 @@ class OneShot {
         }
         return (result.data ?? result);
     }
-    /**
-     * Shared x402 quote-to-pay flow for paid tools. Fetches the 402 quote, runs
-     * any per-tool 400 handling, enforces maxCost, signs the payment auth, and
-     * POSTs the paid request. Returns the parsed quote context plus the raw paid
-     * Response — the caller owns the post-202 handling (poll a job vs. return the
-     * body directly), since that differs per tool.
-     */
+    /** Shared quote-to-pay flow; callers own post-202 handling because some tools poll and others return directly. */
     async runQuoteToPay(cfg) {
         await this.ensureBudgetsSynced();
         const approval = { ...cfg.extraHeaders, ...this.approvalHeader(cfg.approvalId) };
@@ -2936,8 +2837,6 @@ class OneShot {
             await cfg.on400(quoteResp);
         }
         if (quoteResp.status !== 402) {
-            // Routes the budget gate on the quote leg (fixed-price ones) surface a
-            // 403 here; failFromResponse maps it to BudgetExceededError.
             await this.failFromResponse(cfg.expectMsg, quoteResp);
         }
         const quoteData = await quoteResp.json();
@@ -2986,14 +2885,20 @@ class OneShot {
         this.validate(requestId, 'requestId');
         return this.pollJob(requestId, options.timeout, options.signal, options.onStatusUpdate, options.waitForPhones ? { waitForPhones: true, phoneTimeoutSec: options.phoneTimeoutSec } : undefined);
     }
-    async pollJob(requestId, timeoutSec, signal, onStatusUpdate, phoneOpts) {
-        // HTTP polling is the source of truth; the WebSocket is an accelerator.
-        // Both run concurrently from the start and the first terminal outcome wins,
-        // so a broken push channel (Redis down, worker unconfigured, proxy that
-        // swallows frames) costs nothing beyond the poll cadence. Previously the
-        // client waited 60% of its timeout on the socket before polling at all —
-        // in prod that was ~72s of dead air on every call while the push never came.
-        // An already-aborted signal ends the wait before any proof is signed or sent.
+    unwrapJobResult(job) {
+        const result = job.result ?? job;
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            const value = { ...result };
+            for (const field of ['cached', 'fetched_at']) {
+                if (field in job)
+                    value[field] = job[field];
+            }
+            return value;
+        }
+        return result;
+    }
+    async pollJob(requestId, timeoutSec, signal, onStatusUpdate, phoneOpts, tool = '') {
+        // Race HTTP with WebSocket push so a broken push channel cannot stall job completion.
         if (signal?.aborted)
             throw new errors_2.OneShotError('Operation cancelled');
         const inner = new AbortController();
@@ -3045,31 +2950,15 @@ class OneShot {
             signal?.removeEventListener('abort', onOuterAbort);
         }
         this.log(`Job ${requestId} ready after ${Date.now() - startedAt}ms via ${wait.via ?? 'unknown'}`);
-        // Optional second phase: keep polling for the async phone-reveal webhook.
-        // Only kicks in when the caller explicitly opts in AND the result still
-        // has phones_pending=true (set by the worker when the upstream enrichment
-        // has a pending async phone callback). This is opt-in so existing callers
-        // see no behavior change — the WebSocket/HTTP polls return as soon as the
-        // worker sets status=completed, with phones=null.
-        //
-        // Pass the existing result as the initial fallback: if the polling GETs
-        // hit a transient error before any successful refresh, we return what we
-        // already have (with phones_pending=true still set so consumers know).
+        // Phone reveals are opt-in; retain the completed snapshot if every refresh fails.
         if (phoneOpts?.waitForPhones && this._isPhonesPending(result)) {
             result = await this._pollForPhones(requestId, phoneOpts.phoneTimeoutSec ?? 360, signal, result);
         }
         if (phoneOpts?.waitForPhones)
             notify('completed');
-        return result;
+        return (0, untrusted_content_1.markUntrusted)(result, tool || wait.resultTool || '');
     }
-    /**
-     * Detects whether a job result is still waiting for an async phone reveal.
-     * The worker sets `result.phones_pending=true` when the upstream enrichment
-     * has a pending async webhook and the webhook URL is configured; the webhook
-     * handler flips it to false (or removes it) once phones arrive.
-     *
-     * Accepts worker search rows, profile objects, dossier sections and legacy results.
-     */
+    /** Detect pending phone reveals in search rows, profiles, dossier sections and legacy results. */
     _isPhonesPending(result) {
         if (!result || typeof result !== 'object')
             return false;
@@ -3085,19 +2974,10 @@ class OneShot {
                 || (Array.isArray(body.results) && body.results.some(pending));
         });
     }
-    /**
-     * Slow poll loop that waits for async phone-reveal callbacks to arrive via
-     * the webhook handler (which UPDATEs jobs.result_data.result.phones). Polls
-     * GET /v1/requests/{id} every 5s — the upstream provider can take several
-     * minutes to deliver, so a tight loop just wastes API calls. Returns the
-     * latest snapshot whether or not phones arrived (consumer can re-check
-     * `phones_pending`).
-     */
+    /** Poll phone reveals every 5s to avoid wasting calls during slow callbacks; return the latest snapshot on timeout. */
     async _pollForPhones(requestId, timeoutSec, signal, initialResult) {
         const deadline = Date.now() + timeoutSec * 1000;
         const interval = 5000;
-        // Seed with the snapshot the caller already has so a transient first-poll
-        // failure can still return the sync data (with phones_pending=true).
         let lastResult = initialResult;
         while (Date.now() < deadline) {
             if (signal?.aborted)
@@ -3108,14 +2988,13 @@ class OneShot {
                     signal,
                 });
                 if (!resp.ok) {
-                    // Soft-fail on transient errors during the phone wait — return
-                    // whatever we last had so consumers don't lose the sync result.
+                    // Preserve the last successful snapshot across transient phone-wait errors.
                     if (lastResult !== undefined)
                         return lastResult;
                     throw new errors_2.ToolError('Failed to check job status', resp.status, await resp.text(), resp.headers.get('retry-after'));
                 }
                 const job = await resp.json();
-                lastResult = (job.result ?? job);
+                lastResult = this.unwrapJobResult(job);
                 if (!this._isPhonesPending(lastResult)) {
                     return lastResult;
                 }
@@ -3131,38 +3010,17 @@ class OneShot {
             }
             await this.sleep(interval, signal);
         }
-        // Timeout — return the last snapshot. phones_pending will still be true
-        // so the consumer knows phones never arrived.
         return lastResult;
     }
-    /**
-     * WebSocket branch of a job wait. Resolves on a `completed` push for this
-     * request, rejects with `JobError` on `failed` and with `OneShotError` on
-     * abort. Every other failure (no WebSocket global, handshake refused, socket
-     * closed early) rejects with a plain `Error`, which `pollJob` treats as
-     * "no push available" rather than as an outcome. There is no timeout here:
-     * the HTTP branch owns the deadline and aborts this one when it settles.
-     */
+    /** WebSocket transport failures leave HTTP polling in charge; job outcomes and cancellation settle the wait.
+     * The HTTP branch owns the deadline and aborts this branch when it settles. */
     async waitViaWebSocket(requestId, signal, emit, wait) {
-        // Access-token sessions have no wallet signer to produce a signed proof,
-        // and the standard WebSocket constructor (browser and Node globals alike)
-        // cannot set a custom `Authorization` header on the handshake request —
-        // so there is no way to authenticate this upgrade without putting the
-        // reusable bearer token in the URL, which issue #971 round 1 (finding
-        // F-t_4d087f2a-5) forbids: a bearer secret must never ride in a URL that
-        // proxies, access logs, and telemetry can capture. These sessions skip
-        // the WebSocket accelerator entirely and rely on HTTP polling, which
-        // authenticates via the Authorization header on every request.
+        // WebSocket cannot carry an Authorization header; keep reusable bearer tokens out of logged URLs.
+        // Token sessions use authenticated HTTP polling instead.
         if (this.isAccessTokenSession) {
             throw new Error('WebSocket push is not available for access-token sessions; falling back to HTTP polling');
         }
-        // Build the signed, single-use read proof BEFORE opening the socket: the
-        // server authenticates the upgrade itself (not just the post-upgrade
-        // connection) the same as agentProofAuth does for every other free-read
-        // route (issue #971) — an unsigned ?wallet= alone is no longer
-        // sufficient. Unlike a bearer token, a proof is short-lived and single-use
-        // (5-minute TTL, Redis-enforced nonce), so passing it as a URL query
-        // param is an acceptable channel for it.
+        // Authenticate the upgrade with a short-lived, single-use proof; a wallet address alone proves nothing.
         const authHeaders = await this.signedReadHeaders();
         const authParams = new URLSearchParams();
         if (authHeaders['x-agent-proof'])
@@ -3224,7 +3082,8 @@ class OneShot {
                         settle(() => {
                             cleanup();
                             wait.via = 'ws';
-                            const result = (msg.result ?? msg);
+                            wait.resultTool = typeof msg.result_tool === 'string' ? msg.result_tool : undefined;
+                            const result = this.unwrapJobResult(msg);
                             if (msg.request_id && typeof result === 'object' && result !== null && !('request_id' in result)) {
                                 result.request_id = msg.request_id;
                             }
@@ -3250,7 +3109,6 @@ class OneShot {
                 });
             };
             ws.onclose = () => {
-                // Any close before we got a result means no push is coming.
                 settle(() => {
                     cleanup();
                     reject(new Error('WebSocket closed before result'));
@@ -3298,7 +3156,7 @@ class OneShot {
                 });
                 if (!resp.ok) {
                     const body = await resp.text();
-                    // 5xx / 429 from the poll endpoint are transient — keep polling.
+                    // 5xx / 429 from the poll endpoint are transient - keep polling.
                     // Any other non-2xx (401/403/404) is a real answer about this job.
                     if (resp.status >= 500 || resp.status === 429) {
                         throw new Error(`Poll returned ${resp.status}: ${body.slice(0, 200)}`);
@@ -3309,10 +3167,11 @@ class OneShot {
                 emit?.(String(job.status));
                 if (job.status === 'completed') {
                     this.log('Job completed');
-                    if (wait)
+                    if (wait) {
                         wait.via = 'http';
-                    const result = (job.result ?? job);
-                    // Propagate request_id into the result so callers always have it
+                        wait.resultTool = typeof job.result_tool === 'string' ? job.result_tool : undefined;
+                    }
+                    const result = this.unwrapJobResult(job);
                     if (job.request_id && typeof result === 'object' && result !== null && !('request_id' in result)) {
                         result.request_id = job.request_id;
                     }
@@ -3367,9 +3226,6 @@ class OneShot {
     }
     async makeRequest(endpoint, data, payment, quoteId, signal, timeoutMs, extraHeaders) {
         let resp = await this.sendLeg(endpoint, data, payment, quoteId, signal, timeoutMs, extraHeaders);
-        // The API refuses a request whose wallet proof it rejected, saying why (#1437).
-        // A stale clock window or a proof sent twice is cured by signing a new proof:
-        // send the leg again once. Nothing is paid in answer to this refusal.
         for (let attempt = 0; resp.status === 401; attempt++) {
             const refusal = await this.readInvalidProof(resp);
             if (!refusal)
@@ -3398,22 +3254,10 @@ class OneShot {
         }
     }
     async sendLeg(endpoint, data, payment, quoteId, signal, timeoutMs, extraHeaders) {
-        // A leg with no payment attached proves the wallet with a signed agent
-        // proof: the API spends an agent's credits, and shows them on a quote, only
-        // for a caller that has proven it holds the wallet (a bare X-Agent-ID is a
-        // public address). A leg that carries a payment signature needs none. The
-        // endpoints with durable admission read a 'submit' proof; a caller that
-        // asked for a proof explicitly keeps the scope it always had.
-        //
-        // One payment leg does need a proof: when credits cover the whole cost the
-        // "payment" is the zero-cost authorization, an unsigned stub (signature
-        // '0x'). It proves nothing, and the API refuses to spend credits on it
-        // alone (401 proof_required).
+        // Credit spending requires wallet proof unless a real payment signature already proves ownership.
+        // Zero-cost authorizations are unsigned stubs, so those still need a proof.
         const unsignedStub = payment?.payload?.signature === '0x';
-        // Identity Verification (#2405) answers a retry from the start its key already made, before payment, and
-        // only for a caller that proves the wallet: its payment leg carries the agent proof too, however the key was
-        // given (an option, or the idempotency_key body field the generated MCP tool sends). The API refuses a
-        // payment signature alone there with agent_proof_required. Same list as oneshot-python.
+        // Identity Verification requires wallet proof on the payment leg too, to recover keyed submissions.
         const provenPayment = /(?:^|\/)identity\/start$/.test(endpoint);
         const askedForProof = !!extraHeaders?.['x-agent-proof'];
         const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|solve|predict)$/.test(endpoint)
@@ -3460,14 +3304,8 @@ class OneShot {
             throw new errors_2.OneShotError('Operation cancelled before payment');
         }
     }
-    /**
-     * ETH mode only. Make sure the wallet's *effective* USDC (on-chain balance
-     * minus payments signed but not yet settled) covers this charge, swapping
-     * ETH→USDC for a buffer of `swapBufferMultiplier` payments when it does not,
-     * then reserve the charge. Returns the reservation so the caller can release
-     * it if the payment never settles (request failed). Runs under a per-instance
-     * lock so concurrent calls never double-swap or race the wallet nonce.
-     */
+    /** Reserve effective USDC (on-chain minus unsettled payments), swapping a buffer if needed.
+     * Serialize reservations and swaps to avoid overspending and nonce races; release failed payments. */
     async ensureUsdcBalance(paymentInfo) {
         if (this._currency !== 'ETH')
             return undefined;
@@ -3548,18 +3386,10 @@ class OneShot {
         if (reservation)
             this._usdcPending.delete(reservation.id);
     }
-    /**
-     * How much USDC to buy: top up to `charge × swapBufferMultiplier`, counting
-     * whatever effective balance is already there. When the wallet provider
-     * exposes `getBalance` and its ETH cannot cover the buffered quote, fall
-     * back to the bare shortfall so an ETH-poor wallet can still make the one
-     * payment in front of it (a send-only provider always gets the buffer).
-     */
+    /** Buy a buffer, or only the shortfall when getBalance shows insufficient ETH for the buffer. */
     async sizeSwap(charge, effective, chainId) {
         const shortfall = charge - effective;
-        // Integer math on a 10^6 scale (multiplier ≤ 1000, so ≤ 10^9 — always a
-        // finite, exact integer): keeps the multiplier's precision, no float→BigInt
-        // on an unbounded value.
+        // Bounded fixed-point math preserves precision without converting an unbounded float to BigInt.
         const mScaled = BigInt(Math.round(this._swapBufferMultiplier * SWAP_MULTIPLIER_SCALE));
         const target = (charge * mScaled + BigInt(SWAP_MULTIPLIER_SCALE) - 1n) / BigInt(SWAP_MULTIPLIER_SCALE);
         let amount = target > effective ? target - effective : shortfall;
@@ -3573,7 +3403,7 @@ class OneShot {
                 }
             }
             catch {
-                // Quoting failed — let executeSwap quote again and report properly.
+                // Quoting failed - let executeSwap quote again and report properly.
             }
         }
         return amount;
@@ -3584,7 +3414,7 @@ class OneShot {
         const quote = await getSwapQuote(this.rpcProvider, usdcAmount, chainId, this._slippage);
         return quote?.amountInMax;
     }
-    /** Perform the on-chain swap. */
+    /** Swap on the configured chain using the wallet provider. */
     async executeUsdcSwap(usdcAmount, chainId) {
         const { executeSwap } = await Promise.resolve().then(() => __importStar(require('./swap')));
         return executeSwap(this.provider, this.rpcProvider, usdcAmount, chainId, this._slippage);
@@ -3617,7 +3447,6 @@ class OneShot {
                     ? Buffer.from(header, 'base64').toString()
                     : atob(header);
                 const parsed = JSON.parse(decoded);
-                // x402 v2: { x402Version: 2, accepts: [...], resource: {...}, extensions: {...} }
                 if (parsed.accepts?.length > 0) {
                     return {
                         accepted: parsed.accepts[0],
@@ -3630,7 +3459,6 @@ class OneShot {
                 this.log('Failed to parse PAYMENT-REQUIRED header, using defaults');
             }
         }
-        // Fallback: construct from known production values
         return {
             accepted: {
                 scheme: 'exact',
@@ -3653,14 +3481,13 @@ class OneShot {
         if (header) {
             return this.parsePaymentRequired(header);
         }
-        // Probe: send quote ID without payment to get x402 middleware's 402
         // Carries X-Approval-Id: a policy-held call's probe must reach the 402,
         // not be held again.
         const probeResp = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
         return this.parsePaymentRequired(probeResp.headers.get('payment-required'));
     }
     async signPaymentAuthorization(paymentInfo, accepted, resource, extensions) {
-        // Credits may cover the full cost — send a zero-cost authorization so the server
+        // Credits may cover the full cost - send a zero-cost authorization so the server
         // always receives a payment-signature header (avoids 402 from x402 SDK).
         if (parseFloat(paymentInfo.amount) === 0) {
             this.log('Credits cover full cost — sending zero-cost authorization');
@@ -3682,12 +3509,9 @@ class OneShot {
                     },
                 } };
         }
-        // Belt and braces: every paid path branches to retryAsCreditsSession
-        // before reaching here in access-token mode.
         if (this._accessToken) {
             throw new errors_1.InsufficientCreditsError(`Credits do not cover $${paymentInfo.amount}; top up credits or use a wallet session`, parseFloat(paymentInfo.amount));
         }
-        // If paying with ETH, make sure USDC covers the charge (swapping a buffer if not) and reserve it
         const reservation = await this.ensureUsdcBalance(paymentInfo);
         const now = Math.floor(Date.now() / 1000);
         const nonce = ethers_1.ethers.randomBytes(32);
@@ -3695,14 +3519,10 @@ class OneShot {
         const validAfter = now - 300; // Buffer for clock skew
         const validBefore = now + 3600;
         const nonceHex = ethers_1.ethers.hexlify(nonce);
-        // Use the EIP-712 domain from the server's payment requirements — name,
-        // version AND chain. The chain used to be the mainnet constant, which made
-        // every signature invalid against Base Sepolia (the domain separator
-        // includes chainId), so the SDK could never pay on staging.
+        // Use the server's full EIP-712 domain, including chainId, so the signature matches its network.
         const domainName = accepted.extra?.name || 'USD Coin';
         const domainVersion = accepted.extra?.version || '2';
         const chainId = chainIdFromNetwork(accepted.network ?? paymentInfo.network) ?? CHAIN_ID;
-        // Sign EIP-3009 TransferWithAuthorization
         let signature;
         try {
             signature = await this.provider.signTypedData({
@@ -3732,7 +3552,6 @@ class OneShot {
             this.releaseUsdcReservation(reservation);
             throw err;
         }
-        // Return x402 PaymentPayload v2 format (including resource + extensions for Bazaar discovery)
         return { reservation, auth: {
                 x402Version: 2,
                 ...(resource ? { resource } : {}),