@oneshot-agent/sdk 0.62.0 → 0.63.0

package/dist/index.js

@@ -65,7 +65,7 @@ __exportStar(require("./errors"), exports);
 const approvals_1 = require("./approvals");
 // Keep receipt on its subpath: node:crypto breaks browser bundles, and providerCost is not public.
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.62.0';
+const SDK_VERSION = '0.63.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. */
@@ -320,6 +320,39 @@ class OneShot {
     async tool(toolName, options) {
         return this.executeToolRequest(`/v1/tools/${toolName}`, options);
     }
+    /**
+     * Price account setup without a recipient or message; this does not buy or send. Choose the mode
+     * (`relay` by default, or `mailbox`) and the addresses (default `['agent']`). On a verified domain
+     * the agent already has, this prices only the named addresses it does not have yet.
+     */
+    async quoteDomain(domain, options = {}) {
+        this.validate(domain, 'domain');
+        const { mailbox_mode, addresses, ...rest } = options;
+        if (mailbox_mode !== undefined && mailbox_mode !== 'relay' && mailbox_mode !== 'mailbox') {
+            throw new errors_2.ValidationError("mailbox_mode must be 'relay' or 'mailbox'", 'mailbox_mode');
+        }
+        if (addresses !== undefined && (!Array.isArray(addresses) || addresses.length < 1 || addresses.length > 10
+            || addresses.some((a) => typeof a !== 'string' || !a.trim()))) {
+            throw new errors_2.ValidationError('addresses must name 1 to 10 local parts, such as ["sales"]', 'addresses');
+        }
+        const quote = await this.executeToolRequest('/v1/domains/quote', {
+            ...rest, domain,
+            ...(mailbox_mode ? { mailbox_mode } : {}),
+            ...(addresses ? { addresses: addresses.map((a) => a.trim().toLowerCase()) } : {}),
+        });
+        if (quote.total_cost !== undefined)
+            this.assertWithinMaxCost(String(quote.total_cost), options.maxCost);
+        return quote;
+    }
+    /**
+     * Owner/API purchase of the exact setup quote. The mode and addresses are the quote's; the result
+     * names them. Registration, adding addresses and email are separate actions.
+     */
+    async buyDomain(domain, quoteId, options = {}) {
+        this.validate(domain, 'domain');
+        this.validate(quoteId?.trim(), 'quoteId');
+        return this.executeToolRequest('/v1/domains/buy', { ...options, domain }, quoteId.trim());
+    }
     async email(options) {
         // to/subject are server-derived when replying to an inbound email.
         if (!options.reply_to_email_id) {
@@ -332,59 +365,117 @@ class OneShot {
         if (options.from_mailbox && !options.from_domain) {
             throw new errors_2.ValidationError('from_mailbox was pinned without from_domain. Pass from_domain (a domain you own) as well, or omit both to rotate across your warmed domains.', 'from_domain');
         }
-        const useRotation = !options.from_domain && !options.from_mailbox;
-        const fromAddress = useRotation
-            ? undefined
-            : `${options.from_mailbox ?? 'agent'}@${options.from_domain}`;
         // Reuse the confirmed quote so the charge matches the amount shown; true alone confirms no amount.
         const confirmedQuote = typeof options.confirmNewDomain === 'string' && options.confirmNewDomain.trim()
             ? options.confirmNewDomain.trim() : undefined;
         if (confirmedQuote) {
-            this.log(`Email: sending against confirmed quote ${confirmedQuote}`);
-            return this.executeToolRequest('/v1/tools/email/send', this.emailSendPayload(options, fromAddress), confirmedQuote);
+            this.validate(options.from_domain, 'from_domain');
+            const setup = await this.buyDomain(options.from_domain, confirmedQuote, {
+                maxCost: options.maxCost, signal: options.signal, wait: false,
+            });
+            return { status: 'setup_pending', setup, request_id: setup.request_id, receipt_id: setup.receipt_id,
+                message: 'Setup purchased; no email was sent. Wait for it to finish, then call email without confirmNewDomain.' };
+        }
+        let fromAddress;
+        if (options.from_domain) {
+            const domainName = options.from_domain.trim().toLowerCase().replace(/\.$/, '');
+            // An unavailable ownership read leaves the email quote to decide whether setup is needed.
+            const owned = await this.listDomains().catch(() => undefined);
+            const entry = owned?.domains.find(d => d.domain.toLowerCase() === domainName);
+            // A new name reaches the setup quote without an email quote.
+            if (owned && !entry)
+                return this.emailDomainSetup(domainName, options);
+            fromAddress = options.from_mailbox
+                ? `${options.from_mailbox}@${options.from_domain}`
+                : entry?.default_from ?? `agent@${options.from_domain}`;
+        }
+        let quote;
+        try {
+            quote = await this.tool('email/quote', {
+                ...(fromAddress ? { from_address: fromAddress } : {}),
+                ...(options.to !== undefined ? { to_address: options.to } : {}),
+                ...(options.subject !== undefined ? { subject: options.subject } : {}),
+                ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
+                body: options.body,
+                maxCost: options.maxCost,
+            });
+        }
+        catch (error) {
+            const setup = await this.emailSetupFromRefusal(error, options);
+            if (setup)
+                return setup;
+            throw error;
         }
-        // Mailbox provisioning and domain registration are distinct fees; only a new domain needs confirmation.
-        const quote = await this.tool('email/quote', {
-            ...(fromAddress ? { from_address: fromAddress } : {}),
-            ...(options.to !== undefined ? { to_address: options.to } : {}),
-            ...(options.subject !== undefined ? { subject: options.subject } : {}),
-            ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
-            ...(options.mailbox_mode ? { mailbox_mode: options.mailbox_mode } : {}),
-            body: options.body,
-            maxCost: options.maxCost,
-        });
         this.log(`Email quote: $${quote.total_cost}`);
         // Enforce the cap locally even if the server did not check the header.
         this.assertWithinMaxCost(quote.total_cost, options.maxCost);
-        // A new domain must be explicitly authorized against its exact quote before any charge or send.
-        if (quote.is_new) {
-            const domainName = quote.domain ?? options.from_domain ?? '';
-            const breakdown = quote.registration_fee !== undefined && quote.service_fee !== undefined
-                ? ` (registration $${quote.registration_fee} + service fee $${quote.service_fee}` +
-                    `${quote.mailbox_provisioning_fee ? ` + mailbox fee $${quote.mailbox_provisioning_fee}` : ''})`
-                : '';
-            return {
-                status: 'confirmation_required',
-                cost: parseFloat(quote.total_cost),
-                quote_id: quote.quote_id,
-                domain: { domain: domainName, status: 'quote_only', was_provisioned: false },
-                message: `Registering ${domainName} costs $${quote.total_cost} total${breakdown}. ` +
-                    `Nothing has been charged yet. Show the user this exact amount; once they agree, call this again with the same ` +
-                    `arguments and confirm_new_domain: '${quote.quote_id}' (SDK: confirmNewDomain) to register the domain, ` +
-                    `charge exactly $${quote.total_cost}, and send this email. true only re-quotes; a wrong or expired quote id is refused without charge.`,
-            };
-        }
         return this.executeToolRequest('/v1/tools/email/send', this.emailSendPayload(options, fromAddress ?? quote.from_address), quote.quote_id);
     }
-    /** The /email/send body for `email()`: the same whether it follows a fresh quote or a confirmed one. */
+    /**
+     * A send never sets up a domain or an address: the email quote refuses with `no_sending_domain` or
+     * `address_not_set_up` and names the setup. Route that to the setup quote, so the caller reviews its
+     * price, rather than surfacing a bare error. Any other error is the caller's.
+     */
+    async emailSetupFromRefusal(error, options) {
+        if (!(error instanceof errors_2.ToolError) || error.statusCode !== 400)
+            return undefined;
+        let body;
+        try {
+            body = JSON.parse(error.responseBody);
+        }
+        catch {
+            return undefined;
+        }
+        const requirements = Array.isArray(body.requirements) ? body.requirements : undefined;
+        if (body.error === 'address_not_set_up' && body.domain && body.from_address) {
+            const local = body.from_address.split('@')[0];
+            try {
+                return await this.emailDomainSetup(body.domain, options, [local]);
+            }
+            catch (quoteError) {
+                // The address is already being added by an earlier purchase.
+                if (quoteError instanceof errors_2.ToolError && quoteError.statusCode === 409 && /addresses_already_set_up/.test(quoteError.responseBody)) {
+                    return { status: 'setup_pending', error: 'address_not_set_up', requirements,
+                        message: `${body.from_address} is being set up; no email was sent. Send again once it is active in listDomains().` };
+                }
+                throw quoteError;
+            }
+        }
+        if (body.error !== 'no_sending_domain')
+            return undefined;
+        const domain = body.domain ?? options.from_domain?.trim().toLowerCase();
+        if (body.reason === 'not_owned' && domain)
+            return this.emailDomainSetup(domain, options);
+        const pending = body.reason === 'not_verified';
+        return {
+            status: pending ? 'setup_pending' : 'setup_required', error: 'no_sending_domain', requirements,
+            message: body.message ?? 'This agent has no verified sending domain. Buy one with quoteDomain and buyDomain; no email was sent.',
+        };
+    }
+    async emailDomainSetup(domainName, options, addresses) {
+        const named = addresses ?? (options.from_mailbox ? [options.from_mailbox] : undefined);
+        const setup = await this.quoteDomain(domainName, { maxCost: options.maxCost, signal: options.signal, ...(named ? { addresses: named } : {}) });
+        const addingAddresses = setup.setup === 'domain_addresses';
+        return {
+            status: setup.purchasable ? 'confirmation_required' : 'setup_unavailable',
+            cost: setup.total_cost,
+            quote_id: setup.quote_id,
+            setup,
+            domain: { domain: domainName, status: 'quote_only', was_provisioned: false },
+            message: !setup.purchasable
+                ? 'This name cannot be purchased. Choose another name for account setup.'
+                : addingAddresses
+                    ? 'This address is not on the domain yet. No purchase or email send has occurred. The owner or API caller must review setup.total_cost, then buy this exact quote at POST /v1/domains/buy (SDK: confirmNewDomain). Send separately once the address is active.'
+                    : 'No setup purchase or email send has occurred. The owner or API caller must review setup.total_cost and setup.billing, then buy this exact quote at POST /v1/domains/buy (SDK: confirmNewDomain). No email is included; send separately after verification.',
+        };
+    }
+    /** Keep setup-only fields out of the paid send body. */
     emailSendPayload(options, resolvedFromAddress) {
         const payload = {
             ...(resolvedFromAddress ? { from_address: resolvedFromAddress } : {}),
             ...(options.to !== undefined ? { to_address: options.to } : {}),
             ...(options.subject !== undefined ? { subject: options.subject } : {}),
             ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
-            // Preserve mailbox provisioning when the new domain does not yet have a stored mode.
-            ...(options.mailbox_mode ? { mailbox_mode: options.mailbox_mode } : {}),
             body: options.body,
             signal: options.signal,
             onStatusUpdate: options.onStatusUpdate,
@@ -1140,8 +1231,8 @@ class OneShot {
      * already has with them, or a new one. Use it once an invitation is accepted,
      * or for a connection the account has never messaged. Needs the `reply`
      * grant; shares the reply daily cap and pacing. A failed send carries an
-     * error code: `not_connected` (invite them first) and `rate_limited` mean
-     * "defer", not "give up".
+     * error code: `recipient_not_connected` means invite them first, not give
+     * up.
      */
     async linkedinMessage(options) {
         this.validate(options.accountId, 'accountId');
@@ -1489,7 +1580,7 @@ class OneShot {
     }
     /**
      * The agent's connections: GitHub and business systems, each with `id`, `system`, `account_label` and
-     * `status`. Free. A connected-system read (ledger, CRM, shipping, tax, procurement, meetings) takes the `id` of an active
+     * `status`. Free. A connected-system read (ledger, CRM, shipping, tax, procurement, meetings, field service) takes the `id` of an active
      * one as `connection_id`; pick it by `system` and `account_label`, then call the read with the generic
      * {@link OneShot.route}.
      *
@@ -1638,7 +1729,7 @@ class OneShot {
      * with JobError (goal ID, end_reason code, snapshot in partialResult).
      * Budget exhaustion waits in awaiting_budget for funding; after seven days it ends. After fundComputeGoal revives an ended goal,
      * call waitForComputeGoal again with the same ID to observe the new run.
-     * Paused/awaiting_confirmation/awaiting_connection/awaiting_budget/awaiting_tool and recurring goals keep waiting until the
+     * Paused/awaiting_confirmation/awaiting_connection/awaiting_budget/awaiting_tool/awaiting_setup 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.
@@ -1696,7 +1787,8 @@ class OneShot {
         }
     }
     /**
-     * List tasks under a compute goal
+     * List tasks under a compute goal, newest first: one page of `limit` tasks (default 100, at most 500).
+     * Use `getComputeTasksPage` to read further pages.
      *
      * @example
      * ```typescript
@@ -1706,16 +1798,40 @@ class OneShot {
      * }
      * ```
      */
-    async getComputeTasks(goalId) {
+    async getComputeTasks(goalId, options = {}) {
+        return (await this.getComputeTasksPage(goalId, options)).tasks;
+    }
+    /**
+     * One page of a compute goal's tasks, newest first, with the cursor of the next page (null on the last).
+     *
+     * @example
+     * ```typescript
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await agent.getComputeTasksPage('goal_01HX...', { cursor });
+     *   for (const t of page.tasks) console.log(t.id, t.status);
+     *   cursor = page.next_cursor ?? undefined;
+     * } while (cursor);
+     * ```
+     */
+    async getComputeTasksPage(goalId, options = {}) {
         this.validate(goalId, 'goalId');
-        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/tasks`, {
+        const query = new URLSearchParams();
+        if (options.status)
+            query.set('status', options.status);
+        if (options.limit !== undefined)
+            query.set('limit', String(options.limit));
+        if (options.cursor)
+            query.set('cursor', options.cursor);
+        const qs = query.toString();
+        const response = await this.fetchApi(`${this.baseUrl}/v1/compute/${goalId}/tasks${qs ? `?${qs}` : ''}`, {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
             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;
+        return { tasks: json.data, next_cursor: json.page?.next_cursor ?? null };
     }
     /**
      * List what a compute goal produced: the files its sandbox tasks left and
@@ -1913,7 +2029,7 @@ class OneShot {
         return json.data;
     }
     /**
-     * Pause a recurring compute goal
+     * Pause a compute goal (one-off goals keep their work and continue where they were on resume)
      *
      * @example
      * ```typescript
@@ -1934,7 +2050,7 @@ class OneShot {
         return json.data;
     }
     /**
-     * Resume a paused recurring compute goal
+     * Resume a paused compute goal
      *
      * @example
      * ```typescript
@@ -2540,6 +2656,9 @@ class OneShot {
         const credits = response.status === 402 ? this.parseInsufficientCredits(text) : undefined;
         if (credits)
             throw credits;
+        const ambiguous = response.status === 500 ? this.parseSettlementAmbiguous(text) : undefined;
+        if (ambiguous)
+            throw ambiguous;
         const rejection = [402, 500].includes(response.status) ? this.parsePaymentRejection(text) : undefined;
         if (rejection)
             throw rejection;
@@ -2648,6 +2767,20 @@ class OneShot {
             return undefined;
         }
     }
+    /** A 500 `settlement_ambiguous`: the payment may be spent, so the caller must not sign another for this call. */
+    parseSettlementAmbiguous(text) {
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+        if (body?.error !== 'settlement_ambiguous')
+            return undefined;
+        const settlementId = typeof body.settlement_id === 'string' ? body.settlement_id : undefined;
+        return new errors_1.SettlementAmbiguousError(`Payment may have gone through. Don't pay again; if it landed and the call did not run, it is credited to your account.${settlementId ? ` [settlement ${settlementId}]` : ''}`, settlementId);
+    }
     parsePaymentRejection(text) {
         let data;
         try {
@@ -2726,7 +2859,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|lookup\/company-private-raises|solve|predict|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint);
+        const reliable = /(?:^|\/)(lookup\/person-(profile|email|email-status)|lookup\/place-permits|lookup\/company-private-raises|lookup\/company-fund-holdings|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');
@@ -2839,7 +2972,7 @@ class OneShot {
             if (duplicate?.error === 'duplicate_request' && typeof duplicate.details?.request_id === 'string') {
                 response = Response.json({ request_id: duplicate.details.request_id, receipt_id: duplicate.details.receipt_id,
                     status: 'processing', tool: 'linkedin', linkedin: { action_request_id: duplicate.details.action_request_id,
-                        invitation_id: duplicate.details.invitation_id } }, { status: 202 });
+                        invitation_id: duplicate.details.invitation_id, scheduled_for: null } }, { status: 202 });
             }
         }
         if (!response.ok) {
@@ -3295,7 +3428,7 @@ class OneShot {
         // Identity Verification requires wallet proof on the payment leg too, to recover keyed submissions.
         const provenPayment = /(?:^|\/)identity\/start$/.test(endpoint);
         const askedForProof = !!extraHeaders?.['x-agent-proof'];
-        const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|lookup\/company-private-raises|physical-mail\/send|solve|predict)$/.test(endpoint)
+        const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|lookup\/company-private-raises|lookup\/company-fund-holdings|physical-mail\/send|solve|predict)$/.test(endpoint)
             ? 'submit'
             : askedForProof ? 'read' : 'write';
         const headers = {
@@ -3466,14 +3599,22 @@ 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|lookup\/company-private-raises|physical-mail\/send|solve|predict|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
+            if (!/(lookup\/person-(profile|email|email-status)|lookup\/place-permits|lookup\/company-private-raises|lookup\/company-fund-holdings|physical-mail\/send|solve|predict|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
                 this.releaseUsdcReservation(signed.reservation);
             throw err;
         }
-        if (!resp.ok && !(extraHeaders?.['Idempotency-Key'] && resp.status >= 500))
+        // A settlement_ambiguous payment may be spent: keep its reservation until it expires.
+        if (!resp.ok && !(extraHeaders?.['Idempotency-Key'] && resp.status >= 500) && !(await this.isSettlementAmbiguous(resp))) {
             this.releaseUsdcReservation(signed.reservation);
+        }
         return resp;
     }
+    async isSettlementAmbiguous(resp) {
+        if (resp.status !== 500)
+            return false;
+        const text = await resp.clone().text().catch(() => '');
+        return this.parseSettlementAmbiguous(text) !== undefined;
+    }
     /** Parse the PAYMENT-REQUIRED header from a 402 response into the accepted requirements and Bazaar metadata. */
     parsePaymentRequired(header) {
         if (header) {