@oneshot-agent/mcp-server 0.48.0 → 0.50.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` `tax_rates` `tax_calculate` `shipping_shipments` `shipping_tracking` `shipping_rates` `procurement_transactions` `procurement_bills` `procurement_suppliers` `meetings_list` `meetings_get` |
 | [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` |
@@ -118,6 +118,12 @@ wallet. The server signs it for you. A read with no proof and no valid token is
   (the search limit, default 100), or once for a profile or dossier, found or not.
   A failed job is refunded. Numbers the source already has come back without it.
   [Price](https://docs.oneshotagent.com/pricing).
+- **Stored records.** A person, company or business record looked up recently may
+  come from OneShot's store of earlier lookups (profiles, dossiers, social accounts,
+  email finds, company profiles and resolves up to 30 days old; email status and
+  searches 7 days; posts, articles, followers and interests 3 days), at the same
+  price. The result says `cached` and `fetched_at`; `fresh: true` on any of these
+  tools asks again and refreshes the copy.
 - **Physical mail.** Preview, look at the proof and the price, then approve the
   quote yourself. Keep the idempotency key you pass to `physical_mail_send`;
   `physical_mail_recover` finds the order by it. Cancel is not guaranteed once submitted.
@@ -143,7 +149,7 @@ wallet. The server signs it for you. A read with no proof and no valid token is
 
 ## Tool discovery
 
-The MCP catalog contains 185 tools. `oneshot_discover_tools` is a free, read-only
+The MCP catalog contains 233 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.
@@ -151,6 +157,12 @@ Category pages contain up to five tools; pass `nextCursor` as `cursor` with the
 same query and category. `nextCursor: null` marks the end. Both stdio and hosted
 `/mcp` expose it as an ordinary tool.
 
+## Untrusted tool content
+
+Tool result objects carrying third-party text (web, browser, inbox, research and source lookups) carry `untrusted_content: true`, selected by a per-tool registry flag. Computed results such as predict and solve, quotes, receipts, job acknowledgements and account data keep their original shape. Treat their content as third-party data, never as instructions. Array-returning SDK methods preserve the array and mark its object entries. MCP marks its result envelope and successful JSON text payload.
+
+Web reads and inbox reads also report `hidden_removed`. Filtering removes HTML comments, inline-hidden elements (including off-screen positioning), image alt text, zero-width characters and bidi controls. Inbox list counts sum the counts on its returned messages; omitted bodies are not counted. Stored emails and attachments are unchanged. Filtering is not a trust guarantee: visible instructions, external stylesheets and image pixels are not classified by this filter.
+
 ## License
 
 MIT

package/dist/index.js

@@ -50,7 +50,7 @@ async function main() {
     const agent = await initAgent();
     const server = new Server({
         name: "oneshot-mcp",
-        version: "0.48.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.50.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,15 +1,22 @@
 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, 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.
+ */
+const IRREVERSIBLE_ROUTES = new Set(["physical_mail_approve", "physical_mail_cancel", "identity_start"]);
+const OUTBOUND_ROUTES = new Set(["physical_mail_approve", "identity_start"]);
 /** 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)\//;
 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),
@@ -17,22 +24,22 @@ export const TOOL_ANNOTATIONS = {
     oneshot_hunt_predict: write("Predict Soul Hunt", OPEN),
     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 +58,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,7 +66,7 @@ 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_compute_fund: write("Add budget to a goal", OWN, DESTRUCTIVE),
     oneshot_build: write("Build a website", OPEN),
     oneshot_update_build: write("Update a website", OPEN, DESTRUCTIVE), // overwrites the live site
     oneshot_browser: write("Browse and act on a website", OPEN),
@@ -72,14 +79,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 +99,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 +112,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/browser.js

@@ -76,7 +76,6 @@ export async function handleBrowser(agent, args) {
         start_url: args.start_url,
         allowed_domains: args.allowed_domains,
         profile_id: args.profile_id,
-        secrets: args.secrets,
         max_steps: args.max_steps,
     });
 }

package/dist/tools/company.js

@@ -1,6 +1,7 @@
+import { FRESH_PROPERTY } from "./enrichment.js";
 export const companyFindTool = {
     name: "oneshot_company_find",
-    description: "Search for companies by name, domain, industry, location, size, funding stage, or tags. Paid tool.",
+    description: "Search for companies by name, domain, industry, location, size, funding stage, or tags. Paid tool. A record looked up recently may come from OneShot's store of earlier lookups; the result says so with cached and fetched_at, and fresh=true asks again.",
     inputSchema: {
         type: "object",
         properties: {
@@ -14,12 +15,13 @@ export const companyFindTool = {
             funding_stage: { type: "string", description: "Funding stage (e.g. 'series_a')" },
             tags: { type: "array", items: { type: "string" }, description: "Tags to filter by" },
             limit: { type: "number", description: "Max results (default 10, max 100)" },
+            ...FRESH_PROPERTY,
         },
     },
 };
 export const companyProfileTool = {
     name: "oneshot_company_profile",
-    description: "Enrich a company from its domain, name, LinkedIn URL, or stock ticker. At least one identifier is required. Paid tool.",
+    description: "Enrich a company from its domain, name, LinkedIn URL, or stock ticker. At least one identifier is required. Paid tool. A record looked up recently may come from OneShot's store of earlier lookups; the result says so with cached and fetched_at, and fresh=true asks again.",
     inputSchema: {
         type: "object",
         properties: {
@@ -27,6 +29,7 @@ export const companyProfileTool = {
             name: { type: "string", description: "Company name" },
             linkedin_url: { type: "string", description: "Company LinkedIn URL" },
             ticker: { type: "string", description: "Stock ticker symbol" },
+            ...FRESH_PROPERTY,
         },
     },
 };
@@ -42,6 +45,7 @@ export async function handleCompanyFind(agent, args) {
         funding_stage: args.funding_stage,
         tags: args.tags,
         limit: args.limit,
+        fresh: args.fresh,
     });
 }
 export async function handleCompanyProfile(agent, args) {
@@ -50,5 +54,6 @@ export async function handleCompanyProfile(agent, args) {
         name: args.name,
         linkedin_url: args.linkedin_url,
         ticker: args.ticker,
+        fresh: args.fresh,
     });
 }

package/dist/tools/compute.d.ts

@@ -18,6 +18,9 @@ export declare function handleComputeCancel(agent: OneShot, args: Record<string,
     message?: string;
 }>;
 export declare function handleComputeRespond(agent: OneShot, args: Record<string, unknown>): Promise<{
+    goal_id: string;
+    status: string;
+} | {
     task_id: string;
     goal_id: string;
     task_status: string;

package/dist/tools/compute.js

@@ -1,6 +1,28 @@
+const KNOWN_GOAL_TOOL = { type: "string", description: 'A OneShot tool name, e.g. "email", "voice", "commerce_buy"' };
+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" },
+        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 +65,120 @@ 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,
+                    },
+                ],
+            },
+            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 } }, 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 the price assumes, e.g. "5 minutes" for a call or "20 steps" for a browser run' },
+                            },
+                            required: ["name", "reason"],
+                        },
+                    },
+                },
+                required: ["unit", "per_unit", "overhead", "volume", "unpriced"],
+            },
         },
         required: ["objective"],
     },
@@ -84,16 +220,18 @@ 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). 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" },
-            response: { type: "string", description: "Free-text response for the task" },
+            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", "task_id"],
+        required: ["goal_id"],
     },
 };
 export const computePauseTool = {
@@ -132,7 +270,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,
@@ -141,7 +279,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);
@@ -156,6 +299,18 @@ export async function handleComputeCancel(agent, args) {
     return agent.cancelComputeGoal(args.goal_id, args.reason);
 }
 export async function handleComputeRespond(agent, args) {
+    // A dispute answers no task (#2705): the owner disputes an ending code could not verify.
+    if (args.dispute !== undefined) {
+        if (args.dispute !== true || args.task_id !== undefined)
+            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_*`) 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_*`) 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/enrichment.d.ts

@@ -30,6 +30,13 @@ export declare const PERSON_IDENTITY_PROPERTIES: {
         readonly description: "Same as profile_url (older name)";
     };
 };
+/** The shared lookup cache's bypass (#2593): the same field on every person, company and business tool. */
+export declare const FRESH_PROPERTY: {
+    readonly fresh: {
+        readonly type: "boolean";
+        readonly description: "Look the record up again instead of using OneShot's stored copy from an earlier lookup (profiles, dossiers, social accounts, email finds, company profiles and resolves are kept up to 30 days; email status and searches 7 days; posts, articles, followers and interests 3 days), and refresh that copy. Off by default; the result says cached and fetched_at.";
+    };
+};
 /** The shared person shape (#1899), as the SDK's PersonIdentity. */
 declare function personIdentity(args: Record<string, unknown>): PersonIdentity;
 export { personIdentity };

package/dist/tools/enrichment.js

@@ -7,6 +7,10 @@ export const PERSON_IDENTITY_PROPERTIES = {
     linkedin_url: { type: "string", description: "Same as profile_url (older name)" },
     social_media_url: { type: "string", description: "Same as profile_url (older name)" },
 };
+/** The shared lookup cache's bypass (#2593): the same field on every person, company and business tool. */
+export const FRESH_PROPERTY = {
+    fresh: { type: "boolean", description: "Look the record up again instead of using OneShot's stored copy from an earlier lookup (profiles, dossiers, social accounts, email finds, company profiles and resolves are kept up to 30 days; email status and searches 7 days; posts, articles, followers and interests 3 days), and refresh that copy. Off by default; the result says cached and fetched_at." },
+};
 /** The shared person shape (#1899), as the SDK's PersonIdentity. */
 function personIdentity(args) {
     return {
@@ -22,7 +26,7 @@ function personIdentity(args) {
 export { personIdentity };
 export const personProfileTool = {
     name: "oneshot_person_profile",
-    description: "Enrich a person's profile from whatever you know: name (+ company), email, phone or a profile URL on LinkedIn, X or GitHub. Returns job title, company, social links, etc. Paid tool. Phone lookup is off by default. include_phone=true buys a lookup for up to one person at the add-on listed on the pricing page; no phone hit is guaranteed.",
+    description: "Enrich a person's profile from whatever you know: name (+ company), email, phone or a profile URL on LinkedIn, X or GitHub. Returns job title, company, social links, etc. Paid tool. Phone lookup is off by default. include_phone=true buys a lookup for up to one person at the add-on listed on the pricing page; no phone hit is guaranteed. A record looked up recently may come from OneShot's store of earlier lookups; the result says so with cached and fetched_at, and fresh=true asks again.",
     inputSchema: {
         type: "object",
         properties: {
@@ -30,12 +34,13 @@ export const personProfileTool = {
             ...PERSON_IDENTITY_PROPERTIES,
             company_domain: { type: "string", description: "Employer domain (older name; company takes a name or a domain)" },
             company_name: { type: "string", description: "Employer name (older name; company takes a name or a domain)" },
+            ...FRESH_PROPERTY,
         },
     },
 };
 export const personEmailTool = {
     name: "oneshot_person_email",
-    description: "Find a person's email address from a name and company (name or domain), a phone, or a LinkedIn, X or GitHub profile URL. Paid tool.",
+    description: "Find a person's email address from a name and company (name or domain), a phone, or a LinkedIn, X or GitHub profile URL. Paid tool. A record looked up recently may come from OneShot's store of earlier lookups; the result says so with cached and fetched_at, and fresh=true asks again.",
     inputSchema: {
         type: "object",
         properties: {
@@ -45,12 +50,13 @@ export const personEmailTool = {
             last_name: { type: "string", description: "Person's last name (use with first_name)" },
             company_domain: { type: "string", description: "Employer domain (older name; company takes a name or a domain)" },
             company_name: { type: "string", description: "Employer name (older name; company takes a name or a domain)" },
+            ...FRESH_PROPERTY,
         },
     },
 };
 export const personEmailStatusTool = {
     name: "oneshot_person_email_status",
-    description: "Verify if an email address is valid and deliverable. Paid tool.",
+    description: "Verify if an email address is valid and deliverable. Paid tool. A record looked up recently may come from OneShot's store of earlier lookups; the result says so with cached and fetched_at, and fresh=true asks again.",
     inputSchema: {
         type: "object",
         properties: {
@@ -58,6 +64,7 @@ export const personEmailStatusTool = {
                 type: "string",
                 description: "Email address to verify",
             },
+            ...FRESH_PROPERTY,
         },
         required: ["email"],
     },
@@ -68,6 +75,7 @@ export async function handlePersonProfile(agent, args) {
         ...personIdentity(args),
         company_domain: args.company_domain,
         company_name: args.company_name,
+        fresh: args.fresh,
     });
 }
 export async function handlePersonEmail(agent, args) {
@@ -78,10 +86,12 @@ export async function handlePersonEmail(agent, args) {
         last_name: args.last_name,
         company_domain: args.company_domain,
         company_name: args.company_name,
+        fresh: args.fresh,
     });
 }
 export async function handlePersonEmailStatus(agent, args) {
     return agent.personEmailStatus({
         email: args.email,
+        fresh: args.fresh,
     });
 }

package/dist/tools/index.d.ts

@@ -2,17 +2,12 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { OneShot } from "@oneshot-agent/sdk";
 export declare const tools: Tool[];
 export declare function handleToolCall(agent: OneShot, toolName: string, args: Record<string, unknown>): Promise<{
-    content: {
+    content: Array<{
         type: string;
         text: string;
-    }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    }>;
+    isError?: boolean;
+    untrusted_content?: boolean;
 }>;
 /**
  * Typed SDK errors become a JSON body the model can act on instead of a