@oneshot-agent/sdk 0.16.2 → 0.18.0

package/dist/index.js

@@ -15,6 +15,9 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importStar = (this && this.__importStar) || (function () {
     var ownKeys = function(o) {
         ownKeys = Object.getOwnPropertyNames || function (o) {
@@ -33,9 +36,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OneShot = exports.EmergencyNumberError = exports.ContentBlockedError = exports.ValidationError = exports.JobTimeoutError = exports.JobError = exports.ToolError = exports.OneShotError = exports.executeSwap = exports.getSwapQuote = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
+exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
 const ethers_1 = require("ethers");
 const ethers_2 = require("./providers/ethers");
+const errors_1 = require("./errors");
 var ethers_3 = require("./providers/ethers");
 Object.defineProperty(exports, "EthersWalletProvider", { enumerable: true, get: function () { return ethers_3.EthersWalletProvider; } });
 var cdp_1 = require("./providers/cdp");
@@ -43,7 +47,8 @@ Object.defineProperty(exports, "CdpWalletProvider", { enumerable: true, get: fun
 var swap_1 = require("./swap");
 Object.defineProperty(exports, "getSwapQuote", { enumerable: true, get: function () { return swap_1.getSwapQuote; } });
 Object.defineProperty(exports, "executeSwap", { enumerable: true, get: function () { return swap_1.executeSwap; } });
-const SDK_VERSION = '0.13.1';
+__exportStar(require("./errors"), exports);
+const SDK_VERSION = '0.16.2';
 // ============================================================================
 // Environment Configuration
 // ============================================================================
@@ -52,67 +57,12 @@ const RPC_URL = 'https://mainnet.base.org';
 const CHAIN_ID = 8453;
 const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
 // ============================================================================
-// Error Classes
+// Public types — defined in ./types.ts. Re-exported below so existing
+// consumer imports (`import { EmailToolOptions, ... } from '@oneshot-agent/sdk'`)
+// keep resolving unchanged. The OneShot class below pulls the names it needs
+// for internal use via the import block.
 // ============================================================================
-class OneShotError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'OneShotError';
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-exports.OneShotError = OneShotError;
-class ToolError extends OneShotError {
-    constructor(message, statusCode, responseBody) {
-        super(message);
-        this.statusCode = statusCode;
-        this.responseBody = responseBody;
-        this.name = 'ToolError';
-    }
-}
-exports.ToolError = ToolError;
-class JobError extends OneShotError {
-    constructor(message, jobId, jobError) {
-        super(message);
-        this.jobId = jobId;
-        this.jobError = jobError;
-        this.name = 'JobError';
-    }
-}
-exports.JobError = JobError;
-class JobTimeoutError extends OneShotError {
-    constructor(jobId, elapsedMs) {
-        super(`Job ${jobId} timed out after ${elapsedMs / 1000}s`);
-        this.jobId = jobId;
-        this.elapsedMs = elapsedMs;
-        this.name = 'JobTimeoutError';
-    }
-}
-exports.JobTimeoutError = JobTimeoutError;
-class ValidationError extends OneShotError {
-    constructor(message, field) {
-        super(message);
-        this.field = field;
-        this.name = 'ValidationError';
-    }
-}
-exports.ValidationError = ValidationError;
-class ContentBlockedError extends OneShotError {
-    constructor(message, categories) {
-        super(message);
-        this.categories = categories;
-        this.name = 'ContentBlockedError';
-    }
-}
-exports.ContentBlockedError = ContentBlockedError;
-class EmergencyNumberError extends OneShotError {
-    constructor(message, blockedNumber) {
-        super(message);
-        this.blockedNumber = blockedNumber;
-        this.name = 'EmergencyNumberError';
-    }
-}
-exports.EmergencyNumberError = EmergencyNumberError;
+__exportStar(require("./types"), exports);
 // ============================================================================
 // OneShot SDK
 // ============================================================================
@@ -154,7 +104,7 @@ class OneShot {
             const walletProvider = new ethers_2.EthersWalletProvider(config.privateKey, rpcProvider);
             return new OneShot(config, walletProvider);
         }
-        throw new ValidationError('Provide one of: privateKey, cdp, or walletProvider', 'config');
+        throw new errors_1.ValidationError('Provide one of: privateKey, cdp, or walletProvider', 'config');
     }
     /**
      * Sync constructor — works with privateKey (backwards compatible).
@@ -174,11 +124,11 @@ class OneShot {
             this.provider = new ethers_2.EthersWalletProvider(config.privateKey, this.rpcProvider);
         }
         else {
-            throw new ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
+            throw new errors_1.ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
         }
         // Validate ETH mode requirements
         if (this._currency === 'ETH' && !this.provider.sendTransaction) {
-            throw new ValidationError('ETH currency mode requires a wallet provider that supports sendTransaction', 'currency');
+            throw new errors_1.ValidationError('ETH currency mode requires a wallet provider that supports sendTransaction', 'currency');
         }
         if (this.debug) {
             this.log(`SDK initialized — chain=${CHAIN_ID} currency=${this._currency}`);
@@ -212,16 +162,41 @@ class OneShot {
         this.validate(options.to, 'to');
         this.validate(options.subject, 'subject');
         this.validate(options.body, 'body');
-        const fromAddress = `${options.from_mailbox ?? 'agent'}@${options.from_domain ?? 'oneshotagent.com'}`;
+        // 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 either knob, we keep legacy behavior: build
+        // `${mailbox ?? 'agent'}@${domain ?? 'oneshotagent.com'}`.
+        const useRotation = !options.from_domain && !options.from_mailbox;
+        const fromAddress = useRotation
+            ? undefined
+            : `${options.from_mailbox ?? 'agent'}@${options.from_domain ?? 'oneshotagent.com'}`;
         const quote = await this.tool('email/quote', {
-            from_address: fromAddress,
+            ...(fromAddress ? { from_address: fromAddress } : {}),
             to_address: options.to,
             subject: options.subject,
-            body: options.body
+            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).
+        if (options.maxCost && parseFloat(quote.total_cost) > options.maxCost) {
+            throw new errors_1.OneShotError(`Quote $${quote.total_cost} exceeds maxCost $${options.maxCost}`);
+        }
+        const resolvedFromAddress = fromAddress ?? quote.from_address;
         const payload = {
-            from_address: fromAddress,
+            // 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 } : {}),
             to_address: options.to,
             subject: options.subject,
             body: options.body,
@@ -237,6 +212,40 @@ class OneShot {
         }
         return this.executeToolRequest('/v1/tools/email/send', payload, quote.quote_id);
     }
+    /** List the caller's domain pool with warmup and rotation metadata. */
+    async listDomains() {
+        const response = await fetch(`${this.baseUrl}/v1/tools/email/domains`, {
+            headers: this.headers(),
+        });
+        if (!response.ok) {
+            throw new errors_1.ToolError('Failed to list domains', response.status, await response.text());
+        }
+        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`, {
+            method: 'POST',
+            headers: this.headers(),
+        });
+        if (!response.ok) {
+            throw new errors_1.ToolError('Failed to pause domain', response.status, await response.text());
+        }
+        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`, {
+            method: 'POST',
+            headers: this.headers(),
+        });
+        if (!response.ok) {
+            throw new errors_1.ToolError('Failed to resume domain', response.status, await response.text());
+        }
+        return response.json();
+    }
     async research(options) {
         this.validate(options.topic, 'topic');
         return this.tool('research', { ...options });
@@ -246,14 +255,14 @@ class OneShot {
     }
     async enrichProfile(options) {
         if (!options.linkedin_url && !options.email && !options.name) {
-            throw new ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
+            throw new errors_1.ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
         }
         return this.tool('enrich/profile', { ...options });
     }
     async findEmail(options) {
         this.validate(options.company_domain, 'company_domain');
         if (!options.full_name && !(options.first_name && options.last_name)) {
-            throw new ValidationError('Either full_name or both first_name and last_name required', 'name');
+            throw new errors_1.ValidationError('Either full_name or both first_name and last_name required', 'name');
         }
         return this.tool('enrich/email', { ...options });
     }
@@ -263,13 +272,13 @@ class OneShot {
     }
     async deepResearchPerson(options) {
         if (!options.email && !options.social_media_url && !options.name) {
-            throw new ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
+            throw new errors_1.ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
         }
         return this.tool('research/person', { ...options });
     }
     async socialProfiles(options) {
         if (!options.email && !options.social_media_url) {
-            throw new ValidationError('At least one of email or social_media_url is required', 'identifier');
+            throw new errors_1.ValidationError('At least one of email or social_media_url is required', 'identifier');
         }
         return this.tool('research/social', { ...options });
     }
@@ -284,7 +293,7 @@ class OneShot {
     }
     async personInterests(options) {
         if (!options.email && !options.phone && !options.social_media_url) {
-            throw new ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
+            throw new errors_1.ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
         }
         return this.tool('research/interests', { ...options });
     }
@@ -305,7 +314,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to list inbox', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to list inbox', response.status, await response.text());
         }
         return response.json();
     }
@@ -315,10 +324,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new ToolError('Email not found', 404, 'Email not found');
+            throw new errors_1.ToolError('Email not found', 404, 'Email not found');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to get email', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get email', response.status, await response.text());
         }
         return response.json();
     }
@@ -333,14 +342,14 @@ class OneShot {
             variant_id: options.variant_id
         };
         // Commerce quotes can take up to 90s due to Rye API polling
-        const quoteResp = await this.makeRequest('/v1/tools/commerce/buy', payload, undefined, undefined, options.signal, 120000);
+        const quoteResp = await this.makeRequest('/v1/tools/commerce/buy', payload, undefined, undefined, options.signal, 120000, this.maxCostHeader(options.maxCost));
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`Commerce quote: $${quoteData.context.total} for "${quoteData.context.product_title}"`);
         if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -356,7 +365,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const buyResp = await this.makeRequest('/v1/tools/commerce/buy', payload, auth, quoteData.context.quote_id, options.signal, 60000);
         if (buyResp.status !== 202) {
-            throw new ToolError('Commerce buy failed', buyResp.status, await buyResp.text());
+            throw new errors_1.ToolError('Commerce buy failed', buyResp.status, await buyResp.text());
         }
         const result = await buyResp.json();
         this.log(`Order submitted: ${result.request_id}`);
@@ -395,13 +404,13 @@ class OneShot {
         this.validate(options.target_number, 'target_number');
         // Check for empty arrays
         if (Array.isArray(options.target_number) && options.target_number.length === 0) {
-            throw new ValidationError('target_number array cannot be empty', 'target_number');
+            throw new errors_1.ValidationError('target_number array cannot be empty', 'target_number');
         }
         if (options.objective.length < 10) {
-            throw new ValidationError('Objective must be at least 10 characters', 'objective');
+            throw new errors_1.ValidationError('Objective must be at least 10 characters', 'objective');
         }
         if (options.max_duration_minutes !== undefined && (options.max_duration_minutes < 1 || options.max_duration_minutes > 30)) {
-            throw new ValidationError('max_duration_minutes must be between 1 and 30', 'max_duration_minutes');
+            throw new errors_1.ValidationError('max_duration_minutes must be between 1 and 30', 'max_duration_minutes');
         }
         const payload = {
             objective: options.objective,
@@ -417,26 +426,25 @@ class OneShot {
         if (options.max_duration_minutes)
             payload.max_duration_minutes = options.max_duration_minutes;
         // Voice uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/voice/call', payload, undefined, undefined, options.signal);
+        const quoteResp = await this.makeRequest('/v1/tools/voice/call', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
         // Handle error responses before expecting 402
         if (quoteResp.status === 400) {
             const errorData = await quoteResp.json();
             if (errorData.error === 'content_blocked') {
-                throw new ContentBlockedError(errorData.message, errorData.categories || []);
+                throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
             }
             if (errorData.error === 'emergency_number_blocked') {
-                throw new EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
             }
-            throw new ValidationError(errorData.message || 'Invalid request', 'request');
+            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
         }
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`Voice quote: $${quoteData.context.total} for ${quoteData.context.estimated_duration_minutes}min call`);
-        this.log(`Objective summary: ${quoteData.context.objective_summary}`);
         if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -452,7 +460,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const callResp = await this.makeRequest('/v1/tools/voice/call', payload, auth, quoteData.context.quote_id, options.signal);
         if (callResp.status !== 202) {
-            throw new ToolError('Voice call initiation failed', callResp.status, await callResp.text());
+            throw new errors_1.ToolError('Voice call initiation failed', callResp.status, await callResp.text());
         }
         const result = await callResp.json();
         this.log(`Call initiated: ${result.request_id}`);
@@ -478,17 +486,17 @@ class OneShot {
         this.validate(options.to_number, 'to_number');
         // Check for empty arrays
         if (Array.isArray(options.to_number) && options.to_number.length === 0) {
-            throw new ValidationError('to_number array cannot be empty', 'to_number');
+            throw new errors_1.ValidationError('to_number array cannot be empty', 'to_number');
         }
         if (options.message.length < 1) {
-            throw new ValidationError('Message is required', 'message');
+            throw new errors_1.ValidationError('Message is required', 'message');
         }
         if (options.message.length > 1600) {
-            throw new ValidationError('Message must be 1600 characters or less', 'message');
+            throw new errors_1.ValidationError('Message must be 1600 characters or less', 'message');
         }
         const recipientCount = Array.isArray(options.to_number) ? options.to_number.length : 1;
         if (recipientCount > 10) {
-            throw new ValidationError('Maximum 10 recipients allowed', 'to_number');
+            throw new errors_1.ValidationError('Maximum 10 recipients allowed', 'to_number');
         }
         const payload = {
             message: options.message,
@@ -498,25 +506,25 @@ class OneShot {
             wait: options.wait
         };
         // SMS uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/sms/send', payload, undefined, undefined, options.signal);
+        const quoteResp = await this.makeRequest('/v1/tools/sms/send', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
         // Handle error responses before expecting 402
         if (quoteResp.status === 400) {
             const errorData = await quoteResp.json();
             if (errorData.error === 'content_blocked') {
-                throw new ContentBlockedError(errorData.message, errorData.categories || []);
+                throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
             }
             if (errorData.error === 'emergency_number_blocked') {
-                throw new EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
             }
-            throw new ValidationError(errorData.message || 'Invalid request', 'request');
+            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
         }
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`SMS quote: $${quoteData.context.total} for ${quoteData.context.segment_count} segment(s) to ${recipientCount} recipient(s)`);
         if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -532,7 +540,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const sendResp = await this.makeRequest('/v1/tools/sms/send', payload, auth, quoteData.context.quote_id, options.signal);
         if (sendResp.status !== 202) {
-            throw new ToolError('SMS send failed', sendResp.status, await sendResp.text());
+            throw new errors_1.ToolError('SMS send failed', sendResp.status, await sendResp.text());
         }
         const result = await sendResp.json();
         this.log(`SMS queued: ${result.request_id}`);
@@ -562,7 +570,7 @@ class OneShot {
         this.validate(options.product?.name, 'product.name');
         this.validate(options.product?.description, 'product.description');
         if (options.product.description.length < 10) {
-            throw new ValidationError('Product description must be at least 10 characters', 'product.description');
+            throw new errors_1.ValidationError('Product description must be at least 10 characters', 'product.description');
         }
         const payload = {
             type: options.type ?? 'saas',
@@ -586,19 +594,19 @@ class OneShot {
         if (options.build_id)
             payload.build_id = options.build_id;
         // Build uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/build', payload, undefined, undefined, options.signal);
+        const quoteResp = await this.makeRequest('/v1/tools/build', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
         if (quoteResp.status === 400) {
             const errorData = await quoteResp.json();
-            throw new ValidationError(errorData.message || 'Invalid request', 'request');
+            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
         }
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`Build quote: $${quoteData.context.pricing.total} for "${quoteData.context.product_name}"`);
         this.log(`Type: ${quoteData.context.analysis.inferred_type}, Sections: ${quoteData.context.analysis.estimated_sections}`);
         if (options.maxCost && parseFloat(quoteData.context.pricing.total) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.pricing.total} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.pricing.total} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -614,7 +622,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const buildResp = await this.makeRequest('/v1/tools/build', payload, auth, quoteData.context.quote_id, options.signal);
         if (buildResp.status !== 202) {
-            throw new ToolError('Build initiation failed', buildResp.status, await buildResp.text());
+            throw new errors_1.ToolError('Build initiation failed', buildResp.status, await buildResp.text());
         }
         const result = await buildResp.json();
         this.log(`Build initiated: ${result.request_id}`);
@@ -638,10 +646,10 @@ class OneShot {
     async browser(options) {
         this.validate(options.task, 'task');
         if (options.task.length < 10) {
-            throw new ValidationError('Task must be at least 10 characters', 'task');
+            throw new errors_1.ValidationError('Task must be at least 10 characters', 'task');
         }
         if (options.max_steps !== undefined && (options.max_steps < 1 || options.max_steps > 100)) {
-            throw new ValidationError('max_steps must be between 1 and 100', 'max_steps');
+            throw new errors_1.ValidationError('max_steps must be between 1 and 100', 'max_steps');
         }
         const payload = {
             task: options.task,
@@ -664,18 +672,18 @@ class OneShot {
         if (options.max_steps)
             payload.max_steps = options.max_steps;
         // Browser uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/browser', payload, undefined, undefined, options.signal);
+        const quoteResp = await this.makeRequest('/v1/tools/browser', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
         if (quoteResp.status === 400) {
             const errorData = await quoteResp.json();
-            throw new ValidationError(errorData.message || 'Invalid request', 'request');
+            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
         }
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`Browser quote: $${quoteData.context.estimated_cost} for ~${quoteData.context.estimated_steps} steps`);
         if (options.maxCost && parseFloat(quoteData.context.estimated_cost) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.estimated_cost} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.estimated_cost} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -691,7 +699,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const execResp = await this.makeRequest('/v1/tools/browser', payload, auth, quoteData.context.quote_id, options.signal);
         if (execResp.status !== 202) {
-            throw new ToolError('Browser task initiation failed', execResp.status, await execResp.text());
+            throw new errors_1.ToolError('Browser task initiation failed', execResp.status, await execResp.text());
         }
         const result = await execResp.json();
         this.log(`Browser task initiated: ${result.request_id}`);
@@ -717,7 +725,7 @@ class OneShot {
             body: JSON.stringify({ name }),
         });
         if (!response.ok) {
-            throw new ToolError('Failed to create browser profile', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to create browser profile', response.status, await response.text());
         }
         return response.json();
     }
@@ -737,7 +745,7 @@ class OneShot {
             headers: this.headers(),
         });
         if (!response.ok) {
-            throw new ToolError('Failed to list browser profiles', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to list browser profiles', response.status, await response.text());
         }
         const data = await response.json();
         return data.profiles;
@@ -757,7 +765,7 @@ class OneShot {
             headers: this.headers(),
         });
         if (!response.ok) {
-            throw new ToolError('Failed to delete browser profile', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to delete browser profile', response.status, await response.text());
         }
     }
     /**
@@ -806,7 +814,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to list SMS inbox', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to list SMS inbox', response.status, await response.text());
         }
         return response.json();
     }
@@ -825,10 +833,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new ToolError('SMS message not found', 404, 'Message not found');
+            throw new errors_1.ToolError('SMS message not found', 404, 'Message not found');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to get SMS message', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get SMS message', response.status, await response.text());
         }
         return response.json();
     }
@@ -855,7 +863,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to list notifications', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to list notifications', response.status, await response.text());
         }
         return response.json();
     }
@@ -874,10 +882,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new ToolError('Notification not found', 404, 'Notification not found');
+            throw new errors_1.ToolError('Notification not found', 404, 'Notification not found');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to mark notification as read', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to mark notification as read', response.status, await response.text());
         }
     }
     async getUnifiedBalance() {
@@ -885,7 +893,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to fetch balance', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to fetch balance', response.status, await response.text());
         }
         return response.json();
     }
@@ -943,21 +951,21 @@ class OneShot {
         if (options.schedule)
             payload.schedule = options.schedule;
         // First call: get quote (402)
-        const quoteResp = await this.makeRequest('/v1/compute', payload, undefined, undefined, options.signal);
+        const quoteResp = await this.makeRequest('/v1/compute', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
         if (quoteResp.status === 400) {
             const errorData = await quoteResp.json();
             if (errorData.error === 'content_blocked') {
-                throw new ContentBlockedError(errorData.message, []);
+                throw new errors_1.ContentBlockedError(errorData.message, []);
             }
-            throw new ValidationError(errorData.message || 'Invalid request', 'request');
+            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
         }
         if (quoteResp.status !== 402) {
-            throw new ToolError('Expected 402 for compute quote', quoteResp.status, await quoteResp.text());
+            throw new errors_1.ToolError('Expected 402 for compute quote', quoteResp.status, await quoteResp.text());
         }
         const quoteData = await quoteResp.json();
         this.log(`Compute quote: $${quoteData.context.total_budget} — ${quoteData.context.objective_summary}`);
         if (options.maxCost && parseFloat(quoteData.context.total_budget) > options.maxCost) {
-            throw new OneShotError(`Quote $${quoteData.context.total_budget} exceeds maxCost $${options.maxCost}`);
+            throw new errors_1.OneShotError(`Quote $${quoteData.context.total_budget} exceeds maxCost $${options.maxCost}`);
         }
         const paymentInfo = {
             protocol: 'x402',
@@ -973,7 +981,7 @@ class OneShot {
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const createResp = await this.makeRequest('/v1/compute', payload, auth, quoteData.context.quote_id, options.signal);
         if (createResp.status !== 202) {
-            throw new ToolError('Compute goal creation failed', createResp.status, await createResp.text());
+            throw new errors_1.ToolError('Compute goal creation failed', createResp.status, await createResp.text());
         }
         return createResp.json();
     }
@@ -992,10 +1000,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new ToolError('Goal not found', 404, 'Goal not found');
+            throw new errors_1.ToolError('Goal not found', 404, 'Goal not found');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to get compute goal', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1017,7 +1025,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to get compute tasks', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get compute tasks', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1037,10 +1045,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new ToolError('Budget not found', 404, 'Budget not found for this goal');
+            throw new errors_1.ToolError('Budget not found', 404, 'Budget not found for this goal');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to get compute budget', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get compute budget', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1062,10 +1070,10 @@ class OneShot {
             body: JSON.stringify({ reason })
         });
         if (response.status === 404) {
-            throw new ToolError('Goal not found', 404, 'Goal not found');
+            throw new errors_1.ToolError('Goal not found', 404, 'Goal not found');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to cancel compute goal', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to cancel compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1091,10 +1099,10 @@ class OneShot {
             body: JSON.stringify(input)
         });
         if (response.status === 404) {
-            throw new ToolError('Goal or task not found', 404, await response.text());
+            throw new errors_1.ToolError('Goal or task not found', 404, await response.text());
         }
         if (!response.ok) {
-            throw new ToolError('Failed to respond to compute task', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to respond to compute task', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1115,7 +1123,7 @@ class OneShot {
             body: JSON.stringify({ reason })
         });
         if (!response.ok) {
-            throw new ToolError('Failed to pause compute goal', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to pause compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1137,13 +1145,16 @@ class OneShot {
             body: JSON.stringify({})
         });
         if (!response.ok) {
-            throw new ToolError('Failed to resume compute goal', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to resume compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
     }
     /**
-     * Top up budget for a recurring compute goal
+     * Top up budget for a recurring compute goal.
+     *
+     * Uses the quote-then-pay flow: the first call gets a 402 with the top-up price,
+     * the second call (with payment) credits the budget. The amount IS the price.
      *
      * @example
      * ```typescript
@@ -1154,17 +1165,33 @@ class OneShot {
     async fundComputeGoal(goalId, amount) {
         this.validate(goalId, 'goalId');
         if (!amount || amount <= 0) {
-            throw new ValidationError('amount must be a positive number', 'amount');
+            throw new errors_1.ValidationError('amount must be a positive number', 'amount');
         }
-        const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/fund`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
-            body: JSON.stringify({ amount })
-        });
-        if (!response.ok) {
-            throw new ToolError('Failed to fund compute goal', response.status, await response.text());
+        const path = `/v1/compute/${goalId}/fund`;
+        const payload = { amount };
+        // First call: get quote (402)
+        const quoteResp = await this.makeRequest(path, payload);
+        if (quoteResp.status !== 402) {
+            throw new errors_1.ToolError('Expected 402 for compute fund quote', quoteResp.status, await quoteResp.text());
         }
-        const json = await response.json();
+        const quoteData = await quoteResp.json();
+        this.log(`Compute fund quote: $${quoteData.payment_request.amount} to top up ${goalId}`);
+        const paymentInfo = {
+            protocol: 'x402',
+            network: `eip155:${quoteData.payment_request.chain_id}`,
+            payTo: quoteData.payment_request.recipient,
+            amount: quoteData.payment_request.amount,
+            currency: 'USD',
+            facilitator_url: this.baseUrl,
+            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
+        };
+        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, path, payload, quoteData.context.quote_id);
+        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+        const fundResp = await this.makeRequest(path, payload, auth, quoteData.context.quote_id);
+        if (!fundResp.ok) {
+            throw new errors_1.ToolError('Failed to fund compute goal', fundResp.status, await fundResp.text());
+        }
+        const json = await fundResp.json();
         return json.data;
     }
     // ---------------------------------------------------------------------------
@@ -1191,7 +1218,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to get spend breakdown', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get spend breakdown', response.status, await response.text());
         }
         return response.json();
     }
@@ -1213,7 +1240,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to get RoCS', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to get RoCS', response.status, await response.text());
         }
         return response.json();
     }
@@ -1241,7 +1268,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new ToolError('Failed to list receipts', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to list receipts', response.status, await response.text());
         }
         return response.json();
     }
@@ -1265,10 +1292,10 @@ class OneShot {
             body: JSON.stringify(valueTag)
         });
         if (response.status === 404) {
-            throw new ToolError('Receipt not found', 404, 'Receipt not found or not owned by this agent');
+            throw new errors_1.ToolError('Receipt not found', 404, 'Receipt not found or not owned by this agent');
         }
         if (!response.ok) {
-            throw new ToolError('Failed to tag receipt value', response.status, await response.text());
+            throw new errors_1.ToolError('Failed to tag receipt value', response.status, await response.text());
         }
     }
     // ---------------------------------------------------------------------------
@@ -1280,7 +1307,7 @@ class OneShot {
     }
     validate(value, field) {
         if (!value)
-            throw new ValidationError(`${field} is required`, field);
+            throw new errors_1.ValidationError(`${field} is required`, field);
     }
     headers() {
         return {
@@ -1288,8 +1315,21 @@ class OneShot {
             'X-OneShot-SDK-Version': SDK_VERSION
         };
     }
+    /**
+     * 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.
+     */
+    maxCostHeader(maxCost) {
+        if (!maxCost || maxCost <= 0)
+            return undefined;
+        return { 'X-Max-Cost-USDC': maxCost.toString() };
+    }
     async executeToolRequest(endpoint, options, quoteId) {
-        const { signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, ...payload } = options;
+        const { signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, maxCost, ...payload } = options;
+        const extraHeaders = this.maxCostHeader(maxCost);
         // Validate memo
         if (payload.memo !== undefined) {
             if (typeof payload.memo !== 'string' || payload.memo.trim().length === 0) {
@@ -1316,9 +1356,9 @@ class OneShot {
             }
         }
         if (signal?.aborted) {
-            throw new OneShotError('Operation cancelled');
+            throw new errors_1.OneShotError('Operation cancelled');
         }
-        let response = await this.makeRequest(endpoint, payload, undefined, quoteId, signal);
+        let response = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
         // Handle 402 Payment Required
         if (response.status === 402) {
             // Parse x402 v2 PaymentRequired from PAYMENT-REQUIRED header
@@ -1338,10 +1378,10 @@ class OneShot {
             this.log(`Payment required: ${paymentInfo.amount} USDC`);
             this.checkAbortBeforePayment(signal);
             const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-            response = await this.makeRequest(endpoint, payload, auth, quoteId, signal);
+            response = await this.makeRequest(endpoint, payload, auth, quoteId, signal, undefined, extraHeaders);
         }
         if (!response.ok) {
-            throw new ToolError('Tool request failed', response.status, await response.text());
+            throw new errors_1.ToolError('Tool request failed', response.status, await response.text());
         }
         const result = await response.json();
         // Handle async jobs
@@ -1364,12 +1404,12 @@ class OneShot {
             this.log('WebSocket unavailable, falling back to HTTP polling');
             result = await this.pollJobHttp(requestId, timeoutSec, signal, onStatusUpdate);
         }
-        // Optional second phase: keep polling for Apollo phone-reveal callbacks.
+        // 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 Apollo enrichment is
-        // pending an async webhook). 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.
+        // 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
@@ -1380,9 +1420,9 @@ class OneShot {
         return result;
     }
     /**
-     * Detects whether a job result is still waiting for Apollo's async phone
-     * reveal. The worker sets `result.phones_pending=true` when an enrichment
-     * was Apollo-sourced and Apollo's webhook URL is configured. The webhook
+     * 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.
      *
      * Tolerates two shapes: the unwrapped result `{phones_pending}` and the
@@ -1400,11 +1440,12 @@ class OneShot {
         return false;
     }
     /**
-     * Slow poll loop that waits for Apollo phone-reveal callbacks to arrive
-     * via the webhook handler (which UPDATEs jobs.result_data.result.phones).
-     * Polls GET /v1/requests/{id} every 5s — Apollo says "several minutes" so
-     * a tight loop wastes API calls. Returns the latest snapshot whether or
-     * not phones arrived (consumer can re-check `phones_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`).
      */
     async _pollForPhones(requestId, timeoutSec, signal, initialResult) {
         const deadline = Date.now() + timeoutSec * 1000;
@@ -1414,7 +1455,7 @@ class OneShot {
         let lastResult = initialResult;
         while (Date.now() < deadline) {
             if (signal?.aborted)
-                throw new OneShotError('Operation cancelled');
+                throw new errors_1.OneShotError('Operation cancelled');
             try {
                 const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: this.headers(),
@@ -1425,7 +1466,7 @@ class OneShot {
                     // whatever we last had so consumers don't lose the sync result.
                     if (lastResult !== undefined)
                         return lastResult;
-                    throw new ToolError('Failed to check job status', resp.status, await resp.text());
+                    throw new errors_1.ToolError('Failed to check job status', resp.status, await resp.text());
                 }
                 const job = await resp.json();
                 lastResult = (job.result ?? job);
@@ -1434,7 +1475,7 @@ class OneShot {
                 }
             }
             catch (err) {
-                if (err instanceof OneShotError)
+                if (err instanceof errors_1.OneShotError)
                     throw err;
                 if (lastResult !== undefined)
                     return lastResult;
@@ -1497,7 +1538,7 @@ class OneShot {
                 signal.addEventListener('abort', () => {
                     settle(() => {
                         cleanup();
-                        reject(new OneShotError('Operation cancelled'));
+                        reject(new errors_1.OneShotError('Operation cancelled'));
                     });
                 }, { once: true });
             }
@@ -1538,7 +1579,7 @@ class OneShot {
                     else if (msg.status === 'failed') {
                         settle(() => {
                             cleanup();
-                            reject(new JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown')));
+                            reject(new errors_1.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown')));
                         });
                     }
                     else {
@@ -1574,14 +1615,14 @@ class OneShot {
         const maxRetries = 3;
         while (Date.now() - startTime < maxWaitMs) {
             if (signal?.aborted)
-                throw new OneShotError('Operation cancelled');
+                throw new errors_1.OneShotError('Operation cancelled');
             try {
                 const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: this.headers(),
                     signal
                 });
                 if (!resp.ok) {
-                    throw new ToolError('Failed to check job status', resp.status, await resp.text());
+                    throw new errors_1.ToolError('Failed to check job status', resp.status, await resp.text());
                 }
                 const job = await resp.json();
                 if (job.status === 'completed') {
@@ -1594,42 +1635,43 @@ class OneShot {
                     return result;
                 }
                 if (job.status === 'failed') {
-                    throw new JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'));
+                    throw new errors_1.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'));
                 }
                 onStatusUpdate?.(job.status, requestId);
                 retries = 0;
                 await this.sleep(pollInterval, signal);
             }
             catch (err) {
-                if (err instanceof OneShotError)
+                if (err instanceof errors_1.OneShotError)
                     throw err;
                 if (++retries > maxRetries) {
-                    throw new OneShotError(`Polling failed after ${maxRetries} retries: ${err}`);
+                    throw new errors_1.OneShotError(`Polling failed after ${maxRetries} retries: ${err}`);
                 }
                 const backoff = pollInterval * Math.pow(2, retries - 1);
                 this.log(`Retry ${retries}/${maxRetries} in ${backoff}ms`);
                 await this.sleep(backoff, signal);
             }
         }
-        throw new JobTimeoutError(requestId, Date.now() - startTime);
+        throw new errors_1.JobTimeoutError(requestId, Date.now() - startTime);
     }
     sleep(ms, signal) {
         return new Promise((resolve, reject) => {
             if (signal?.aborted) {
-                return reject(new OneShotError('Operation cancelled'));
+                return reject(new errors_1.OneShotError('Operation cancelled'));
             }
             const timer = setTimeout(resolve, ms);
             const onAbort = () => {
                 clearTimeout(timer);
-                reject(new OneShotError('Operation cancelled'));
+                reject(new errors_1.OneShotError('Operation cancelled'));
             };
             signal?.addEventListener('abort', onAbort, { once: true });
         });
     }
-    async makeRequest(endpoint, data, payment, quoteId, signal, timeoutMs) {
+    async makeRequest(endpoint, data, payment, quoteId, signal, timeoutMs, extraHeaders) {
         const headers = {
             'Content-Type': 'application/json',
-            ...this.headers()
+            ...this.headers(),
+            ...(extraHeaders ?? {})
         };
         if (payment) {
             const paymentJson = JSON.stringify(payment);
@@ -1663,7 +1705,7 @@ class OneShot {
     }
     checkAbortBeforePayment(signal) {
         if (signal?.aborted) {
-            throw new OneShotError('Operation cancelled before payment');
+            throw new errors_1.OneShotError('Operation cancelled before payment');
         }
     }
     /**