@oneshot-agent/mcp-server 0.43.0 → 0.45.0

package/README.md

@@ -1,61 +1,40 @@
 # @oneshot-agent/mcp-server
 
-MCP (Model Context Protocol) server for [OneShot](https://oneshotagent.com). It gives any MCP client (Claude Desktop, Cursor, Claude Code) OneShot's tools: email, calls, SMS, research, enrichment, commerce, website builds. Paid calls are charged one at a time and show up in your receipts. An optional daily budget caps the spend.
+Your agent can think. This lets it act from Claude Desktop, Cursor or Claude
+Code: send email, make calls, research, buy, build sites. It pays per call,
+gets a signed receipt, and spends nothing you did not allow.
 
-Quick start:
-
-1. Install the server (below).
-2. Add it to your client's MCP config with CDP credentials ([Configuration](#configuration)).
-3. Send USDC on Base to the agent's wallet ([Funding Your Agent](#funding-your-agent)).
-
-## Installation
+## Install
 
 ```bash
 npm install -g @oneshot-agent/mcp-server
 ```
 
-## Configuration
-
-Pick one of three auth methods: **CDP Wallet** (recommended, no private keys in config), a raw private key, or an **access token** (credits-only session with no key; see Remote below).
-
-### Environment Variables
+Or skip the install and let your client run `npx -y @oneshot-agent/mcp-server`.
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CDP_API_KEY_ID` | Option A | Coinbase CDP API key ID |
-| `CDP_API_KEY_SECRET` | Option A | Coinbase CDP API key secret |
-| `CDP_WALLET_SECRET` | Option A | Coinbase CDP wallet secret |
-| `ONESHOT_WALLET_PRIVATE_KEY` | Option B | Raw private key for signing payments |
-| `ONESHOT_ACCESS_TOKEN` | Option C | Agent access token (`oneshot_…`): credits-only session, cannot be combined with `ONESHOT_BUDGET_*` |
-| `ONESHOT_BUDGET_DAILY` | No | Max USDC the agent may spend per UTC day (spend budget, enforced server-side) |
-| `ONESHOT_BUDGET_PER_TRANSACTION` | No | Max USDC for any single call |
-| `ONESHOT_BUDGET_ALERT_AT` | No | Fraction of the daily budget that triggers a warning (default 0.8) |
-| `ONESHOT_BUDGET_PAUSE_AT` | No | Fraction at which paid calls stop (default 1.0) |
-| `ONESHOT_BUDGET_ALERT_EMAIL` | No | Email for budget alerts |
+## Start
 
-### Claude Desktop
+Pick one way to pay. Set its env vars in your client's config, below.
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "oneshot": {
-      "command": "npx",
-      "args": ["-y", "@oneshot-agent/mcp-server"],
-      "env": {
-        "CDP_API_KEY_ID": "your-api-key-id",
-        "CDP_API_KEY_SECRET": "your-api-key-secret",
-        "CDP_WALLET_SECRET": "your-wallet-secret"
-      }
-    }
-  }
-}
-```
+| Variable | Use | What it is |
+|----------|-----|------------|
+| `CDP_API_KEY_ID` | A (recommended) | CDP API key ID. No private key in your config. |
+| `CDP_API_KEY_SECRET` | A | CDP API key secret |
+| `CDP_WALLET_SECRET` | A | CDP wallet secret |
+| `ONESHOT_WALLET_PRIVATE_KEY` | B | Raw private key that signs payments |
+| `ONESHOT_ACCESS_TOKEN` | C | Access token (`oneshot_…`). Credits only, no key. |
+| `ONESHOT_BUDGET_DAILY` | optional | Max USDC per UTC day |
+| `ONESHOT_BUDGET_PER_TRANSACTION` | optional | Max USDC for one call |
+| `ONESHOT_BUDGET_ALERT_AT` | optional | Fraction of the daily budget that warns (default 0.8) |
+| `ONESHOT_BUDGET_PAUSE_AT` | optional | Fraction at which paid calls stop (default 1.0) |
+| `ONESHOT_BUDGET_ALERT_EMAIL` | optional | Where budget alerts go |
 
-### Cursor
+Set more than one and the token wins, then CDP, then the raw key.
+Get CDP credentials [here](https://docs.cdp.coinbase.com/agentic-wallet/welcome).
 
-Add to `.cursor/mcp.json` in your project:
+One block, three places:
+Claude Desktop reads `~/Library/Application Support/Claude/claude_desktop_config.json`,
+Cursor reads `.cursor/mcp.json` in your project, Claude Code reads user-scoped servers from `~/.claude.json`.
 
 ```json
 {
@@ -73,38 +52,9 @@ Add to `.cursor/mcp.json` in your project:
 }
 ```
 
-### Claude Code
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "oneshot": {
-      "command": "npx",
-      "args": ["-y", "@oneshot-agent/mcp-server"],
-      "env": {
-        "CDP_API_KEY_ID": "your-api-key-id",
-        "CDP_API_KEY_SECRET": "your-api-key-secret",
-        "CDP_WALLET_SECRET": "your-wallet-secret"
-      }
-    }
-  }
-}
-```
-
-Get CDP credentials at [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/welcome), or use `ONESHOT_WALLET_PRIVATE_KEY` instead of the CDP env vars for raw key auth.
-
-### Read authentication
-
-Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return private, per-agent data. The server wraps the OneShot TypeScript SDK, which signs a short-lived **EIP-712 read proof** (`x-agent-proof`) on each read so the API can verify you control the `X-Agent-ID` wallet. This needs no configuration; it ships in `@oneshot-agent/sdk >= 0.25.0` (the bundled dependency). The API enforces this proof by default — a request with no proof (or a mismatched one) and no valid access token is rejected.
-
-## Remote (hosted)
-
-Clients that run in someone else's cloud (Grok Bot, hosted runners) cannot spawn this
-server and must not hold a wallet key. For them, OneShot hosts the same tool registry over
-Streamable HTTP at **`https://win.oneshotagent.com/mcp`**, authenticated with an
-**agent access token** and billed to the agent's credit balance:
+**Hosted.** A client in someone else's cloud cannot run this server and must not
+hold a wallet key. Point it at `https://win.oneshotagent.com/mcp` with an access
+token. Same tools, billed to the agent's credits.
 
 ```json
 {
@@ -117,261 +67,70 @@ Streamable HTTP at **`https://win.oneshotagent.com/mcp`**, authenticated with an
 }
 ```
 
-Mint a token from a wallet session with `agent.createAccessToken()` (`@oneshot-agent/sdk`
-≥ 0.33.0). Setup and billing details: https://docs.oneshotagent.com/sdk/remote-mcp
-
-The same token also works with this local server (≥ 0.20.0): set `ONESHOT_ACCESS_TOKEN`
-instead of the wallet variables for a credits-only session on your own machine.
-
-## Available Tools
-
-### Soul Hunt
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_hunt_list` | List active or collected Soul Hunts. Free. |
-| `oneshot_hunt_status` | Detailed status, rounds and timeline for a specific hunt. Free. |
-| `oneshot_hunt_predict` | Submit a prediction for a hunt. Debits a stake from your balance. Paid, and requires a wallet session — Soul Hunt enforces a wallet-signed write proof that an access-token/OAuth session cannot produce. |
-| `oneshot_hunt_collection` | View the souls you have captured. Free. |
-| `oneshot_hunt_leaderboard` | Public predictor leaderboard. Free. |
-
-Soul Hunt is a separate service (`api.soulhunt.ai`) from the main OneShot API; the wallet session's `X-Agent-ID`/`x-agent-proof` carry over, but the OneShot bearer token never does.
-
-### Communication
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_email` | Send emails with attachments |
-| `oneshot_voice` | Make phone calls |
-| `oneshot_sms` | Send SMS messages |
-
-### Inbox
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_inbox_list` | List received emails |
-| `oneshot_inbox_get` | Get a specific email |
-| `oneshot_sms_inbox_list` | List received SMS messages |
-| `oneshot_sms_inbox_get` | Get a specific SMS message |
-
-### Inbound voice
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_voice_number_provision` | Get the agent a phone number (existing one free; new one charges the registration fee from credits) |
-| `oneshot_voice_numbers` | List the agent's phone numbers |
-| `oneshot_voice_inbound_set` | Make a number answer its own calls (wallet session only) |
-| `oneshot_voice_inbound_disable` | Stop answering calls to a number (wallet session only) |
-| `oneshot_voice_inbound_calls` | List inbound calls, or one call with transcript |
-
-### Research & Enrichment
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_research` | Deep web research with sources |
-| `oneshot_solve` | Plan vehicle routes with constraint checks and conflicts |
-| `oneshot_person_find` | Search for people by title, company, etc. |
-| `oneshot_person_profile` | Enrich person profile from LinkedIn URL, email, or name + company |
-| `oneshot_person_email` | Find someone's email address |
-| `oneshot_person_email_status` | Verify email deliverability |
-| `oneshot_company_find` | Search for companies by industry, size, location, etc. |
-| `oneshot_company_profile` | Enrich a company from domain, name, LinkedIn, or ticker |
-| `oneshot_business_find` | Discover local businesses (restaurants, contractors, practices) by category × location |
-| `oneshot_business_resolve` | Business name + address → website domain, phone, status, confidence |
-| `oneshot_record_solicitations_find` | Federal Sources Sought / Presolicitation notices by NAICS with the contracting officer's contact |
-
-### Person Intelligence
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_person_dossier` | A person’s profile, known social accounts, articles, posts and written summary |
-| `oneshot_person_social_accounts` | Find all social accounts for a person |
-| `oneshot_person_articles` | Find articles about a person |
-| `oneshot_person_posts` | Recent social posts with engagement |
-| `oneshot_person_interests` | Analyze interests across categories |
-| `oneshot_person_followers` | Map followers, following, replies |
-
-### Web
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_web_search` | Search the web |
-| `oneshot_web_read` | Read any URL as markdown + screenshot |
-| `oneshot_browser` | Autonomous browser: navigate, click, extract |
-
-### Commerce
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_product_find` | Search for products |
-| `oneshot_commerce_buy` | Purchase products |
-
-### Physical Mail
-
-Quote-to-pay with an explicit approval in between. Prices are on the [Pricing](https://docs.oneshotagent.com/pricing) page; the quote carries the price of each piece.
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_physical_mail_upload` | Upload print-ready artwork (PDF, PNG or JPEG as base64, 20 MB max) and get its asset id |
-| `oneshot_physical_mail_validate_address` | Check that a U.S. address is deliverable |
-| `oneshot_physical_mail_preview` | Quote a letter or postcard and render an uncharged proof |
-| `oneshot_physical_mail_quote` | Read a quote |
-| `oneshot_physical_mail_approve` | Approve the exact piece and price of a quote |
-| `oneshot_physical_mail_send` | Print and post an approved piece (quote id, approval id and an idempotency key you keep) |
-| `oneshot_physical_mail_recover` | Find the order a send created, by its idempotency key |
-| `oneshot_physical_mail_order` | Read an order and its status |
-| `oneshot_physical_mail_cancel` | Ask to cancel an order (not guaranteed once submitted) |
-
-### Build
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_build` | Build and deploy production websites |
-| `oneshot_update_build` | Update an existing website |
-
-### Compute Orchestration
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_compute` | Create an autonomous goal (objective + budget); OneShot plans and runs the steps |
-| `oneshot_compute_status` | Get a compute goal's status and budget |
-| `oneshot_compute_tasks` | List tasks planned/executed under a goal |
-| `oneshot_compute_cancel` | Cancel a goal and refund remaining budget |
-| `oneshot_compute_respond` | Respond to a human-in-the-loop task |
-| `oneshot_compute_pause` | Pause a recurring goal; plan and progress are kept |
-| `oneshot_compute_resume` | Resume a paused recurring goal |
-| `oneshot_compute_fund` | Top up a recurring goal's USDC budget |
-
-### Domains
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_list_domains` | List sending domains with warmup/limits |
-| `oneshot_pause_domain` | Pause a sending domain |
-| `oneshot_resume_domain` | Resume a paused sending domain |
-
-### Analytics
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_spend_breakdown` | Spend by tool/category over a period |
-| `oneshot_return_on_spend` | Return on spend: cost vs. value produced |
-| `oneshot_receipts_list` | List spend receipts |
-| `oneshot_tag_receipt_value` | Tag a receipt with the value it generated |
-
-### Account
-
-| Tool | Description |
-|------|-------------|
-| `oneshot_notifications` | List agent notifications |
-| `oneshot_mark_notification_read` | Mark notification as read |
-| `oneshot_get_balance` | Get USDC wallet balance |
-| `oneshot_budget_status` | Today's spend vs the configured budget (read-only) |
-
-Paid tools are priced in USDC via the x402 protocol. Current rates are on the [Pricing](https://docs.oneshotagent.com/pricing) page.
-
-## Tool Examples
-
-### Send an Email
-
-```
-Use oneshot_email:
-- to: "user@example.com"
-- subject: "Hello from AI"
-- body: "<h1>Hello!</h1><p>This email was sent by an AI agent.</p>"
-- from_name: "Jane Doe"      (optional display name → "Jane Doe <jane@domain>")
-- from_mailbox: "jane"       (optional local-part, defaults to "agent"; requires from_domain)
-- from_domain: "acme.com"    (optional, must be a domain you own; omit both from_domain and
-                              from_mailbox to rotate across your warmed domains)
-- mailbox_mode: "mailbox"    (optional, 'relay' (default) | 'mailbox' — dedicated per-address
-                              mailbox; only when first provisioning a new from_domain)
-```
-
-### Make a Phone Call
-
-```
-Use oneshot_voice:
-- target_number: "+14155551234"
-- objective: "Call the restaurant and make a reservation for 2 people at 7pm tonight"
-- caller_persona: "A polite assistant calling on behalf of John"
-```
-
-### Send an SMS
-
-```
-Use oneshot_sms:
-- to_number: "+14155551234"
-- message: "Your order has shipped! Track it at: https://example.com/track/123"
-```
-
-### Research a Topic
-
-```
-Use oneshot_research:
-- topic: "What are the latest developments in quantum computing?"
-- depth: "deep"
-```
-
-### Search for People
-
-```
-Use oneshot_person_find:
-- job_titles: ["CTO", "VP Engineering"]
-- companies: ["Stripe", "Square"]
-- location: ["San Francisco"]
-- limit: 10
-```
-
-### Find Someone's Email
-
-```
-Use oneshot_person_email:
-- name: "John Smith"
-- company: "Example" (a name or a domain)
-```
-
-### Check Wallet Balance
-
-```
-Use oneshot_get_balance (no parameters needed)
-```
-
-### Build a Website
-
-```
-Use oneshot_build:
-- type: "saas"
-- product:
-    name: "Acme Analytics"
-    description: "Real-time analytics dashboard for modern teams. Track metrics, visualize data, and make better decisions."
-    industry: "Software"
-- lead_capture:
-    enabled: true
-- brand:
-    primary_color: "#4F46E5"
-    tone: "professional"
-```
-
-### Read Inbox
-
-```
-Use oneshot_inbox_list:
-- limit: 10
-- include_body: true
-```
-
-## Funding Your Agent
-
-Send USDC to your agent's wallet address on Base. The server runs on Base Mainnet (chain 8453).
-
-## LinkedIn connection recovery
-
-If the active account list is empty or an account is `connection_deleted` or
-`revoked`, ask the human to use `oneshot_linkedin_connect` and authorize fresh
-grants. An existing account with `reconnect_required` must be reconnected through
-the owning application. Reconnect and revoke are deliberately not agent tools.
-Do not create a new connection automatically after authentication failures or
-timeouts.
+Mint the token from a wallet session with `agent.createAccessToken()` in
+`@oneshot-agent/sdk`. [Setup and billing](https://docs.oneshotagent.com/sdk/remote-mcp).
+
+## What it does
+
+Every tool is named `oneshot_<name>`. Below are the names.
+
+| Area | Tools |
+|------|-------|
+| [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` |
+| [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` |
+| [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` |
+| [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` |
+
+## Money
+
+- It pays in USDC on Base mainnet (chain 8453). Send USDC to the agent's wallet first.
+- A paid call costs what the quote says, or it does not run. [Prices](https://docs.oneshotagent.com/pricing).
+- Budgets live on the server. You set them in env vars; the model cannot.
+  `budget_status` only reads them.
+- A budget value that does not parse stops the server at startup. It never runs unguarded.
+- An access token spends prepaid credits only. It never signs a payment, and it
+  cannot be combined with `ONESHOT_BUDGET_*`: the server refuses to start.
+
+## Trust
+
+Every paid call returns a signed receipt. Reads of private data (inbox, SMS inbox,
+notifications, balance, browser profiles) carry a signed proof that you hold the
+wallet. The server signs it for you. A read with no proof and no valid token is refused.
+
+## 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).
+- **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.
+  A failed job is refunded. Numbers the source already has come back without it.
+  [Price](https://docs.oneshotagent.com/pricing).
+- **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.
+- **LinkedIn.** No active account, or one that is `connection_deleted` or `revoked`:
+  ask the human to run `linkedin_connect` and grant again. `reconnect_required`
+  is fixed by the owning application. Reconnect and revoke are not agent tools.
+  Never open a new connection on your own after an auth failure or a timeout.
+- **Predict.** Pass `model: "simulation"` with a `simulation` block, or
+  `model: "forecast"` with a `forecast` block. You get ranges and consistency
+  checks back. [Inputs and limits](https://docs.oneshotagent.com/api-reference/predict).
+- **Wallet session only.** `voice_inbound_set`, `voice_inbound_disable` and
+  `hunt_predict`, which stakes from your balance. Soul Hunt is a separate
+  service: your wallet proof carries over, your access token never does.
 
 ## Links
 
@@ -382,12 +141,16 @@ timeouts.
 - [Python SDK (Core)](https://pypi.org/project/oneshot-python/)
 - [GitHub](https://github.com/oneshot-agent/sdk)
 
-## Optional phone lookup
-
-`person_find`, `person_profile`, and `person_dossier` accept `include_phone`, off by default. It adds the per-person add-on listed on the pricing page × the requested search limit (default 100) for a search, or once for profile/dossier, for up to that many people with no promised hit. Existing source numbers and published business or record numbers remain available without opting in. Fallbacks and callbacks cost nothing extra; a completed no-match is charged and a failed job is refunded. Use a boolean `true` / `false`. The full quote is checked before payment.
+## Tool discovery
 
-## Predict
+The MCP catalog contains 172 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.
+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.
 
-Use `oneshot_predict` with the matching model block. Supports `model: "simulation"` with a `simulation` block of named distributions and arithmetic outputs, or `model: "forecast"` with a `forecast` block containing a time series and horizon. Returns uncertainty ranges and consistency checks.
+## License
 
-See [Predict](https://docs.oneshotagent.com/api-reference/predict) for inputs, results and limits.
+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.43.0", // keep in sync with package.json; guarded by version.test.ts
+        version: "0.45.0", // keep in sync with package.json; guarded by version.test.ts
     }, {
         capabilities: {
             tools: {},

package/dist/tools/annotations.js

@@ -3,10 +3,13 @@ import { LOOKUP_MANIFEST, ROUTE_MANIFEST } from "./lookup-manifest.generated.js"
 const read = (title, openWorld) => ({ title, readOnlyHint: true, destructiveHint: false, openWorldHint: openWorld });
 /** Changes something. `destructive` only for delete / overwrite / revoke. */
 const write = (title, openWorld, destructive = false) => ({ title, readOnlyHint: false, destructiveHint: destructive, openWorldHint: openWorld });
+/** 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 OPEN = true;
 const OWN = false;
 const DESTRUCTIVE = true;
 export const TOOL_ANNOTATIONS = {
+    oneshot_discover_tools: read("Discover tools", OWN),
     oneshot_solve: read("Solve", OWN),
     oneshot_predict: read("Predict", OWN),
     oneshot_hunt_list: read("List Soul Hunts", OPEN),
@@ -94,12 +97,15 @@ export const TOOL_ANNOTATIONS = {
     oneshot_approval_list: read("List approvals", OWN),
     oneshot_approval_cancel: write("Cancel an approval", OWN, DESTRUCTIVE),
     oneshot_action_policy: read("Show approval rules", OWN),
+    // Connected systems (#2403): the list is hand-written; the reads come from the route manifest below.
+    oneshot_connections_list: read("List connections", OWN),
     // The lookup tools come from the generated manifest: paid retrieval over public or third-party data (#1445).
     ...Object.fromEntries(LOOKUP_MANIFEST.map((entry) => [`oneshot_${entry.name}`, read(entry.title, OPEN)])),
     // The declared routes come from the same manifest (#1580). A read of the agent's own data is closed-world; a paid
-    // read (Changes, Benchmark) reaches recorded third-party data; a write changes something, and a DELETE removes it.
+    // 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;
+        const own = !entry.paid || CONNECTED_SYSTEM_READ.test(entry.path);
         return [
             `oneshot_${entry.name}`,
             entry.readOnly ? read(entry.title, own ? OWN : OPEN) : write(entry.title, own ? OWN : OPEN, entry.method === "DELETE"),

package/dist/tools/connections.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+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.
+ * Connecting and revoking stay in the console.
+ */
+export declare const connectionsListTool: Tool;
+/** The route's answer as it is: `{ connections: [...] }`. Through `route()`, which the published SDK range already has. */
+export declare function handleConnectionsList(agent: OneShot, _args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/connections.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ * 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. " +
+        "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.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+/** The route's answer as it is: `{ connections: [...] }`. Through `route()`, which the published SDK range already has. */
+export async function handleConnectionsList(agent, _args) {
+    return agent.route("GET", "/v1/connections");
+}

package/dist/tools/discover.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { OneShot } from '@oneshot-agent/sdk';
+export declare const discoverToolsTool: Tool;
+export declare function handleDiscoverTools(agent: OneShot, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/discover.js

@@ -0,0 +1,20 @@
+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.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Task or tool name to search for.' },
+            category: { type: 'string', description: 'Category ID from the directory.' },
+            cursor: { type: 'string', description: 'Opaque nextCursor from a category page.' },
+        },
+        additionalProperties: false,
+    },
+};
+export async function handleDiscoverTools(agent, args) {
+    if (Object.entries(args).some(([key, value]) => !['query', 'category', 'cursor'].includes(key) || typeof value !== 'string')) {
+        throw new Error('Expected optional query, category and cursor strings.');
+    }
+    // route() is available in the published SDK too; discoverTools() wraps this same free request.
+    return agent.route('GET', '/v1/tools/discover', { query: args, paid: false });
+}

package/dist/tools/email.js

@@ -1,13 +1,13 @@
 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). Paid tool — quote provided before payment.\n\n" +
+    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.",
     inputSchema: {
         type: "object",
         properties: {
             to: {
                 type: "string",
-                description: "Recipient email address (or comma-separated list). Optional when reply_to_email_id is set — defaults to the inbound sender.",
+                description: "Recipient email address (or comma-separated list). Optional when reply_to_email_id is set — defaults to the other party.",
             },
             subject: {
                 type: "string",
@@ -15,7 +15,7 @@ export const emailTool = {
             },
             reply_to_email_id: {
                 type: "string",
-                description: "Reply within a thread: id of an inbound email (from oneshot_inbox_list/oneshot_inbox_get). Sets In-Reply-To/References headers so mail clients group the conversation.",
+                description: "Reply within a thread: id of an inbound email (from oneshot_inbox_list/oneshot_inbox_get), or one this agent sent. Sets In-Reply-To/References headers so mail clients group the conversation.",
             },
             body: {
                 type: "string",