@oneshot-agent/sdk 0.55.0 → 0.56.0

package/dist/index.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.ReadOnlyWalletProvider = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
 const hunts_1 = require("./hunts");
 __exportStar(require("./solve"), exports);
+__exportStar(require("./predict"), exports);
 __exportStar(require("./hunts"), exports);
 const physical_mail_1 = require("./physical-mail");
 __exportStar(require("./physical-mail"), exports);
@@ -66,11 +67,36 @@ const approvals_1 = require("./approvals");
 // stay off this public surface (see tests/unit/sdk-provider-cost-removed.test.ts).
 // Import from the `@oneshot-agent/sdk/receipt` subpath instead.
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.55.0';
+const SDK_VERSION = '0.56.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. */
 const HTTP_POLL_RELAXED_MS = 5000;
+function isTransientComputeReadError(error) {
+    if (error instanceof errors_2.ToolError) {
+        return error.statusCode === 429 || (error.statusCode >= 500 && error.statusCode < 600);
+    }
+    // Fetch network failures differ across browsers, Node and Bun. Do not swallow
+    // arbitrary TypeErrors (bad URLs/configuration), JSON errors or signing errors.
+    if (!(error instanceof Error))
+        return false;
+    const seen = new Set();
+    let current = error;
+    while (current !== null && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        const { code, cause } = current;
+        if ((code !== undefined && [
+            'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'EPIPE', 'ETIMEDOUT',
+            'ENOTFOUND', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH',
+            'ConnectionRefused', 'ConnectionClosed', 'Timeout',
+            'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT',
+        ].includes(code)) || (current instanceof TypeError &&
+            /^(fetch failed|Failed to fetch|Load failed|NetworkError when attempting to fetch resource\.)$/i.test(current.message)))
+            return true;
+        current = cause;
+    }
+    return false;
+}
 const BASE_URL = 'https://win.oneshotagent.com';
 const RPC_URL = 'https://mainnet.base.org';
 const CHAIN_ID = 8453;
@@ -201,7 +227,7 @@ class OneShot {
     constructor(config, walletProvider) {
         this.hunts = new hunts_1.Hunts(this);
         this.physicalMail = new physical_mail_1.PhysicalMail(async (path, method, body, mime) => {
-            const response = await fetch(`${this.baseUrl}/v1/tools/physical-mail${path}`, {
+            const response = await this.fetchApi(`${this.baseUrl}/v1/tools/physical-mail${path}`, {
                 method, headers: { ...await this.signedReadHeaders(method === 'GET' ? 'read' : 'write'), 'Content-Type': mime ?? 'application/json' },
                 ...(body === undefined ? {} : { body: mime ? body : JSON.stringify(body) }),
                 signal: AbortSignal.timeout(60000),
@@ -215,6 +241,7 @@ class OneShot {
         /** Which paid calls run, are denied, or wait for approval. Wallet sessions write it. */
         this.policy = new approvals_1.ActionPolicies((path, method, body, scope) => this.agentJson(path, method, body, scope));
         this.readProofWarned = false;
+        this.proofClockOffsetSec = 0;
         /** ETH mode: signed payments not yet observed as settled, keyed by reservation id. */
         this._usdcPending = new Map();
         this._usdcReservationSeq = 0;
@@ -434,35 +461,35 @@ class OneShot {
     }
     /** List the caller's domain pool with warmup and rotation metadata. */
     async listDomains() {
-        const response = await fetch(`${this.baseUrl}/v1/tools/email/domains`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/email/domains`, {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list domains', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list domains', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
     /** Take a domain out of rotation without releasing it. */
     async pauseDomain(domain) {
         this.validate(domain, 'domain');
-        const response = await fetch(`${this.baseUrl}/v1/tools/email/domains/${encodeURIComponent(domain)}/pause`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/email/domains/${encodeURIComponent(domain)}/pause`, {
             method: 'POST',
             headers: await this.signedReadHeaders('write'),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to pause domain', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to pause domain', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
     /** Put a paused domain back into rotation. */
     async resumeDomain(domain) {
         this.validate(domain, 'domain');
-        const response = await fetch(`${this.baseUrl}/v1/tools/email/domains/${encodeURIComponent(domain)}/resume`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/email/domains/${encodeURIComponent(domain)}/resume`, {
             method: 'POST',
             headers: await this.signedReadHeaders('write'),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to resume domain', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to resume domain', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -470,6 +497,10 @@ class OneShot {
         this.validate(options.topic, 'topic');
         return this.tool('research', { ...options });
     }
+    async predict(input) {
+        const { memo, valueTag, decisionContext, ...options } = input;
+        return this.tool('predict', { ...options, timeout: options.timeout ?? 240 });
+    }
     /**
      * Solve a routing or packing problem with constraint checks and conflicts. Quotes, pays and waits for
      * the job. The result's `solution` is typed by the request's `problem`.
@@ -484,10 +515,15 @@ class OneShot {
         const { includePhone, ...payload } = options;
         return this.tool('find/person', { ...payload, include_phone: includePhone, limit: options.limit ?? 100 });
     }
-    async personProfile(options) {
-        if (!options.linkedin_url && !options.email && !options.name) {
-            throw new errors_2.ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
+    /** At least one identity (#1899): 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) {
+            throw new errors_2.ValidationError('At least one of name, email, phone, or profile_url is required', 'identifier');
         }
+    }
+    async personProfile(options) {
+        this.requirePersonIdentity(options);
         const { includePhone, ...payload } = options;
         return this.tool('lookup/person-profile', { ...payload, include_phone: includePhone });
     }
@@ -547,10 +583,7 @@ class OneShot {
         });
     }
     async personEmail(options) {
-        this.validate(options.company_domain, 'company_domain');
-        if (!options.full_name && !(options.first_name && options.last_name)) {
-            throw new errors_2.ValidationError('Either full_name or both first_name and last_name required', 'name');
-        }
+        this.requirePersonIdentity(options);
         return this.tool('lookup/person-email', { ...options });
     }
     async personEmailStatus(options) {
@@ -558,17 +591,13 @@ class OneShot {
         return this.tool('lookup/person-email-status', { ...options });
     }
     async personDossier(options) {
-        if (!options.email && !options.social_media_url && !options.name) {
-            throw new errors_2.ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
-        }
+        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).
         return this.tool('lookup/person-dossier', { ...payload, include_phone: includePhone, timeout: options.timeout ?? 300 });
     }
     async personSocialAccounts(options) {
-        if (!options.email && !options.social_media_url) {
-            throw new errors_2.ValidationError('At least one of email or social_media_url is required', 'identifier');
-        }
+        this.requirePersonIdentity(options);
         return this.tool('lookup/person-social-accounts', { ...options });
     }
     async personArticles(options) {
@@ -577,17 +606,15 @@ class OneShot {
         return this.tool('lookup/person-articles', { ...options });
     }
     async personPosts(options) {
-        this.validate(options.social_media_url, 'social_media_url');
+        this.requirePersonIdentity(options);
         return this.tool('lookup/person-posts', { ...options });
     }
     async personInterests(options) {
-        if (!options.email && !options.phone && !options.social_media_url) {
-            throw new errors_2.ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
-        }
+        this.requirePersonIdentity(options);
         return this.tool('lookup/person-interests', { ...options });
     }
     async personFollowers(options) {
-        this.validate(options.social_media_url, 'social_media_url');
+        this.requirePersonIdentity(options);
         return this.tool('lookup/person-followers', { ...options });
     }
     async inboxList(options = {}) {
@@ -596,24 +623,24 @@ class OneShot {
             limit: options.limit || undefined,
             include_body: options.include_body ? 'true' : undefined,
         });
-        const response = await fetch(`${this.baseUrl}/v1/tools/inbox${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/inbox${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list inbox', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list inbox', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
     async inboxGet(emailId) {
         this.validate(emailId, 'emailId');
-        const response = await fetch(`${this.baseUrl}/v1/tools/inbox/${emailId}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/inbox/${emailId}`, {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
             throw new errors_2.ToolError('Email not found', 404, 'Email not found');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get email', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get email', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -958,14 +985,14 @@ class OneShot {
         this.validate(name, 'name');
         if (options.cookies !== undefined && options.storage_state !== undefined)
             throw new errors_2.ValidationError('Provide cookies or storage_state, not both', 'options');
-        const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/browser/profiles`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders()) },
             body: JSON.stringify({ name, ...options }),
             signal: AbortSignal.timeout(150000),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to create browser profile', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to create browser profile', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -994,12 +1021,12 @@ class OneShot {
     }
     async browserProfileSetup(profileId, action, body = {}) {
         this.validate(profileId, 'profileId');
-        const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles/${encodeURIComponent(profileId)}/setup/${action}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/browser/profiles/${encodeURIComponent(profileId)}/setup/${action}`, {
             method: 'POST', headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders()) },
             body: JSON.stringify(body), signal: AbortSignal.timeout(150000),
         });
         if (!response.ok)
-            throw new errors_2.ToolError('Browser profile setup failed', response.status, '');
+            throw new errors_2.ToolError('Browser profile setup failed', response.status, '', response.headers.get('retry-after'));
         return response.json();
     }
     /**
@@ -1014,11 +1041,11 @@ class OneShot {
      * ```
      */
     async listBrowserProfiles() {
-        const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/browser/profiles`, {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list browser profiles', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list browser profiles', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const data = await response.json();
         return data.profiles;
@@ -1033,12 +1060,12 @@ class OneShot {
      */
     async deleteBrowserProfile(profileId) {
         this.validate(profileId, 'profileId');
-        const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles/${profileId}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/browser/profiles/${profileId}`, {
             method: 'DELETE',
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to delete browser profile', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to delete browser profile', response.status, await response.text(), response.headers.get('retry-after'));
         }
     }
     async linkedinFree(method, path, opts) {
@@ -1046,7 +1073,7 @@ class OneShot {
         for (const [k, v] of Object.entries(opts.query ?? {}))
             if (v !== undefined)
                 url.searchParams.set(k, v);
-        const response = await fetch(url.toString(), {
+        const response = await this.fetchApi(url.toString(), {
             method,
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders(opts.scope ?? 'read')) },
             ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
@@ -1061,7 +1088,7 @@ class OneShot {
             catch { /* Non-JSON upstream error. */ }
             if (response.status === 409 && code === 'connect_required')
                 throw new errors_1.LinkedInConnectRequiredError(body);
-            throw new errors_2.ToolError(`LinkedIn ${opts.what} failed`, response.status, body);
+            throw new errors_2.ToolError(`LinkedIn ${opts.what} failed`, response.status, body, response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1248,11 +1275,11 @@ class OneShot {
             limit: options.limit || undefined,
             from: options.from || undefined,
         });
-        const response = await fetch(`${this.baseUrl}/v1/tools/sms/inbox${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/sms/inbox${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list SMS inbox', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list SMS inbox', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1394,7 +1421,7 @@ class OneShot {
         const scope = (0, deadline_1.deadlineScope)(toolOptions.signal, filled.startsWith('/v1/tools/browser/profiles') ? 150000 : 30000);
         try {
             const request = (async () => {
-                const response = await fetch(`${this.baseUrl}${target}`, {
+                const response = await this.fetchApi(`${this.baseUrl}${target}`, {
                     method,
                     headers: { ...(sendsBody ? { 'Content-Type': 'application/json' } : {}), ...(await this.signedReadHeaders(method === 'GET' ? 'read' : 'write')) },
                     ...(sendsBody ? { body: JSON.stringify(body ?? {}) } : {}),
@@ -1427,7 +1454,7 @@ class OneShot {
     }
     /** Signed free request returning the `data` field of `{ success, data }`. */
     async signedJson(method, path, body, scope, failure) {
-        const response = await fetch(`${this.baseUrl}${path}`, {
+        const response = await this.fetchApi(`${this.baseUrl}${path}`, {
             method,
             headers: {
                 ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
@@ -1436,7 +1463,7 @@ class OneShot {
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError(failure, response.status, await response.text());
+            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);
@@ -1452,14 +1479,14 @@ class OneShot {
      */
     async smsInboxGet(messageId) {
         this.validate(messageId, 'messageId');
-        const response = await fetch(`${this.baseUrl}/v1/tools/sms/inbox/${messageId}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/sms/inbox/${messageId}`, {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
             throw new errors_2.ToolError('SMS message not found', 404, 'Message not found');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get SMS message', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get SMS message', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1480,11 +1507,11 @@ class OneShot {
             unread: options.unread ? 'true' : undefined,
             limit: options.limit || undefined,
         });
-        const response = await fetch(`${this.baseUrl}/v1/tools/notifications${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/notifications${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list notifications', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list notifications', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1498,7 +1525,7 @@ class OneShot {
      */
     async markNotificationRead(notificationId) {
         this.validate(notificationId, 'notificationId');
-        const response = await fetch(`${this.baseUrl}/v1/tools/notifications/${notificationId}/read`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/notifications/${notificationId}/read`, {
             method: 'PATCH',
             headers: await this.signedReadHeaders('write')
         });
@@ -1506,15 +1533,15 @@ class OneShot {
             throw new errors_2.ToolError('Notification not found', 404, 'Notification not found');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to mark notification as read', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to mark notification as read', response.status, await response.text(), response.headers.get('retry-after'));
         }
     }
     async getUnifiedBalance() {
-        const response = await fetch(`${this.baseUrl}/v1/tools/balance`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/tools/balance`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to fetch balance', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to fetch balance', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1604,20 +1631,89 @@ class OneShot {
      * console.log(status.status, status.budget?.remaining);
      * ```
      */
-    async getComputeGoal(goalId) {
+    async getComputeGoal(goalId, options = {}) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}`, {
-            headers: await this.signedReadHeaders()
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}`, {
+            headers: await this.signedReadHeaders(),
+            signal: options.signal,
         });
         if (response.status === 404) {
             throw new errors_2.ToolError('Goal not found', 404, 'Goal not found');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get compute goal', response.status, await response.text());
+            // Keep the HTTP classification even if the error body is interrupted.
+            const body = await response.text().catch(() => {
+                options.signal?.throwIfAborted();
+                return 'Response body unavailable';
+            });
+            throw new errors_2.ToolError('Failed to get compute goal', response.status, body, response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
     }
+    /**
+     * Poll a compute goal using its goal_id, not its creation request_id.
+     * Returns the complete goal snapshot on completed; failed/cancelled reject
+     * 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
+     * goal ends or the timeout (seconds, default 120) expires with JobTimeoutError.
+     * Infinity disables the local deadline.
+     * onStatusUpdate receives each distinct observed status before settlement.
+     * Callback throws/rejections are ignored and promises are not awaited.
+     * Transient reads (5xx, 429, network failures) retry on the polling cadence.
+     */
+    async waitForComputeGoal(goalId, options = {}) {
+        this.validate(goalId, 'goalId');
+        const started = Date.now();
+        const scope = (0, deadline_1.deadlineScope)(options.signal, (options.timeout ?? 120) * 1000);
+        const poll = async () => {
+            let lastStatus;
+            let polls = 0;
+            while (true) {
+                scope.signal.throwIfAborted();
+                let goal;
+                try {
+                    goal = await this.getComputeGoal(goalId, { signal: scope.signal });
+                }
+                catch (error) {
+                    scope.signal.throwIfAborted();
+                    if (!isTransientComputeReadError(error))
+                        throw error;
+                    await this.sleep(HTTP_POLL_BACKOFF_MS[Math.min(polls++, HTTP_POLL_BACKOFF_MS.length - 1)], scope.signal);
+                    continue;
+                }
+                // A late response from a transport ignoring abort must not emit progress.
+                scope.signal.throwIfAborted();
+                if (goal.status !== lastStatus) {
+                    lastStatus = goal.status;
+                    try {
+                        Promise.resolve(options.onStatusUpdate?.(goal.status, goalId)).catch(() => { });
+                    }
+                    catch { /* Observers cannot change the goal outcome. */ }
+                }
+                if (goal.status === 'completed')
+                    return goal;
+                if (goal.status === 'failed' || goal.status === 'cancelled') {
+                    const reason = goal.end_reason ?? goal.status;
+                    throw new errors_2.JobError(`Compute goal ${goal.status}: ${reason}`, goalId, reason, reason, { ...goal });
+                }
+                await this.sleep(HTTP_POLL_BACKOFF_MS[Math.min(polls++, HTTP_POLL_BACKOFF_MS.length - 1)], scope.signal);
+            }
+        };
+        try {
+            return await (0, deadline_1.abortable)(poll(), scope.signal);
+        }
+        catch (error) {
+            if (scope.timedOut())
+                throw new errors_2.JobTimeoutError(goalId, Date.now() - started);
+            throw error;
+        }
+        finally {
+            scope.close();
+        }
+    }
     /**
      * List tasks under a compute goal
      *
@@ -1631,11 +1727,11 @@ class OneShot {
      */
     async getComputeTasks(goalId) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/tasks`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/tasks`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get compute tasks', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get compute tasks', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1654,11 +1750,11 @@ class OneShot {
      */
     async getComputeOutputs(goalId) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/outputs`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/outputs`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list compute outputs', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list compute outputs', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1669,11 +1765,11 @@ class OneShot {
         this.validate(key, 'key');
         // The key is a path: keep its slashes, escape everything else.
         const path = key.split('/').map(encodeURIComponent).join('/');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/outputs/${path}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/outputs/${path}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to read compute output', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to read compute output', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1689,14 +1785,14 @@ class OneShot {
      */
     async getComputeBudget(goalId) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/budget`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/budget`, {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
             throw new errors_2.ToolError('Budget not found', 404, 'Budget not found for this goal');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get compute budget', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get compute budget', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1712,7 +1808,7 @@ class OneShot {
      */
     async cancelComputeGoal(goalId, reason) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/cancel`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/cancel`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
             body: JSON.stringify({ reason })
@@ -1726,7 +1822,7 @@ class OneShot {
             return { goal_id: goalId, status: pending.status ?? 'pending_settlement', message: pending.message };
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to cancel compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to cancel compute goal', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1746,16 +1842,16 @@ class OneShot {
     async respondToComputeTask(goalId, input) {
         this.validate(goalId, 'goalId');
         this.validate(input.task_id, 'task_id');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/respond`, {
+        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(input)
         });
         if (response.status === 404) {
-            throw new errors_2.ToolError('Goal or task not found', 404, await response.text());
+            throw new errors_2.ToolError('Goal or task not found', 404, await response.text(), response.headers.get('retry-after'));
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to respond to compute task', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to respond to compute task', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1775,15 +1871,15 @@ class OneShot {
      */
     async confirmComputeGoal(goalId, input) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/respond`, {
+        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({ confirm_done: input.approved, ...(input.response ? { response: input.response } : {}) }),
         });
         if (response.status === 404)
-            throw new errors_2.ToolError('Goal not found', 404, await response.text());
+            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 confirm compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to confirm compute goal', response.status, await response.text(), response.headers.get('retry-after'));
         const json = await response.json();
         return json.data;
     }
@@ -1797,13 +1893,13 @@ class OneShot {
      */
     async pauseComputeGoal(goalId, reason) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/pause`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/pause`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
             body: JSON.stringify({ reason })
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to pause compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to pause compute goal', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1819,13 +1915,13 @@ class OneShot {
      */
     async resumeComputeGoal(goalId) {
         this.validate(goalId, 'goalId');
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/resume`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/resume`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
             body: JSON.stringify({})
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to resume compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to resume compute goal', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         return json.data;
@@ -1955,11 +2051,11 @@ class OneShot {
      */
     async spendBreakdown(options) {
         const qs = this.buildQuery({ period: options?.period || undefined });
-        const response = await fetch(`${this.baseUrl}/v1/analytics/spend/breakdown${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/spend/breakdown${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get spend breakdown', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get spend breakdown', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -1974,11 +2070,11 @@ class OneShot {
      */
     async rocs(options) {
         const qs = this.buildQuery({ period: options?.period || undefined });
-        const response = await fetch(`${this.baseUrl}/v1/analytics/rocs${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/rocs${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get RoCS', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get RoCS', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -2010,11 +2106,11 @@ class OneShot {
             since: toIso(options?.since),
             until: toIso(options?.until),
         });
-        const response = await fetch(`${this.baseUrl}/v1/analytics/receipts${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/receipts${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to list receipts', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list receipts', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -2047,19 +2143,19 @@ class OneShot {
         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 fetch(`${this.baseUrl}/v1/analytics/outcomes`, {
+            const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/outcomes`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
                 body: JSON.stringify({ goal_id: ref.goalId, ...valueTag }),
             });
             if (!response.ok) {
-                throw new errors_2.ToolError('Failed to record outcome value', response.status, await response.text());
+                throw new errors_2.ToolError('Failed to record outcome value', response.status, await response.text(), response.headers.get('retry-after'));
             }
             return;
         }
         const id = typeof ref === 'string' ? ref : (ref.receiptId ?? ref.requestId);
         this.validate(id, 'receiptId/requestId/goalId');
-        const response = await fetch(`${this.baseUrl}/v1/analytics/receipts/${id}/value`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/receipts/${id}/value`, {
             method: 'PATCH',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
             body: JSON.stringify(valueTag)
@@ -2068,7 +2164,7 @@ class OneShot {
             throw new errors_2.ToolError('Receipt not found', 404, 'Receipt not found or not owned by this agent');
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to tag receipt value', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to tag receipt value', response.status, await response.text(), response.headers.get('retry-after'));
         }
     }
     /**
@@ -2090,11 +2186,11 @@ class OneShot {
      */
     async rocsByGoal(options) {
         const qs = this.buildQuery({ period: options?.period || undefined, goal_id: options?.goalId || undefined });
-        const response = await fetch(`${this.baseUrl}/v1/analytics/rocs/by-goal${qs ? `?${qs}` : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/analytics/rocs/by-goal${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to get RoCS by goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get RoCS by goal', response.status, await response.text(), response.headers.get('retry-after'));
         }
         return response.json();
     }
@@ -2135,7 +2231,7 @@ class OneShot {
         const headers = await this.signedReadHeaders(`staging:${method}:${path}:${digest}`);
         if (!headers['x-agent-proof'])
             throw new Error('Could not sign staging application');
-        const response = await fetch(`${this.baseUrl}/v1/staging${path}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/staging${path}`, {
             method, headers: { ...headers, 'Content-Type': 'application/json' },
             signal: AbortSignal.timeout(10000),
             ...(body ? { body: JSON.stringify(body) } : {}),
@@ -2170,7 +2266,7 @@ class OneShot {
             return base;
         try {
             const agent = this.provider.address;
-            const issuedAt = Math.floor(Date.now() / 1000);
+            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
@@ -2205,6 +2301,45 @@ 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.
+     */
+    async fetchApi(url, init) {
+        const response = await fetch(url, init);
+        const headers = new Headers(init.headers);
+        const proof = headers.get('x-agent-proof');
+        if (response.status !== 401 || !proof || this._accessToken)
+            return response;
+        const origin = new URL(this.baseUrl).origin;
+        if (new URL(url).origin !== origin || (response.url && new URL(response.url).origin !== origin))
+            return response;
+        let scope;
+        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)
+                return response;
+            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);
+        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 });
+    }
     /** 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. */
     buildQuery(params) {
@@ -2248,7 +2383,7 @@ class OneShot {
                 body.alert_email = this._alertEmail;
             let response;
             try {
-                response = await fetch(`${this.baseUrl}/v1/agents/me/budgets`, {
+                response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/budgets`, {
                     method: 'PUT',
                     headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
                     body: JSON.stringify(body),
@@ -2259,7 +2394,7 @@ class OneShot {
             }
             if (!response.ok) {
                 const text = await response.text();
-                throw new errors_2.BudgetSyncError(`Could not sync spend budget (${response.status}): ${text}`, response.status, text);
+                throw new errors_2.BudgetSyncError(`Could not sync spend budget (${response.status}): ${text}`, response.status, text, response.headers.get('retry-after'));
             }
             this.log('Budget synced');
         })();
@@ -2301,7 +2436,7 @@ class OneShot {
      */
     /** Signed-proof JSON request to a free agent route; returns `data`. Errors map through failFromResponse. */
     async agentJson(path, method, body, scope = 'read') {
-        const response = await fetch(`${this.baseUrl}${path}`, {
+        const response = await this.fetchApi(`${this.baseUrl}${path}`, {
             method,
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders(scope)) },
             ...(body === undefined || method === 'GET' ? {} : { body: JSON.stringify(body) }),
@@ -2313,11 +2448,11 @@ class OneShot {
         return (json && typeof json === 'object' && 'data' in json ? json.data : json);
     }
     async budgets() {
-        const response = await fetch(`${this.baseUrl}/v1/agents/me/budgets`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/budgets`, {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_2.ToolError('Failed to fetch budgets', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to fetch budgets', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const body = await response.json();
         return (body.data ?? body);
@@ -2340,24 +2475,24 @@ class OneShot {
      */
     async createAccessToken(opts = {}) {
         this.assertWalletSession('mint access tokens');
-        const response = await fetch(`${this.baseUrl}/v1/agents/me/access-tokens`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/access-tokens`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
             body: JSON.stringify(opts.name !== undefined ? { name: opts.name } : {}),
         });
         if (!response.ok)
-            throw new errors_2.ToolError('Failed to create access token', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to create access token', response.status, await response.text(), response.headers.get('retry-after'));
         const body = await response.json();
         return body.data;
     }
     /** 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 fetch(`${this.baseUrl}/v1/agents/me/access-tokens${opts.activeOnly ? '?active=true' : ''}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/access-tokens${opts.activeOnly ? '?active=true' : ''}`, {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok)
-            throw new errors_2.ToolError('Failed to list access tokens', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list access tokens', response.status, await response.text(), response.headers.get('retry-after'));
         const body = await response.json();
         return body.data.tokens;
     }
@@ -2365,12 +2500,12 @@ class OneShot {
     async revokeAccessToken(id) {
         this.assertWalletSession('revoke access tokens');
         this.validate(id, 'id');
-        const response = await fetch(`${this.baseUrl}/v1/agents/me/access-tokens/${encodeURIComponent(id)}`, {
+        const response = await this.fetchApi(`${this.baseUrl}/v1/agents/me/access-tokens/${encodeURIComponent(id)}`, {
             method: 'DELETE',
             headers: await this.signedReadHeaders('write'),
         });
         if (!response.ok)
-            throw new errors_2.ToolError('Failed to revoke access token', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to revoke access token', response.status, await response.text(), response.headers.get('retry-after'));
         const body = await response.json();
         return body.data;
     }
@@ -2429,7 +2564,7 @@ class OneShot {
         const budget = response.status === 403 ? this.parseBudgetRejection(text) : undefined;
         if (budget)
             throw budget;
-        throw new errors_2.ToolError(message, response.status, text);
+        throw new errors_2.ToolError(message, response.status, text, response.headers.get('retry-after'));
     }
     /**
      * Map a 402 `insufficient_credits` body (access-token sessions) onto a typed
@@ -2493,12 +2628,12 @@ class OneShot {
             throw new errors_2.ToolError(`Could not resolve the access token's agent (network): ${err}`, 0, String(err));
         }
         if (!response.ok) {
-            throw new errors_2.ToolError('Could not resolve the access token\'s agent', response.status, await response.text());
+            throw new errors_2.ToolError('Could not resolve the access token\'s agent', response.status, await response.text(), response.headers.get('retry-after'));
         }
         const json = await response.json();
         const address = json.data?.wallet_address;
         if (!address)
-            throw new errors_2.ToolError('GET /v1/agents/me returned no wallet_address', response.status, JSON.stringify(json));
+            throw new errors_2.ToolError('GET /v1/agents/me returned no wallet_address', response.status, JSON.stringify(json), response.headers.get('retry-after'));
         return address;
     }
     /**
@@ -2601,7 +2736,7 @@ class OneShot {
                 const headers = signed ? await this.signedReadHeaders() : undefined;
                 if (scope.signal.aborted)
                     throw new errors_2.OneShotError('Read deadline exceeded');
-                const response = await fetch(`${this.baseUrl}${path}`, { headers, signal: scope.signal });
+                const response = await this.fetchApi(`${this.baseUrl}${path}`, { headers, signal: scope.signal });
                 if (!response.ok && !(allowDegraded && response.status === 503))
                     await this.failFromResponse('Reliability read failed', response);
                 return await response.json();
@@ -2620,7 +2755,7 @@ class OneShot {
     }
     async executeToolRequest(endpoint, options, quoteId) {
         // LinkedIn writes act through a human's account and cannot be recalled: always keyed.
-        const reliable = /(?:^|\/)(lookup\/person-(profile|email|email-status)|lookup\/place-permits|solve|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint);
+        const reliable = /(?:^|\/)(lookup\/person-(profile|email|email-status)|lookup\/place-permits|solve|predict|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint);
         const key = options.idempotencyKey ?? (reliable ? ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(16)) : undefined);
         if (options.totalTimeoutMs !== undefined && (!Number.isFinite(options.totalTimeoutMs) || options.totalTimeoutMs <= 0)) {
             throw new errors_2.ValidationError('totalTimeoutMs must be positive', 'totalTimeoutMs');
@@ -2663,7 +2798,7 @@ class OneShot {
                 this.log('Memo truncated to 1000 chars');
             }
         }
-        else if (!endpoint.endsWith('/v1/tools/solve') && !endpoint.includes('/inbox') && !endpoint.includes('/notifications') && !endpoint.includes('/balance')) {
+        else if (!endpoint.endsWith('/v1/tools/solve') && !endpoint.endsWith('/v1/tools/predict') && !endpoint.includes('/inbox') && !endpoint.includes('/notifications') && !endpoint.includes('/balance')) {
             this.log('No memo provided — consider adding a reason for audit trail');
         }
         if (payload.decisionContext !== undefined) {
@@ -2692,7 +2827,7 @@ class OneShot {
         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|find\/person|lookup\/person-(profile|dossier))$/.test(endpoint)) {
+        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,
                 expectMsg: 'Expected a tool quote', totalOf: quote => quote.total,
@@ -2813,6 +2948,15 @@ class OneShot {
      * `wait: false`, or to resume waiting after a client restart. Delivery is the
      * same as for blocking calls: WebSocket push when the server offers it, HTTP
      * polling of `GET /v1/requests/:id` as the source of truth.
+     * For compute goals, use `waitForComputeGoal(goal_id)` instead: their creation
+     * request_id does not track progress. `onStatusUpdate` observes distinct job
+     * statuses, including the terminal status before settlement.
+     * With waitForPhones, completed is deferred until the phone wait returns.
+     * Callback errors are ignored; returned promises are not awaited.
+     *
+     * `signal` ends the local wait only (in-flight fetch aborted, poll timer
+     * cleared, rejects with `OneShotError('Operation cancelled')`); the job
+     * itself keeps running and can be waited for again.
      */
     async waitForResult(requestId, options = {}) {
         this.validate(requestId, 'requestId');
@@ -2825,6 +2969,9 @@ class OneShot {
         // 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.
+        if (signal?.aborted)
+            throw new errors_2.OneShotError('Operation cancelled');
         const inner = new AbortController();
         const onOuterAbort = () => inner.abort();
         if (signal?.aborted)
@@ -2832,12 +2979,24 @@ class OneShot {
         else
             signal?.addEventListener('abort', onOuterAbort, { once: true });
         const wait = { pushConfirmed: false, lastStatus: undefined, via: undefined };
-        // Two sources now report status; only surface changes to the caller.
+        const notify = (status) => {
+            // Progress observers must not alter job outcomes or trigger HTTP retries.
+            try {
+                Promise.resolve(onStatusUpdate?.(status, requestId)).catch(() => { });
+            }
+            catch { /* Ignore synchronous observer errors too. */ }
+        };
+        // Latch terminal transport status immediately, but defer completion for
+        // callers waiting on phones so the losing branch cannot emit stale states.
         const emit = (status) => {
+            if (wait.lastStatus === 'completed' || wait.lastStatus === 'failed')
+                return;
             if (status === wait.lastStatus)
                 return;
             wait.lastStatus = status;
-            onStatusUpdate?.(status, requestId);
+            if (status === 'completed' && phoneOpts?.waitForPhones)
+                return;
+            notify(status);
         };
         const startedAt = Date.now();
         const wsBranch = this.waitViaWebSocket(requestId, inner.signal, emit, wait).catch((err) => {
@@ -2873,8 +3032,10 @@ class OneShot {
         // hit a transient error before any successful refresh, we return what we
         // already have (with phones_pending=true still set so consumers know).
         if (phoneOpts?.waitForPhones && this._isPhonesPending(result)) {
-            return this._pollForPhones(requestId, phoneOpts.phoneTimeoutSec ?? 360, signal, result);
+            result = await this._pollForPhones(requestId, phoneOpts.phoneTimeoutSec ?? 360, signal, result);
         }
+        if (phoneOpts?.waitForPhones)
+            notify('completed');
         return result;
     }
     /**
@@ -2918,7 +3079,7 @@ class OneShot {
             if (signal?.aborted)
                 throw new errors_2.OneShotError('Operation cancelled');
             try {
-                const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
+                const resp = await this.fetchApi(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: await this.signedReadHeaders(),
                     signal,
                 });
@@ -2927,7 +3088,7 @@ class OneShot {
                     // whatever we last had so consumers don't lose the sync result.
                     if (lastResult !== undefined)
                         return lastResult;
-                    throw new errors_2.ToolError('Failed to check job status', resp.status, await resp.text());
+                    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);
@@ -2936,6 +3097,8 @@ class OneShot {
                 }
             }
             catch (err) {
+                if (signal?.aborted)
+                    throw new errors_2.OneShotError('Operation cancelled');
                 if (err instanceof errors_2.OneShotError)
                     throw err;
                 if (lastResult !== undefined)
@@ -3031,6 +3194,7 @@ class OneShot {
                         wait.pushConfirmed = true;
                         this.log('WebSocket push confirmed — relaxing HTTP polling');
                     }
+                    emit(String(msg.status));
                     if (msg.status === 'completed') {
                         this.log('Job completed (WebSocket)');
                         settle(() => {
@@ -3050,9 +3214,6 @@ class OneShot {
                             reject(new errors_2.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code, msg.result));
                         });
                     }
-                    else {
-                        emit(String(msg.status));
-                    }
                 }
                 catch {
                     // Ignore malformed messages
@@ -3088,6 +3249,9 @@ class OneShot {
         catch (error) {
             if (scope.timedOut())
                 throw new errors_2.JobTimeoutError(requestId, Date.now() - started);
+            // An abort mid-fetch surfaces as the transport's AbortError; report it as the cancellation it is.
+            if (signal?.aborted && !(error instanceof errors_2.OneShotError))
+                throw new errors_2.OneShotError('Operation cancelled');
             throw error;
         }
         finally {
@@ -3104,7 +3268,7 @@ class OneShot {
             if (signal?.aborted)
                 throw new errors_2.OneShotError('Operation cancelled');
             try {
-                const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
+                const resp = await this.fetchApi(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: await this.signedReadHeaders(),
                     signal
                 });
@@ -3115,9 +3279,10 @@ class OneShot {
                     if (resp.status >= 500 || resp.status === 429) {
                         throw new Error(`Poll returned ${resp.status}: ${body.slice(0, 200)}`);
                     }
-                    throw new errors_2.ToolError('Failed to check job status', resp.status, body);
+                    throw new errors_2.ToolError('Failed to check job status', resp.status, body, resp.headers.get('retry-after'));
                 }
                 const job = await resp.json();
+                emit?.(String(job.status));
                 if (job.status === 'completed') {
                     this.log('Job completed');
                     if (wait)
@@ -3140,7 +3305,6 @@ class OneShot {
                         wait.via = 'http';
                     throw new errors_2.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code, job.result);
                 }
-                emit?.(String(job.status));
                 retries = 0;
                 const interval = wait?.pushConfirmed
                     ? HTTP_POLL_RELAXED_MS
@@ -3223,7 +3387,7 @@ class OneShot {
         // alone (401 proof_required).
         const unsignedStub = payment?.payload?.signature === '0x';
         const askedForProof = !!extraHeaders?.['x-agent-proof'];
-        const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|solve)$/.test(endpoint)
+        const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|solve|predict)$/.test(endpoint)
             ? 'submit'
             : askedForProof ? 'read' : 'write';
         const headers = {
@@ -3251,7 +3415,7 @@ class OneShot {
         transportDeadline?.signal.addEventListener('abort', () => transportDeadline.close(), { once: true });
         if (fetchSignal?.aborted)
             throw new errors_2.OneShotError('Operation cancelled');
-        const work = fetch(`${this.baseUrl}${endpoint}`, {
+        const work = this.fetchApi(`${this.baseUrl}${endpoint}`, {
             method: 'POST', headers, body: JSON.stringify(data), signal: fetchSignal,
         });
         try {
@@ -3408,7 +3572,7 @@ class OneShot {
         }
         catch (err) {
             // Keyed writes may already be queued server-side after a transport failure: keep the reservation.
-            if (!/(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|solve|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
+            if (!/(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|solve|predict|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
                 this.releaseUsdcReservation(signed.reservation);
             throw err;
         }