@oneshot-agent/mcp-server 0.49.0 → 0.51.0

package/README.md

@@ -79,12 +79,12 @@ Every tool is named `oneshot_<name>`. Below are the names.
 | [Talk](https://docs.oneshotagent.com/api-reference/email/send) | `email` `voice` `sms` `inbox_list` `inbox_get` `sms_inbox_list` `sms_inbox_get` `notifications` `mark_notification_read` |
 | [Inbound calls](https://docs.oneshotagent.com/api-reference/voice/inbound) | `voice_number_provision` `voice_numbers` `voice_inbound_set` `voice_inbound_disable` `voice_inbound_calls` |
 | [Send from your domains](https://docs.oneshotagent.com/api-reference/email/domains) | `list_domains` `pause_domain` `resume_domain` |
-| [Find people and companies](https://docs.oneshotagent.com/api-reference/research/person-find) | `person_find` `person_profile` `person_email` `person_email_status` `person_dossier` `person_social_accounts` `person_articles` `person_posts` `person_interests` `person_followers` `company_find` `company_profile` `business_find` `business_resolve` `record_solicitations_find` |
+| [Find people and companies](https://docs.oneshotagent.com/api-reference/research/person-find) | `person_find` `person_profile` `person_email` `person_email_status` `person_dossier` `person_social_accounts` `person_articles` `person_posts` `person_interests` `person_followers` `company_find` `company_profile` `company_dossier` `business_find` `business_resolve` `record_solicitations_find` |
 | [Lookups](https://docs.oneshotagent.com/tools-and-goals#lookups) | public records, places, products, vehicles, genes, proteins and more, one tool each |
 | [Think](https://docs.oneshotagent.com/api-reference/research) | `research` `predict` `solve` |
 | [Web and buying](https://docs.oneshotagent.com/api-reference/web-search) | `web_search` `web_read` `browser` `product_find` `commerce_buy` |
 | [Physical mail](https://docs.oneshotagent.com/api-reference/physical-mail/overview) | `physical_mail_upload` `physical_mail_validate_address` `physical_mail_preview` `physical_mail_quote` `physical_mail_approve` `physical_mail_send` `physical_mail_recover` `physical_mail_order` `physical_mail_cancel` |
-| [Connected systems](https://docs.oneshotagent.com/api-reference/connections/overview) | `connections_list` `ledger_invoices` `ledger_bills` `ledger_reports` `crm_accounts` `crm_contacts` `crm_opportunities` `tax_rates` `tax_calculate` `shipping_shipments` `shipping_tracking` `shipping_rates` `procurement_transactions` `procurement_bills` `procurement_suppliers` |
+| [Connected systems](https://docs.oneshotagent.com/api-reference/connections/overview) | `connections_list` `ledger_invoices` `ledger_invoice_lines` `ledger_bills` `ledger_reports` `ledger_bank_transactions` `crm_accounts` `crm_contacts` `crm_opportunities` `crm_tickets` `crm_activity` `tax_rates` `tax_calculate` `shipping_shipments` `shipping_tracking` `shipping_rates` `procurement_transactions` `procurement_bills` `procurement_suppliers` `meetings_list` `meetings_get` `field_service_clients` `field_service_jobs` `field_service_quotes` `field_service_invoices` |
 | [LinkedIn](https://docs.oneshotagent.com/api-reference/linkedin/overview) | `linkedin_connect` `linkedin_accounts` `linkedin_invite` `linkedin_message` `linkedin_reply` and more |
 | [Build](https://docs.oneshotagent.com/api-reference/build/create) | `build` `update_build` |
 | [Goals](https://docs.oneshotagent.com/api-reference/compute/create) | `compute` `compute_status` `compute_tasks` `compute_respond` `compute_pause` `compute_resume` `compute_fund` `compute_cancel` |
@@ -110,9 +110,10 @@ wallet. The server signs it for you. A read with no proof and no valid token is
 ## Tool notes
 
 - **Email.** Omit `from_domain` and `from_mailbox` and the send rotates across
-  your warmed domains. `from_mailbox` needs `from_domain`. A new `from_domain`
-  only quotes; nothing is charged until you confirm. `mailbox_mode` applies only
-  when a domain is first set up. [Details](https://docs.oneshotagent.com/api-reference/email/send).
+  your domains, each from its main address. `from_mailbox` needs `from_domain`
+  and must be one of the domain's addresses. A new `from_domain` or address only
+  quotes its setup; nothing is charged or sent. The owner picks the domain's mode
+  and addresses when buying it. [Details](https://docs.oneshotagent.com/api-reference/email/send).
 - **Phone lookup** is off by default on `person_find`, `person_profile` and
   `person_dossier`. `include_phone: true` is charged for each person you ask for
   (the search limit, default 100), or once for a profile or dossier, found or not.
@@ -149,7 +150,7 @@ wallet. The server signs it for you. A read with no proof and no valid token is
 
 ## Tool discovery
 
-The MCP catalog contains 193 tools. `oneshot_discover_tools` is a free, read-only
+The MCP catalog contains 243 tools. `oneshot_discover_tools` is a free, read-only
 search over the tools your token can call. Call it with no arguments for category
 counts, `{ "query": "send a printed letter" }` to search, or `{ "category": "email" }`
 to browse. Results contain public tool names, purposes and required inputs.

package/dist/index.js

@@ -50,7 +50,7 @@ async function main() {
     const agent = await initAgent();
     const server = new Server({
         name: "oneshot-mcp",
-        version: "0.49.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.51.0", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/annotations.d.ts

@@ -6,8 +6,10 @@ import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
  *
  *   readOnlyHint     true  = retrieval only (paid lookups included — the only
  *                            side effect is our own billing)
- *   destructiveHint  true  = deletes, overwrites or revokes something. Sends are
- *                            additive writes, so false — like any mail app's send.
+ *   destructiveHint  true  = deletes, overwrites or revokes something, or is an
+ *                            irreversible send or transaction (a message, call, letter
+ *                            or purchase cannot be taken back). OpenAI's plugin
+ *                            guidelines ask for true on those.
  *   openWorldHint    true  = reaches the public web or third parties;
  *                    false = only the caller's own OneShot account data.
  */

package/dist/tools/annotations.js

@@ -1,38 +1,47 @@
 import { LOOKUP_MANIFEST, ROUTE_MANIFEST } from "./lookup-manifest.generated.js";
 /** Retrieval only. */
 const read = (title, openWorld) => ({ title, readOnlyHint: true, destructiveHint: false, openWorldHint: openWorld });
-/** Changes something. `destructive` only for delete / overwrite / revoke. */
+/** Changes something. `destructive` for delete / overwrite / revoke and for irreversible sends and transactions. */
 const write = (title, openWorld, destructive = false) => ({ title, readOnlyHint: false, destructiveHint: destructive, openWorldHint: openWorld });
+/** Declared routes that cannot be taken back or overwrite settings (a watch's cap and webhook), so destructive. */
+const IRREVERSIBLE_ROUTES = new Set(["physical_mail_approve", "physical_mail_cancel", "identity_start", "watch_update"]);
+/**
+ * Free declared routes that still reach outside the account, so open-world: approving a mail quote posts a
+ * letter, an identity check sends a person a link, a watch follows third-party data and may call a webhook,
+ * and a browser account connection signs in to another site.
+ */
+const OUTBOUND_ROUTES = new Set(["physical_mail_approve", "identity_start", "watch", "watch_update", "browser_connect_account"]);
 /** The connected-system reads (#2403): paid, but each reads the caller's own connected business system, so closed-world. */
-const CONNECTED_SYSTEM_READ = /^\/v1\/tools\/(ledger|crm|shipping|tax|procurement)\//;
+const CONNECTED_SYSTEM_READ = /^\/v1\/tools\/(ledger|crm|shipping|tax|procurement|meetings|mailbox|files|field_service)\//;
 const OPEN = true;
 const OWN = false;
 const DESTRUCTIVE = true;
 export const TOOL_ANNOTATIONS = {
     oneshot_discover_tools: read("Discover tools", OWN),
+    oneshot_lookup: read("Run a lookup", OPEN),
     oneshot_solve: read("Solve", OWN),
     oneshot_predict: read("Predict", OWN),
     oneshot_hunt_list: read("List Soul Hunts", OPEN),
     oneshot_hunt_status: read("Get Soul Hunt Status", OPEN),
-    oneshot_hunt_predict: write("Predict Soul Hunt", OPEN),
+    oneshot_hunt_predict: write("Predict Soul Hunt", OPEN, DESTRUCTIVE), // a submitted prediction cannot be withdrawn
     oneshot_hunt_collection: read("List Collected Souls", OWN),
     oneshot_hunt_leaderboard: read("Soul Hunt Leaderboard", OPEN),
-    oneshot_email: write("Send email", OPEN),
-    oneshot_voice: write("Place a phone call", OPEN),
-    oneshot_sms: write("Send a text message", OPEN),
+    oneshot_email: write("Send email", OPEN, DESTRUCTIVE),
+    oneshot_voice: write("Place a phone call", OPEN, DESTRUCTIVE),
+    oneshot_sms: write("Send a text message", OPEN, DESTRUCTIVE),
     oneshot_inbox_list: read("List received emails", OWN),
     oneshot_inbox_get: read("Read a received email", OWN),
     oneshot_sms_inbox_list: read("List received texts", OWN),
     oneshot_sms_inbox_get: read("Read a received text", OWN),
-    oneshot_voice_number_provision: write("Get a phone number", OPEN),
+    oneshot_voice_number_provision: write("Get a phone number", OPEN, DESTRUCTIVE),
     oneshot_voice_numbers: read("List phone numbers", OWN),
     oneshot_voice_inbound_set: write("Set up call answering", OPEN, DESTRUCTIVE), // replaces the number's answering settings; outside callers reach it via the carrier
-    oneshot_voice_inbound_disable: write("Stop answering calls", OPEN),
+    oneshot_voice_inbound_disable: write("Stop answering calls", OPEN, DESTRUCTIVE),
     oneshot_voice_inbound_calls: read("List answered calls", OWN),
     // Physical Mail (#1883): the upload stores artwork in the agent's own account; the send puts a letter in the post.
     // The generated route tools (validate, preview, quote, approve, recover, order, cancel) get their hints from the manifest below.
     oneshot_physical_mail_upload: write("Upload mail artwork", OWN),
-    oneshot_physical_mail_send: write("Send approved physical mail", OPEN),
+    oneshot_physical_mail_send: write("Send approved physical mail", OPEN, DESTRUCTIVE),
     oneshot_research: read("Deep research", OPEN),
     oneshot_person_find: read("Find people", OPEN),
     oneshot_person_profile: read("Look up a person's profile", OPEN),
@@ -51,7 +60,7 @@ export const TOOL_ANNOTATIONS = {
     oneshot_business_resolve: read("Look up a local business", OPEN),
     oneshot_record_solicitations_find: read("Find government contracts", OPEN),
     oneshot_product_find: read("Search products", OPEN),
-    oneshot_commerce_buy: write("Buy a product", OPEN),
+    oneshot_commerce_buy: write("Buy a product", OPEN, DESTRUCTIVE),
     oneshot_compute: write("Start a goal", OPEN),
     oneshot_compute_status: read("Check a goal", OWN),
     oneshot_compute_tasks: read("List a goal's tasks", OWN),
@@ -59,8 +68,8 @@ export const TOOL_ANNOTATIONS = {
     oneshot_compute_respond: write("Answer a goal's question", OWN),
     oneshot_compute_pause: write("Pause a goal", OWN),
     oneshot_compute_resume: write("Resume a goal", OWN),
-    oneshot_compute_fund: write("Add budget to a goal", OWN),
-    oneshot_build: write("Build a website", OPEN),
+    oneshot_compute_fund: write("Add budget to a goal", OWN, DESTRUCTIVE),
+    oneshot_build: write("Build a website", OPEN, DESTRUCTIVE), // publishes a live site and is paid
     oneshot_update_build: write("Update a website", OPEN, DESTRUCTIVE), // overwrites the live site
     oneshot_browser: write("Browse and act on a website", OPEN),
     oneshot_browser_create_profile: write("Create a browser profile", OWN),
@@ -72,14 +81,14 @@ export const TOOL_ANNOTATIONS = {
     oneshot_linkedin_sync: write("Sync LinkedIn messages", OPEN), // paid; imports history into the account
     oneshot_linkedin_conversations: read("List LinkedIn conversations", OWN),
     oneshot_linkedin_messages: read("Read LinkedIn messages", OWN),
-    oneshot_linkedin_reply: write("Reply in a LinkedIn conversation", OPEN),
-    oneshot_linkedin_message: write("Message a LinkedIn connection", OPEN),
+    oneshot_linkedin_reply: write("Reply in a LinkedIn conversation", OPEN, DESTRUCTIVE),
+    oneshot_linkedin_message: write("Message a LinkedIn connection", OPEN, DESTRUCTIVE),
     oneshot_linkedin_invitation: read("Check a LinkedIn invitation", OWN),
     oneshot_linkedin_invitations: read("List LinkedIn invitations", OWN),
-    oneshot_linkedin_invite: write("Send a LinkedIn invitation", OPEN),
+    oneshot_linkedin_invite: write("Send a LinkedIn invitation", OPEN, DESTRUCTIVE),
     oneshot_linkedin_withdraw_invitation: write("Withdraw a LinkedIn invitation", OPEN, DESTRUCTIVE),
     oneshot_linkedin_view_profile: write("View a LinkedIn profile", OPEN), // notify=true is visible to the person
-    oneshot_linkedin_react: write("React to a LinkedIn post", OPEN),
+    oneshot_linkedin_react: write("React to a LinkedIn post", OPEN, DESTRUCTIVE),
     oneshot_list_domains: read("List sending domains", OWN),
     oneshot_pause_domain: write("Pause a sending domain", OWN),
     oneshot_resume_domain: write("Resume a sending domain", OWN),
@@ -92,7 +101,7 @@ export const TOOL_ANNOTATIONS = {
     oneshot_mark_notification_read: write("Mark a notification read", OWN),
     oneshot_get_balance: read("Check balance", OWN),
     oneshot_budget_status: read("Check budget", OWN),
-    oneshot_approval_create: write("Ask a person to approve", OPEN),
+    oneshot_approval_create: write("Ask a person to approve", OPEN, DESTRUCTIVE),
     oneshot_approval_get: read("Check an approval", OWN),
     oneshot_approval_list: read("List approvals", OWN),
     oneshot_approval_cancel: write("Cancel an approval", OWN, DESTRUCTIVE),
@@ -105,10 +114,10 @@ export const TOOL_ANNOTATIONS = {
     // read (Changes, Benchmark) reaches recorded third-party data, a connected-system read the caller's own system; a
     // write changes something, and a DELETE removes it.
     ...Object.fromEntries(ROUTE_MANIFEST.map((entry) => {
-        const own = !entry.paid || CONNECTED_SYSTEM_READ.test(entry.path);
+        const own = (!entry.paid || CONNECTED_SYSTEM_READ.test(entry.path)) && !OUTBOUND_ROUTES.has(entry.name);
         return [
             `oneshot_${entry.name}`,
-            entry.readOnly ? read(entry.title, own ? OWN : OPEN) : write(entry.title, own ? OWN : OPEN, entry.method === "DELETE"),
+            entry.readOnly ? read(entry.title, own ? OWN : OPEN) : write(entry.title, own ? OWN : OPEN, entry.method === "DELETE" || IRREVERSIBLE_ROUTES.has(entry.name)),
         ];
     })),
 };

package/dist/tools/compute.d.ts

@@ -20,11 +20,6 @@ export declare function handleComputeCancel(agent: OneShot, args: Record<string,
 export declare function handleComputeRespond(agent: OneShot, args: Record<string, unknown>): Promise<{
     goal_id: string;
     status: string;
-    end_reason: string | null;
-    dispute: {
-        at: string;
-        reason: string;
-    };
 } | {
     task_id: string;
     goal_id: string;

package/dist/tools/compute.js

@@ -1,6 +1,30 @@
+const KNOWN_GOAL_TOOL = { type: "string", description: 'A OneShot tool name, e.g. "email", "voice", "commerce_buy"' };
+const SCOPE_DRIVERS = { type: "object", additionalProperties: { anyOf: [{ type: "number" }, { type: "boolean" }, { type: "string" }] }, description: 'Request sizes, never prices: recipients, segments, max_duration_minutes, max_steps (e.g. {"max_steps":25}), include_phone and limit, or letter kind/pages/color/double_sided; Predict/Solve size and time_limit_s. Omitted fields use tool defaults.' };
+const SCOPE_USE = {
+    type: "object",
+    properties: {
+        tool: KNOWN_GOAL_TOOL,
+        qty: { type: "integer", minimum: 1, description: "How many times inside one unit" },
+        max_attempts: { type: "integer", minimum: 1, description: "Attempts each use may take" },
+        drivers: SCOPE_DRIVERS,
+        target: { type: "string", description: 'Whom or what the use is pointed at, e.g. "the carrier\'s billing desk"' },
+        persistence: {
+            type: "object",
+            description: "How long a use keeps trying to reach the world, and what happens when it cannot",
+            properties: {
+                max_attempts: { type: "integer", minimum: 1 },
+                spacing_seconds: { type: "integer", minimum: 0, description: "Seconds between two attempts at the same target" },
+                escalate_to: KNOWN_GOAL_TOOL,
+                then: { type: "string", enum: ["owner", "give_up"], description: "After the last attempt: back to you, or given up as unreached" },
+            },
+            required: ["max_attempts", "spacing_seconds", "then"],
+        },
+    },
+    required: ["tool", "qty", "max_attempts"],
+};
 export const computeTool = {
     name: "oneshot_compute",
-    description: "Create an autonomous compute goal: give OneShot an objective and a budget; it plans and runs the steps across OneShot tools. Returns a goal id to poll. Paid tool (quote-to-pay against the budget).",
+    description: "Create an autonomous compute goal: give OneShot an objective and a budget; it plans and runs the steps across OneShot tools. Name the unit of work, how work starts (a given list, an event, a schedule, or once) and what each unit needs, or pass `scope`. The quote returns `scope`, `price` (per unit expected and ceiling, overhead, total or units covered, unpriced, unmeasured) and the `done_check` the goal is held to. Returns a goal id to poll. Paid tool (quote-to-pay against the budget).",
     inputSchema: {
         type: "object",
         properties: {
@@ -43,6 +67,159 @@ export const computeTool = {
                 },
                 additionalProperties: false,
             },
+            done_check: {
+                description: "What done means, written before the goal runs and evaluated in code: the goal completes on its own when the check is met. Without one the goal waits in awaiting_confirmation for its owner to confirm. Give one shape.",
+                oneOf: [
+                    {
+                        type: "object",
+                        description: "At least at_least tasks of a tool (of: tasks, needs tool), events of one type (of: events, needs event_type) or emails that reached a status (of: emails).",
+                        properties: {
+                            kind: { const: "count" },
+                            of: { type: "string", enum: ["tasks", "events", "emails"] },
+                            tool: KNOWN_GOAL_TOOL,
+                            status: { type: "string", description: 'For tasks: "completed" or "failed"; for emails: "sent", "delivered" or "opened"' },
+                            event_type: { type: "string", enum: ["email_reply", "sms_reply", "voice_completed", "task_completed", "task_failed"] },
+                            at_least: { type: "integer", minimum: 1 },
+                        },
+                        required: ["kind", "of", "at_least"],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: "object",
+                        description: "The latest completed result of a tool, at a dot path (omit for the whole result), equals a value or is at least a number. Give exactly one of equals or at_least.",
+                        properties: {
+                            kind: { const: "tool_result" },
+                            tool: KNOWN_GOAL_TOOL,
+                            path: { type: "string", description: 'Dot path into the result, e.g. "result.status" (up to 8 keys)' },
+                            equals: { type: ["string", "number", "boolean"] },
+                            at_least: { type: "number" },
+                        },
+                        required: ["kind", "tool"],
+                        // The API rejects a tool_result check with neither or both criteria; say so in the schema so a client fails before the quote.
+                        oneOf: [{ required: ["equals"] }, { required: ["at_least"] }],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: "object",
+                        description: "No check can be written: the owner confirms completion.",
+                        properties: { kind: { const: "owner" } },
+                        required: ["kind"],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: "object",
+                        description: "Every case of the goal is in one of finished_states (a state in owner_required_for also needs an owner on the record); at least min_cases (default 1) must exist.",
+                        properties: {
+                            kind: { const: "cases" },
+                            finished_states: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 20, description: 'Lowercase state tokens such as "merged"' },
+                            owner_required_for: { type: "array", items: { type: "string" }, maxItems: 20, description: "States from finished_states that only count when the case record names an owner" },
+                            min_cases: { type: "integer", minimum: 1 },
+                        },
+                        required: ["kind", "finished_states"],
+                        additionalProperties: false,
+                    },
+                    {
+                        type: "object",
+                        description: "A named verifier accepts proof the agent submits (a document, photo, link or fields read from a document). The verifier needs an email or a phone number. With fields, a field the proof does not show, or one outside its bounds, is reported back without asking the verifier. One-off goals only.",
+                        properties: {
+                            kind: { const: "evidence" },
+                            verifier: {
+                                type: "object",
+                                properties: {
+                                    name: { type: "string" },
+                                    email: { type: "string" },
+                                    phone: { type: "string", description: "E.164, such as +14155550100" },
+                                    timezone: { type: "string", description: 'IANA zone, e.g. "America/Chicago", for texts' },
+                                },
+                                required: ["name"],
+                                additionalProperties: false,
+                            },
+                            accepts: { type: "string", description: "What proof is acceptable, in plain words; the verifier is shown it" },
+                            fields: {
+                                type: "array",
+                                maxItems: 20,
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        name: { type: "string" },
+                                        description: { type: "string" },
+                                        type: { type: "string", enum: ["string", "number", "boolean"] },
+                                        equals: { type: ["string", "number", "boolean"] },
+                                        one_of: { type: "array", items: { type: "string" } },
+                                        at_least: { type: "number" },
+                                        at_most: { type: "number" },
+                                    },
+                                    required: ["name", "description", "type"],
+                                    additionalProperties: false,
+                                },
+                            },
+                        },
+                        required: ["kind", "verifier", "accepts"],
+                        additionalProperties: false,
+                    },
+                ],
+            },
+            egress_allowlist: {
+                type: "array",
+                items: { type: "string" },
+                maxItems: 50,
+                description: "Hosts the goal's sandboxes may reach besides OneShot's API: hostnames, IPv4 addresses or IPv4 ranges. Setting it (even to []) limits every sandbox of the goal to OneShot's API and these hosts.",
+            },
+            scope: {
+                type: "object",
+                description: "Your reading of the goal, replacing the quote's and priced again in code. Omit it and the quote proposes one. A tool the goal cannot call is refused.",
+                properties: {
+                    unit: {
+                        type: "object",
+                        description: "What one unit is and what starts it",
+                        properties: {
+                            name: { type: "string", description: 'One unit in your words, e.g. "a carrier invoice"' },
+                            starts_on: { type: "string", enum: ["list", "event", "schedule", "once"], description: "A given list, an event in the world, a schedule, or the goal itself once" },
+                        },
+                        required: ["name", "starts_on"],
+                    },
+                    per_unit: {
+                        type: "object",
+                        description: "What one unit takes",
+                        properties: {
+                            uses: { type: "array", maxItems: 50, items: SCOPE_USE, description: "Tool uses inside one unit" },
+                            step_allowance: { type: "integer", minimum: 0, description: "Model steps one unit may take beyond its tool uses" },
+                            done: { type: "array", items: { type: "string" }, minItems: 1, description: 'Case states that finish a unit, e.g. ["paid"]; "unreached" is always among them' },
+                        },
+                        required: ["uses", "step_allowance", "done"],
+                    },
+                    overhead: {
+                        type: "object",
+                        description: "Tool uses outside any unit: setting up, reporting",
+                        properties: {
+                            uses: { type: "array", maxItems: 50, items: { type: "object", properties: { tool: KNOWN_GOAL_TOOL, qty: { type: "integer", minimum: 1 }, max_attempts: { type: "integer", minimum: 1 }, drivers: SCOPE_DRIVERS }, required: ["tool", "qty", "max_attempts"] } },
+                            step_allowance: { type: "integer", minimum: 0 },
+                        },
+                        required: ["uses", "step_allowance"],
+                    },
+                    volume: {
+                        type: "object",
+                        description: 'How many units: {"kind": "list", "count": N} for a given list, {"kind": "open"} otherwise',
+                        properties: { kind: { type: "string", enum: ["list", "open"] }, count: { type: "integer", minimum: 1 } },
+                        required: ["kind"],
+                    },
+                    unpriced: {
+                        type: "array",
+                        maxItems: 50,
+                        description: "What the price list cannot price: a connected system you pay for, or a tool quoted per call",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                reason: { type: "string", enum: ["connection", "quoted_tool"] },
+                                assumption: { type: "string", description: "What remains unknown until a live quote, capped by the remaining goal budget" },
+                            },
+                            required: ["name", "reason"],
+                        },
+                    },
+                },
+                required: ["unit", "per_unit", "overhead", "volume", "unpriced"],
+            },
         },
         required: ["objective"],
     },
@@ -84,14 +261,15 @@ export const computeCancelTool = {
 };
 export const computeRespondTool = {
     name: "oneshot_compute_respond",
-    description: "Respond to a human-in-the-loop task that a compute goal is waiting on (approve/reject or provide input), or send `dispute: true` without task_id to dispute a goal that ended impossible_unverified, with `response` as the reason; nothing is refunded. Free.",
+    description: "Respond to a human-in-the-loop task that a compute goal is waiting on (approve/reject or provide input), send `continue_without_tool: true` without task_id to release a goal awaiting a requested tool (with `response` as the message it resumes with), or send `dispute: true` without task_id to dispute a goal that ended impossible_unverified, with `response` as the reason; nothing is refunded. Free.",
     inputSchema: {
         type: "object",
         properties: {
             goal_id: { type: "string", description: "Compute goal id" },
-            task_id: { type: "string", description: "Id of the task awaiting a response (not with dispute)" },
-            response: { type: "string", description: "Free-text response for the task, or the reason for a dispute" },
+            task_id: { type: "string", description: "Id of the task awaiting a response (not with continue_without_tool or dispute)" },
+            response: { type: "string", description: "Free-text response for the task, the message an awaiting_tool goal resumes with, or the reason for a dispute" },
             approved: { type: "boolean", description: "Approve (true) or reject (false) an approval task" },
+            continue_without_tool: { type: "boolean", description: "Continue an awaiting_tool goal without the requested tool; must be true, without task_id" },
             dispute: { type: "boolean", description: "Dispute an impossible_unverified ending; must be true, without task_id" },
         },
         required: ["goal_id"],
@@ -99,7 +277,7 @@ export const computeRespondTool = {
 };
 export const computePauseTool = {
     name: "oneshot_compute_pause",
-    description: "Pause a recurring compute goal. Its plan and progress are kept — the goal stops taking scheduled runs until resumed. Only recurring (scheduled) goals can be paused. Free.",
+    description: "Pause a compute goal. A recurring goal stops taking scheduled runs until resumed; any other goal keeps its sessions, cases and reserved budget and continues where it was when resumed. Free.",
     inputSchema: {
         type: "object",
         properties: {
@@ -111,7 +289,7 @@ export const computePauseTool = {
 };
 export const computeResumeTool = {
     name: "oneshot_compute_resume",
-    description: "Resume a paused recurring compute goal. Picks up on the existing plan at the next scheduled run — nothing is lost. Free.",
+    description: "Resume a paused compute goal. A recurring goal picks up at its next scheduled run; any other goal continues now where it was. Nothing is lost. Free.",
     inputSchema: {
         type: "object",
         properties: {
@@ -133,7 +311,7 @@ export const computeFundTool = {
     },
 };
 export async function handleCompute(agent, args) {
-    return agent.compute({
+    const options = {
         objective: args.objective,
         budget_usdc: args.budget_usdc,
         params: args.params,
@@ -142,7 +320,12 @@ export async function handleCompute(agent, args) {
         soul_service_slug: args.soul_service_slug,
         schedule: args.schedule,
         approvals: args.approvals,
-    });
+        done_check: args.done_check,
+        egress_allowlist: args.egress_allowlist,
+    };
+    if (args.scope !== undefined)
+        options.scope = args.scope;
+    return agent.compute(options);
 }
 export async function handleComputeStatus(agent, args) {
     return agent.getComputeGoal(args.goal_id);
@@ -163,6 +346,12 @@ export async function handleComputeRespond(agent, args) {
             throw new Error("Send dispute: true, with an optional response, and without task_id");
         return agent.disputeComputeGoal(args.goal_id, { reason: args.response });
     }
+    // The owner continues a goal held for a requested tool without it (#3173); no task answers it either.
+    if (args.continue_without_tool !== undefined) {
+        if (args.continue_without_tool !== true || args.task_id !== undefined)
+            throw new Error("Send continue_without_tool: true, with an optional response, and without task_id");
+        return agent.continueComputeGoalWithoutTool(args.goal_id, { message: args.response });
+    }
     return agent.respondToComputeTask(args.goal_id, {
         task_id: args.task_id,
         response: args.response,

package/dist/tools/connections.d.ts

@@ -3,7 +3,7 @@ import type { OneShot } from "@oneshot-agent/sdk";
 /**
  * The agent's connections (#2403). Hand-written because `GET /v1/connections` is not a declared route: the
  * connected-system read tools (`oneshot_ledger_*`, `oneshot_crm_*`, `oneshot_shipping_*`, `oneshot_tax_*`,
- * `oneshot_procurement_*`) are generated from their routes and each tells the model to call this one first.
+ * `oneshot_procurement_*`, `oneshot_meetings_*`, `oneshot_field_service_*`) are generated from their routes and each tells the model to call this one first.
  * Connecting and revoking stay in the console.
  */
 export declare const connectionsListTool: Tool;

package/dist/tools/connections.js

@@ -1,7 +1,7 @@
 /**
  * The agent's connections (#2403). Hand-written because `GET /v1/connections` is not a declared route: the
  * connected-system read tools (`oneshot_ledger_*`, `oneshot_crm_*`, `oneshot_shipping_*`, `oneshot_tax_*`,
- * `oneshot_procurement_*`) are generated from their routes and each tells the model to call this one first.
+ * `oneshot_procurement_*`, `oneshot_meetings_*`, `oneshot_field_service_*`) are generated from their routes and each tells the model to call this one first.
  * Connecting and revoking stay in the console.
  */
 export const connectionsListTool = {

package/dist/tools/discover.js

@@ -1,6 +1,6 @@
 export const discoverToolsTool = {
     name: 'oneshot_discover_tools',
-    description: 'Find OneShot tools by task or category. Free. Returns public names, purposes and required inputs. With no query or category, lists categories. Category pages contain up to five tools; pass nextCursor with the same query and category.',
+    description: 'Find OneShot tools by task or category. Free. Returns public names, purposes and required inputs; a lookup that is not in your tool list runs with oneshot_lookup. With no query or category, lists categories. Category pages contain up to five tools; pass nextCursor with the same query and category.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/domains.js

@@ -1,6 +1,6 @@
 export const listDomainsTool = {
     name: "oneshot_list_domains",
-    description: "List the agent's sending domains. Each has default_from (canonical default sender, e.g. agent@domain — billed like any address on its first send), mailbox_mode (relay|mailbox), addresses[] (mailboxes already provisioned — {address, status, warmup_state}; empty means none yet), pool_status (rotation eligibility: active|paused|removed), warmup_state (reputation health: warming|warmed|degraded), pause_reason (warming|low_reputation|manual|null), warmup_score, and daily send limits. mailbox_mode is a property of the domain, fixed when it was set up: on a 'mailbox' domain EVERY address not already active in addresses[] bills the one-time mailbox_provisioning_fee on its first send, the canonical default_from included. 'relay' domains never charge it. A domain can be paused AND warming — reputation pauses auto-recover once warmed; manual pauses need a resume. Free.",
+    description: "List the agent's sending domains. Each has default_from (the main address, e.g. agent@domain; rotation and goals send from it), mailbox_mode (relay|mailbox), addresses[] (the addresses the domain sends and receives at: {address, status, warmup_state}), pool_status (rotation eligibility: active|paused|removed), warmup_state (reputation health: warming|warmed|degraded|not_warmed), pause_reason (warming|low_reputation|manual|null), warmup_score, and daily send limits. mailbox_mode is fixed when the domain is bought. relay: addresses send and receive with no hosted inbox; never warmed (not_warmed), they rotate at once on a daily limit that rises with the domain's age. mailbox: each address is a hosted inbox, warmed before it rotates. The owner adds addresses with the domain purchase; a send never creates one. A domain can be paused AND warming: reputation pauses auto-recover once warmed; manual pauses need a resume. Free.",
     inputSchema: { type: "object", properties: {} },
 };
 export const pauseDomainTool = {

package/dist/tools/email.js

@@ -1,7 +1,7 @@
 export const emailTool = {
     name: "oneshot_email",
     description: "Send an email. Supports HTML body, attachments, and threaded replies (set reply_to_email_id to an inbound email id from oneshot_inbox_list/oneshot_inbox_get, or one this agent sent). Paid tool — quote provided before payment.\n\n" +
-        "Sending requires a domain the agent owns. A fresh account has none — call oneshot_list_domains first to see what's already owned. If there is no usable domain, pass from_domain with a new domain to register it. A call with a new from_domain only quotes — nothing is charged — and returns status 'confirmation_required' with the exact cost (domain registration plus fees) and a quote_id. Tell the user that exact computed number, never a guessed or approximate one, and only once they say to proceed, call this again with the same arguments and confirm_new_domain set to that quote_id: that registers the domain, charges exactly the quoted total, and sends the email in one call. The workspace balance must cover it, or the call fails with insufficient_credits.",
+        "Sending requires an owned, verified domain, and a domain sends only from its own addresses. Call oneshot_list_domains first. A send never sets up a domain or an address: a new from_domain, or a from_mailbox the domain does not have, returns status confirmation_required with a separate setup quote, and no agent domain at all returns setup_required with requirements. Nothing is charged or sent. Show setup.total_cost and setup.billing to the owner, who buys through POST /v1/domains/buy or the account console. Models and goals cannot buy setup. Send again once setup is done.",
     inputSchema: {
         type: "object",
         properties: {
@@ -23,21 +23,16 @@ export const emailTool = {
             },
             from_domain: {
                 type: "string",
-                description: "Domain to send from. If you already own it, pass it to pin that domain. If you don't, pass a new domain here to register it — a call with a new from_domain only quotes (status 'confirmation_required' with a quote_id, nothing charged); repeat the call with confirm_new_domain set to that quote_id to register it, charge exactly the quoted registration + service fee (and a mailbox fee if mailbox_mode is 'mailbox'), and send. Only confirm once the user has seen that amount and asked to proceed. Omit both from_domain and from_mailbox to rotate across your warmed domains — the chosen address comes back on the result. Call oneshot_list_domains first to see what you already own.",
+                description: "Pin an owned sending domain, or choose a new name to quote separate account setup. The owner must buy setup and wait for verification before sending. Omit both from_domain and from_mailbox to rotate across eligible owned domains, each sending from its main address.",
             },
             from_mailbox: {
                 type: "string",
-                description: "Sender mailbox / local-part (optional, defaults to 'agent', i.e. agent@from_domain). Requires from_domain to be set — pinning from_mailbox alone is rejected, since there is no domain to attach it to. You can use any local-part — a new address is auto-provisioned on first use (starts unwarmed, warms over time). The FIRST send from any address — including the default 'agent@' — adds a one-time mailbox_provisioning_fee to the quote; it's free only once that address is already provisioned (active). See the domains list for each domain's default_from and existing addresses.",
+                description: "Sender local-part on from_domain (optional, defaults to the domain's main address, its default_from). Requires from_domain. Must be one of the domain's addresses (see oneshot_list_domains); another returns the setup quote that adds it, and no email is sent.",
             },
             from_name: {
                 type: "string",
                 description: "Display name shown to the recipient (optional), e.g. 'Jane Doe' renders as 'Jane Doe <jane@domain>'",
             },
-            mailbox_mode: {
-                type: "string",
-                enum: ["relay", "mailbox"],
-                description: "How this domain sends (optional). 'relay' = no dedicated mailbox, no mailbox fee. 'mailbox' = a real dedicated mailbox per address (better deliverability + per-address warmup); each new address adds a one-time mailbox_provisioning_fee to the quote. Only honored while a domain is unprovisioned (brand new, or owned with provisioning_status 'unprovisioned') — an already-provisioned domain keeps the mode it was created with, which means OMITTING this does not make a send relay and does not avoid the fee. On a domain already in mailbox mode every address that isn't active yet bills the fee on its first send, the default agent@ included; from_mailbox does not change that. Use oneshot_list_domains to see each domain's mailbox_mode before quoting.",
-            },
             attachments: {
                 type: "array",
                 items: {
@@ -55,10 +50,6 @@ export const emailTool = {
                 type: "string",
                 description: "Only when retrying a call the action policy held: the approval_id from the approval_required error, once a human approved it. The call then runs once.",
             },
-            confirm_new_domain: {
-                type: "string",
-                description: "The quote_id from a 'confirmation_required' result, and nothing else. A call with a from_domain you don't own yet always stops before charging and returns that result with the exact total. Only after showing that total to the user and getting their go-ahead, call this again with the same arguments and confirm_new_domain set to the quote_id: the domain is registered, exactly that quote's total is charged, and the email is sent in that one call. Passing true never charges; it only quotes again. A wrong, expired or already-used quote id is rejected by the server without charge: drop it and call again without confirm_new_domain for a fresh quote.",
-            },
         },
         required: ["body"],
     },
@@ -72,10 +63,7 @@ export async function handleEmail(agent, args) {
         from_domain: args.from_domain,
         from_mailbox: args.from_mailbox,
         from_name: args.from_name,
-        mailbox_mode: args.mailbox_mode,
         attachments: args.attachments,
         approvalId: args.approval_id,
-        // Only the quote id confirms; `true` or anything else is not a confirmation.
-        confirmNewDomain: typeof args.confirm_new_domain === "string" ? args.confirm_new_domain : undefined,
     });
 }

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 import { UNTRUSTED_TOOLS } from './untrusted-tools.generated.js';
 import { discoverToolsTool, handleDiscoverTools } from './discover.js';
+import { handleLookupCall, lookupCallTool, lookupTarget } from './lookup-call.js';
 import { emailTool, handleEmail } from "./email.js";
 import { voiceTool, handleVoice } from "./voice.js";
 import { voiceNumberProvisionTool, voiceNumbersTool, voiceInboundSetTool, voiceInboundDisableTool, voiceInboundCallsTool, handleVoiceNumberProvision, handleVoiceNumbers, handleVoiceInboundSet, handleVoiceInboundDisable, handleVoiceInboundCalls, } from "./voice-inbound.js";
@@ -34,6 +35,7 @@ import { connectionsListTool, handleConnectionsList } from "./connections.js";
 import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue } from "./analytics.js";
 const toolDefinitions = [
     discoverToolsTool,
+    lookupCallTool,
     emailTool,
     voiceTool,
     smsTool,
@@ -130,6 +132,7 @@ export const tools = toolDefinitions.map((tool) => {
 });
 const handlers = {
     oneshot_discover_tools: handleDiscoverTools,
+    oneshot_lookup: handleLookupCall,
     "oneshot_email": handleEmail,
     "oneshot_voice": handleVoice,
     "oneshot_sms": handleSms,
@@ -227,7 +230,9 @@ export async function handleToolCall(agent, toolName, args) {
             isError: true,
         };
     }
-    const untrusted = UNTRUSTED_TOOLS.has(toolName.replace(/^oneshot_/, ""));
+    // oneshot_lookup returns what the lookup it runs returns, so it is marked by that lookup.
+    const marked = toolName === "oneshot_lookup" && args.input !== undefined ? lookupTarget(args) ?? toolName : toolName;
+    const untrusted = UNTRUSTED_TOOLS.has(marked.replace(/^oneshot_/, ""));
     try {
         const data = await handler(agent, args);
         const acknowledgement = data && typeof data === "object" && "request_id" in data && "status" in data
@@ -282,6 +287,12 @@ export function structuredToolError(error) {
             };
         case "PaymentError":
             return { error: "payment_failed", message: e.message, reason: e.reason };
+        case "SettlementAmbiguousError":
+            return {
+                error: "settlement_ambiguous",
+                message: e.message,
+                ...(typeof e.settlementId === "string" ? { settlement_id: e.settlementId } : {}),
+            };
         case "ToolError": {
             // Every 4xx the SDK doesn't recognize as one of the typed errors above
             // (budget/credits/payment) lands here as a plain ToolError, and its