@oneshot-agent/mcp-server 0.50.0 → 0.52.0

package/README.md

@@ -84,10 +84,10 @@ Every tool is named `oneshot_<name>`. Below are the names.
 | [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_invoice_lines` `ledger_bills` `ledger_reports` `ledger_bank_transactions` `crm_accounts` `crm_contacts` `crm_opportunities` `tax_rates` `tax_calculate` `shipping_shipments` `shipping_tracking` `shipping_rates` `procurement_transactions` `procurement_bills` `procurement_suppliers` `meetings_list` `meetings_get` |
+| [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` `client_work_clients` `client_work_items` `client_work_timesheets` |
 | [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` |
+| [Goals](https://docs.oneshotagent.com/api-reference/compute/create) | `compute` `compute_status` `compute_tasks` `compute_respond` `compute_pause` `compute_resume` `compute_fund` `compute_cancel`. `compute` adds `quote_text` for bound hires (public soul identity and service) and unmatched specialist questions, without prices. Starting proceeds without unmatched specialists. Otherwise, the usual goal result is returned. |
 | [Money and receipts](https://docs.oneshotagent.com/api-reference/analytics/overview) | `get_balance` `budget_status` `spend_breakdown` `return_on_spend` `receipts_list` `tag_receipt_value` |
 | Soul Hunt | `hunt_list` `hunt_status` `hunt_predict` `hunt_collection` `hunt_leaderboard` |
 
@@ -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 233 tools. `oneshot_discover_tools` is a free, read-only
+The MCP catalog contains 263 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.50.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.52.0", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/annotations.js

@@ -3,14 +3,16 @@ import { LOOKUP_MANIFEST, ROUTE_MANIFEST } from "./lookup-manifest.generated.js"
 const read = (title, openWorld) => ({ title, readOnlyHint: true, destructiveHint: false, openWorldHint: openWorld });
 /** 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"]);
 /**
- * Declared routes that cannot be taken back, so destructive. Approving a mail quote posts a letter and
- * starting an identity check sends a person a link: both reach outside the account, so open-world too.
+ * 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 IRREVERSIBLE_ROUTES = new Set(["physical_mail_approve", "physical_mail_cancel", "identity_start"]);
-const OUTBOUND_ROUTES = new Set(["physical_mail_approve", "identity_start"]);
+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|meetings|mailbox|files)\//;
+const CONNECTED_SYSTEM_READ = /^\/v1\/tools\/(ledger|crm|shipping|tax|procurement|matters|meetings|mailbox|files|field_service|client_work|portfolio|practice)\//;
 const OPEN = true;
 const OWN = false;
 const DESTRUCTIVE = true;
@@ -21,7 +23,7 @@ export const TOOL_ANNOTATIONS = {
     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, DESTRUCTIVE),
@@ -67,7 +69,7 @@ export const TOOL_ANNOTATIONS = {
     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, DESTRUCTIVE),
-    oneshot_build: write("Build a website", OPEN),
+    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),

package/dist/tools/compute.d.ts

@@ -1,5 +1,8 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import type { OneShot } from "@oneshot-agent/sdk";
+import type { OneShot, ComputeQuote } from "@oneshot-agent/sdk";
+export type { ComputeQuote } from "@oneshot-agent/sdk";
+/** Select public quote details explicitly so prices and private identity never enter tool text. */
+export declare function formatComputeQuote(quote: ComputeQuote): string;
 export declare const computeTool: Tool;
 export declare const computeStatusTool: Tool;
 export declare const computeTasksTool: Tool;
@@ -8,7 +11,26 @@ export declare const computeRespondTool: Tool;
 export declare const computePauseTool: Tool;
 export declare const computeResumeTool: Tool;
 export declare const computeFundTool: Tool;
-export declare function handleCompute(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ComputeGoalResult>;
+export declare function handleCompute(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ComputeGoalResult | {
+    quote_text: string;
+    requires?: Array<import("@oneshot-agent/sdk").ComputeRequirement | import("@oneshot-agent/sdk").ComputeToolRequirement>;
+    goal_id: string;
+    request_id: string;
+    receipt_id?: string;
+    status: string;
+    message: string;
+    memo?: string;
+    cost?: number;
+    goal: {
+        objective: string;
+        budget_usdc: string;
+        deadline?: string;
+        schedule_cron?: string;
+        budget_per_run?: number;
+        max_runs?: number;
+        next_run_at?: string;
+    };
+}>;
 export declare function handleComputeStatus(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ComputeGoalStatus>;
 export declare function handleComputeTasks(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").ComputeOutputContent | import("@oneshot-agent/sdk").ComputeTask[]>;
 export declare function handleComputeCancel(agent: OneShot, args: Record<string, unknown>): Promise<{

package/dist/tools/compute.js

@@ -1,10 +1,18 @@
+/** Select public quote details explicitly so prices and private identity never enter tool text. */
+export function formatComputeQuote(quote) {
+    const hires = (quote.price?.hires ?? []).map(hire => `Hires ${hire.display_name} (${hire.soul_slug}) for ${hire.service_name} (${hire.service_slug})${hire.need ? `: ${hire.need}` : ''}.`);
+    const specialists = (quote.requirements ?? []).filter(req => req.kind === 'specialist').map(req => req.question?.trim() ? req.question : `No specialist matched${req.need ? ` for ${req.need}` : ''}. Start the goal to go ahead without one, using the platform's tools.`);
+    return [...hires, ...specialists].join('\n');
+}
 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",
@@ -34,6 +42,11 @@ export const computeTool = {
                 type: "number",
                 description: "Spend ceiling in USDC. Server estimates if omitted.",
             },
+            purchase_limit_usdc: {
+                type: "number",
+                exclusiveMinimum: 0,
+                description: "The most the owner would pay for one purchase, all in. Only set a figure the owner gave you, never your own. It is added to the total and unused money comes back as credit; a live total above it waits for the owner's approval. Without it, the goal pauses at a purchase it can't afford.",
+            },
             params: {
                 type: "object",
                 description: "Additional parameters / constraints for the objective",
@@ -116,6 +129,45 @@ export const computeTool = {
                         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: {
@@ -151,7 +203,7 @@ export const computeTool = {
                         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 } }, required: ["tool", "qty", "max_attempts"] } },
+                            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"],
@@ -171,11 +223,12 @@ export const computeTool = {
                             properties: {
                                 name: { type: "string" },
                                 reason: { type: "string", enum: ["connection", "quoted_tool"] },
-                                assumption: { type: "string", description: 'What the price assumes, e.g. "5 minutes" for a call or "20 steps" for a browser run' },
+                                assumption: { type: "string", description: "What remains unknown until a live quote, capped by the remaining goal budget" },
                             },
                             required: ["name", "reason"],
                         },
                     },
+                    purchase_limit_usdc: { type: "number", exclusiveMinimum: 0, description: "The most per purchase, all in, as the owner gave it. The top-level field wins over this." },
                 },
                 required: ["unit", "per_unit", "overhead", "volume", "unpriced"],
             },
@@ -236,7 +289,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: {
@@ -248,7 +301,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: {
@@ -270,6 +323,7 @@ export const computeFundTool = {
     },
 };
 export async function handleCompute(agent, args) {
+    let quoteText = '';
     const options = {
         objective: args.objective,
         budget_usdc: args.budget_usdc,
@@ -281,10 +335,14 @@ export async function handleCompute(agent, args) {
         approvals: args.approvals,
         done_check: args.done_check,
         egress_allowlist: args.egress_allowlist,
+        onQuote: quote => { quoteText = formatComputeQuote(quote); },
     };
     if (args.scope !== undefined)
         options.scope = args.scope;
-    return agent.compute(options);
+    if (args.purchase_limit_usdc !== undefined)
+        options.purchase_limit_usdc = args.purchase_limit_usdc;
+    const result = await agent.compute(options);
+    return quoteText ? { ...result, quote_text: quoteText } : result;
 }
 export async function handleComputeStatus(agent, args) {
     return agent.getComputeGoal(args.goal_id);

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_*`, `oneshot_meetings_*`) are generated from their routes and each tells the model to call this one first.
+ * `oneshot_procurement_*`, `oneshot_meetings_*`, `oneshot_matters_*`, `oneshot_field_service_*`, `oneshot_client_work_*`, `oneshot_portfolio_*`, `oneshot_practice_*`) 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,12 +1,12 @@
 /**
  * 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_*`, `oneshot_meetings_*`) are generated from their routes and each tells the model to call this one first.
+ * `oneshot_procurement_*`, `oneshot_meetings_*`, `oneshot_matters_*`, `oneshot_field_service_*`, `oneshot_client_work_*`, `oneshot_portfolio_*`, `oneshot_practice_*`) 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 = {
     name: "oneshot_connections_list",
-    description: "List the agent's connections to business systems (accounting, CRM, shipping, tax, spend) and GitHub. " +
+    description: "List the agent's connections to business systems (accounting, CRM, shipping, tax, spend, practice management, wealth) and GitHub. " +
         "Returns each connection's id, name, kind, system, account_label and status (only an active one can be read). " +
         "Call it before any connected-system read: pick the connection by system and account_label and pass its id as connection_id. " +
         "Connections are added and revoked in the console. Free.",

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

@@ -287,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

package/dist/tools/linkedin.js

@@ -219,7 +219,7 @@ export async function handleLinkedinWithdrawInvitation(agent, args) {
 }
 export const linkedinMessageTool = {
     name: "oneshot_linkedin_message",
-    description: "Message a first-degree LinkedIn connection through a connected account that granted 'reply': into the 1:1 conversation the account already has with them, or a new one. Use it once an invitation is accepted, or for a connection the account has never messaged. Returns conversation_id. The human's account sends it; a message LinkedIn accepted cannot be recalled. Shares the reply daily cap (default 50); sends are paced. A failed send with not_connected (invite them first) or rate_limited means defer, not give up. An Idempotency-Key is generated automatically so a retry never double-sends. Paid tool.",
+    description: "Message a first-degree LinkedIn connection through a connected account that granted 'reply': into the 1:1 conversation the account already has with them, or a new one. Use it once an invitation is accepted, or for a connection the account has never messaged. Returns conversation_id. The human's account sends it; a message LinkedIn accepted cannot be recalled. Shares the reply daily cap (default 50); sends are paced. A failed send with recipient_not_connected means invite them first, not give up. An Idempotency-Key is generated automatically so a retry never double-sends. Paid tool.",
     inputSchema: {
         type: "object",
         properties: {