@oneshot-agent/mcp-server 0.39.1 → 0.40.0

package/README.md

@@ -102,7 +102,7 @@ Read tools (inbox, SMS inbox, notifications, balance, browser profiles) return p
 ## 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 117 tools over
+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:
 
@@ -169,8 +169,9 @@ Soul Hunt is a separate service (`api.soulhunt.ai`) from the main OneShot API; t
 | 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/email |
+| `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. |
@@ -205,6 +206,22 @@ Soul Hunt is a separate service (`api.soulhunt.ai`) from the main OneShot API; t
 | `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 |

package/dist/index.js

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

package/dist/tools/annotations.js

@@ -7,6 +7,7 @@ const OPEN = true;
 const OWN = false;
 const DESTRUCTIVE = true;
 export const TOOL_ANNOTATIONS = {
+    oneshot_solve: read("Solve", 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),
@@ -24,6 +25,10 @@ export const TOOL_ANNOTATIONS = {
     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_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_research: read("Deep research", OPEN),
     oneshot_person_find: read("Find people", OPEN),
     oneshot_person_profile: read("Look up a person's profile", OPEN),

package/dist/tools/enrichment.js

@@ -21,6 +21,10 @@ export const personProfileTool = {
                 type: "string",
                 description: "Company domain for additional context",
             },
+            company_name: {
+                type: "string",
+                description: "Employer name, for a name lookup when the company domain is not known (e.g. Coinbase)",
+            },
         },
     },
 };
@@ -71,6 +75,7 @@ export async function handlePersonProfile(agent, args) {
         email: args.email,
         name: args.name,
         company_domain: args.company_domain,
+        company_name: args.company_name,
     });
 }
 export async function handlePersonEmail(agent, args) {

package/dist/tools/index.js

@@ -2,6 +2,7 @@ import { emailTool, handleEmail } from "./email.js";
 import { voiceTool, handleVoice } from "./voice.js";
 import { voiceNumberProvisionTool, voiceNumbersTool, voiceInboundSetTool, voiceInboundDisableTool, voiceInboundCallsTool, handleVoiceNumberProvision, handleVoiceNumbers, handleVoiceInboundSet, handleVoiceInboundDisable, handleVoiceInboundCalls, } from "./voice-inbound.js";
 import { smsTool, handleSms } from "./sms.js";
+import { solveTool, handleSolve } from "./solve.js";
 import { researchTool, handleResearch } from "./research.js";
 import { personFindTool, handlePersonFind } from "./people.js";
 import { productFindTool, commerceBuyTool, handleProductFind, handleCommerceBuy } from "./commerce.js";
@@ -25,6 +26,7 @@ import { listDomainsTool, pauseDomainTool, resumeDomainTool, handleListDomains,
 import { huntListTool, huntStatusTool, huntPredictTool, huntCollectionTool, huntLeaderboardTool, handleHuntList, handleHuntStatus, handleHuntPredict, handleHuntCollection, handleHuntLeaderboard } from "./hunt.js";
 import { TOOL_ANNOTATIONS } from "./annotations.js";
 import { lookupToolDefinitions, lookupHandlers, routeToolDefinitions, routeHandlers } from "./lookup.js";
+import { physicalMailSendTool, physicalMailUploadTool, handlePhysicalMailSend, handlePhysicalMailUpload } from "./physical-mail.js";
 import { spendBreakdownTool, rocsTool, rocsByGoalTool, receiptsListTool, tagReceiptValueTool, handleSpendBreakdown, handleRocs, handleRocsByGoal, handleReceiptsList, handleTagReceiptValue } from "./analytics.js";
 const toolDefinitions = [
     emailTool,
@@ -39,6 +41,9 @@ const toolDefinitions = [
     voiceInboundSetTool,
     voiceInboundDisableTool,
     voiceInboundCallsTool,
+    solveTool,
+    physicalMailUploadTool,
+    physicalMailSendTool,
     researchTool,
     personFindTool,
     personProfileTool,
@@ -129,6 +134,9 @@ const handlers = {
     "oneshot_voice_inbound_set": handleVoiceInboundSet,
     "oneshot_voice_inbound_disable": handleVoiceInboundDisable,
     "oneshot_voice_inbound_calls": handleVoiceInboundCalls,
+    "oneshot_solve": handleSolve,
+    "oneshot_physical_mail_upload": handlePhysicalMailUpload,
+    "oneshot_physical_mail_send": handlePhysicalMailSend,
     "oneshot_research": handleResearch,
     "oneshot_person_find": handlePersonFind,
     "oneshot_person_profile": handlePersonProfile,

package/dist/tools/lookup-manifest.generated.js

@@ -111,6 +111,29 @@ export const LOOKUP_MANIFEST = [
             "limit": 1
         }
     },
+    {
+        "name": "compound_properties",
+        "path": "lookup/compound-properties",
+        "title": "Compound Properties",
+        "description": "Give the computed molecular descriptors of a chemical compound by its compound identifier (CID) or its InChIKey: the IUPAC name, molecular formula, InChIKey, molecular weight in g/mol, exact mass in Da, XLogP, topological polar surface area in square angstroms, the counts of hydrogen bond donors and acceptors, rotatable bonds and heavy atoms, the formal charge and the complexity score, with a link to the compound page. These are values the source computes from the structure, not measurements. Use it to characterise a compound in a literature review, a screening library or a regulatory file. Give exactly one of `cid` and `inchikey`. `compound` is null when the source knows no compound with that identifier. Synonyms, depositor records, and any synthesis or preparation data are not returned.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "cid": {
+                    "type": "integer",
+                    "description": "The compound identifier (CID), for example 2244. From 1 to 999999999."
+                },
+                "inchikey": {
+                    "type": "string",
+                    "description": "The standard InChIKey of the compound, for example BSYNRYMUTXBXSQ-UHFFFAOYSA-N. Exactly 27 characters. An InChIKey is 14 capitals, a hyphen, 10 capitals, a hyphen and one capital."
+                }
+            },
+            "required": []
+        },
+        "example": {
+            "cid": 2244
+        }
+    },
     {
         "name": "compound_resolve",
         "path": "resolve/compound",
@@ -269,6 +292,42 @@ export const LOOKUP_MANIFEST = [
             "variant": "FWD"
         }
     },
+    {
+        "name": "product_device_clearances",
+        "path": "lookup/product-device-clearances",
+        "title": "Device Clearances",
+        "description": "Look up medical devices cleared by the US Food and Drug Administration through premarket notification (510(k)). Supply at least one clearance number, applicant, device name or product code. Names are matched as word phrases; multiple filters must all match. Returns the total matches and clearance records, newest decision first, with device classifications and decision and received dates. Contact names and street addresses are excluded. No match returns an empty list. The source refreshes weekly.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "k_number": {
+                    "type": "string",
+                    "description": "The clearance number, for example K253582"
+                },
+                "applicant": {
+                    "type": "string",
+                    "description": "The company that applied, matched as words. 2 to 100 characters."
+                },
+                "device_name": {
+                    "type": "string",
+                    "description": "The device name, matched as words. 2 to 100 characters."
+                },
+                "product_code": {
+                    "type": "string",
+                    "description": "The FDA product code"
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "The most clearance records to return. From 1 to 25. Defaults to `10`."
+                }
+            },
+            "required": []
+        },
+        "example": {
+            "applicant": "Apple Inc",
+            "limit": 2
+        }
+    },
     {
         "name": "place_disasters",
         "path": "lookup/place-disasters",
@@ -1357,6 +1416,48 @@ export const ROUTE_MANIFEST = [
             "profile_id": "prof_01HX"
         }
     },
+    {
+        "name": "physical_mail_approve",
+        "method": "POST",
+        "path": "/v1/tools/physical-mail/approve",
+        "paid": false,
+        "readOnly": false,
+        "title": "Approve a Mail Quote",
+        "description": "Approve the exact mailpiece and price of a quote. Repeat the input_hash and total_usdc the quote returned: a changed piece or price is refused. Nothing is charged yet. Returns approval_id, which oneshot_physical_mail_send needs with the quote_id.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "quote_id": {
+                    "type": "string",
+                    "description": "Quote id from oneshot_physical_mail_preview"
+                },
+                "input_hash": {
+                    "type": "string",
+                    "description": "input_hash the quote returned (64 hex characters)"
+                },
+                "total_usdc": {
+                    "type": "string",
+                    "description": "total_usdc the quote returned, as a decimal string"
+                },
+                "approved": {
+                    "type": "boolean",
+                    "description": "Must be true: an explicit approval of this piece at this price"
+                }
+            },
+            "required": [
+                "quote_id",
+                "input_hash",
+                "total_usdc",
+                "approved"
+            ]
+        },
+        "example": {
+            "quote_id": "00000000-0000-4000-8000-000000000000",
+            "input_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "total_usdc": "1.85",
+            "approved": true
+        }
+    },
     {
         "name": "benchmark",
         "method": "POST",
@@ -1467,6 +1568,30 @@ export const ROUTE_MANIFEST = [
             "state": "IL"
         }
     },
+    {
+        "name": "physical_mail_cancel",
+        "method": "POST",
+        "path": "/v1/tools/physical-mail/orders/{order_id}/cancel",
+        "paid": false,
+        "readOnly": false,
+        "title": "Cancel a Mail Order",
+        "description": "Ask to cancel a mail order. Accepted (202) as a request: cancellation is not guaranteed once the mail has been submitted for printing; read the order to see whether it was canceled and refunded. Free.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "order_id": {
+                    "type": "string",
+                    "description": "Order id from oneshot_physical_mail_send"
+                }
+            },
+            "required": [
+                "order_id"
+            ]
+        },
+        "example": {
+            "order_id": "00000000-0000-4000-8000-000000000000"
+        }
+    },
     {
         "name": "watch_update",
         "method": "PATCH",
@@ -1655,6 +1780,54 @@ export const ROUTE_MANIFEST = [
             "domain": "mail.example.com"
         }
     },
+    {
+        "name": "physical_mail_order",
+        "method": "GET",
+        "path": "/v1/tools/physical-mail/orders/{order_id}",
+        "paid": false,
+        "readOnly": true,
+        "title": "Get a Mail Order",
+        "description": "Read a mail order: order_status, payment_status, fulfillment_status, events, cancel_before and the signed receipt. Free. Delivery events are postal observations, never evidence the mail was read.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "order_id": {
+                    "type": "string",
+                    "description": "Order id from oneshot_physical_mail_send or oneshot_physical_mail_recover"
+                }
+            },
+            "required": [
+                "order_id"
+            ]
+        },
+        "example": {
+            "order_id": "00000000-0000-4000-8000-000000000000"
+        }
+    },
+    {
+        "name": "physical_mail_quote",
+        "method": "GET",
+        "path": "/v1/tools/physical-mail/quotes/{quote_id}",
+        "paid": false,
+        "readOnly": true,
+        "title": "Get a Mail Quote",
+        "description": "Read a quote from oneshot_physical_mail_preview: its status (rendering or ready), input_hash, total_usdc, proof url, expires_at and approval_id once approved. Free. Poll it while status is rendering.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "quote_id": {
+                    "type": "string",
+                    "description": "Quote id from oneshot_physical_mail_preview"
+                }
+            },
+            "required": [
+                "quote_id"
+            ]
+        },
+        "example": {
+            "quote_id": "00000000-0000-4000-8000-000000000000"
+        }
+    },
     {
         "name": "voice_inbound_get",
         "method": "GET",
@@ -1733,6 +1906,83 @@ export const ROUTE_MANIFEST = [
         },
         "example": {}
     },
+    {
+        "name": "physical_mail_preview",
+        "method": "POST",
+        "path": "/v1/tools/physical-mail/preview",
+        "paid": false,
+        "readOnly": false,
+        "title": "Preview and Quote a Mailpiece",
+        "description": "Quote a letter or postcard and render an uncharged test proof. Nothing is printed or charged. Returns quote_id, input_hash, total_usdc (the price of this piece; see Pricing), the proof url and expires_at. Upload the artwork first with oneshot_physical_mail_upload; its asset ids go in artwork.file (letter) or artwork.front and artwork.back (postcard). Next: oneshot_physical_mail_approve with the returned quote_id, input_hash and total_usdc.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "to": {
+                    "type": "object",
+                    "description": "Recipient address: { name, address_line1, address_line2?, address_city, address_state (two letters), address_zip (5 or 9 digits), address_country? (\"US\") }"
+                },
+                "from": {
+                    "type": "object",
+                    "description": "Return address, same shape as to"
+                },
+                "artwork": {
+                    "type": "object",
+                    "description": "Letter: { kind: \"letter\", file: <asset id of a PDF>, color?: boolean, double_sided?: boolean }. Postcard: { kind: \"postcard\", front: <asset id>, back: <asset id> }"
+                }
+            },
+            "required": [
+                "to",
+                "from",
+                "artwork"
+            ]
+        },
+        "example": {
+            "to": {
+                "name": "Jane Doe",
+                "address_line1": "185 Berry St",
+                "address_city": "San Francisco",
+                "address_state": "CA",
+                "address_zip": "94107"
+            },
+            "from": {
+                "name": "Acme Inc",
+                "address_line1": "1 Main St",
+                "address_city": "Austin",
+                "address_state": "TX",
+                "address_zip": "78701"
+            },
+            "artwork": {
+                "kind": "letter",
+                "file": "00000000-0000-4000-8000-000000000000",
+                "color": false,
+                "double_sided": false
+            }
+        }
+    },
+    {
+        "name": "physical_mail_recover",
+        "method": "GET",
+        "path": "/v1/tools/physical-mail/orders/recover",
+        "paid": false,
+        "readOnly": true,
+        "title": "Recover a Mail Order",
+        "description": "Find the order a send created, by the idempotency key given to oneshot_physical_mail_send. Use it after a timeout or lost response instead of sending again. Free. Answers 404 when no send with that key reached the API.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": "The idempotency key of the send (1-255 characters: letters, digits, _ . : -)"
+                }
+            },
+            "required": [
+                "key"
+            ]
+        },
+        "example": {
+            "key": "thank-you-2026-q3-jane-doe"
+        }
+    },
     {
         "name": "company_sanctions",
         "method": "POST",
@@ -1802,62 +2052,55 @@ export const ROUTE_MANIFEST = [
         }
     },
     {
-        "name": "solve",
+        "name": "physical_mail_validate_address",
         "method": "POST",
-        "path": "/v1/tools/solve",
-        "paid": true,
+        "path": "/v1/tools/physical-mail/validate-address",
+        "paid": false,
         "readOnly": true,
-        "title": "Solve",
-        "description": "Plan vehicle routes within capacity and time windows. Returns the best route found, constraint checks and conflicts.",
+        "title": "Validate a Mailing Address",
+        "description": "Check that a U.S. postal address is deliverable before quoting mail to it. Returns deliverable, a deliverability code and the standardised address. Free; changes nothing.",
         "inputSchema": {
             "type": "object",
             "properties": {
-                "problem": {
+                "name": {
                     "type": "string",
-                    "enum": [
-                        "routing"
-                    ]
+                    "description": "Recipient name (1-100 characters)"
                 },
-                "time_limit_s": {
-                    "type": "integer",
-                    "minimum": 1,
-                    "maximum": 300,
-                    "default": 30
+                "address_line1": {
+                    "type": "string",
+                    "description": "Street address (1-200 characters)"
                 },
-                "routing": {
-                    "type": "object",
-                    "description": "Vehicles, stops, objective and optional travel matrix."
+                "address_line2": {
+                    "type": "string",
+                    "description": "Apartment, suite or unit (optional)"
+                },
+                "address_city": {
+                    "type": "string"
+                },
+                "address_state": {
+                    "type": "string",
+                    "description": "Two-letter state code, e.g. CA"
+                },
+                "address_zip": {
+                    "type": "string",
+                    "description": "ZIP code, 5 digits or ZIP+4"
                 }
             },
             "required": [
-                "problem",
-                "routing"
+                "name",
+                "address_line1",
+                "address_city",
+                "address_state",
+                "address_zip"
             ]
         },
         "example": {
-            "problem": "routing",
-            "routing": {
-                "objective": "distance",
-                "vehicles": [
-                    {
-                        "id": "van",
-                        "capacity": 10,
-                        "start": {
-                            "lat": 48,
-                            "lng": 16
-                        }
-                    }
-                ],
-                "stops": [
-                    {
-                        "id": "stop",
-                        "location": {
-                            "lat": 48.01,
-                            "lng": 16.01
-                        }
-                    }
-                ]
-            }
+            "name": "Jane Doe",
+            "address_line1": "185 Berry St",
+            "address_line2": "Suite 6100",
+            "address_city": "San Francisco",
+            "address_state": "CA",
+            "address_zip": "94107"
         }
     },
     {

package/dist/tools/physical-mail.d.ts

@@ -0,0 +1,34 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { OneShot } from "@oneshot-agent/sdk";
+/**
+ * The two Physical Mail steps that a generated route tool cannot carry (#1883): the send,
+ * which needs an idempotency key header beside the quote id and the approval id, and the
+ * artwork upload, whose body is a raw PDF, PNG or JPEG. Both go through the SDK's
+ * `physicalMail` (libs/agent-sdk/src/physical-mail.ts). The other seven routes (validate,
+ * preview, quote, approve, recover, order, cancel) are generated from the declaration.
+ */
+/** The route's own limit (`uploadArtwork` in services/physical-mail/service.ts): 20 MB. */
+export declare const PHYSICAL_MAIL_ASSET_LIMIT_BYTES: number;
+export declare const PHYSICAL_MAIL_ASSET_TYPES: readonly ["application/pdf", "image/png", "image/jpeg"];
+type AssetType = (typeof PHYSICAL_MAIL_ASSET_TYPES)[number];
+export declare const physicalMailSendTool: Tool;
+export declare function handlePhysicalMailSend(agent: OneShot, args: Record<string, unknown>): Promise<import("@oneshot-agent/sdk").MailOrder>;
+export declare const physicalMailUploadTool: Tool;
+/** Decodes the base64 `content`, refusing anything that is not base64 or that would exceed the route's limit before any bytes are sent. */
+export declare function decodeArtwork(args: Record<string, unknown>): {
+    data: Uint8Array;
+    mime: AssetType;
+};
+/**
+ * The decoded size of structurally valid base64 (standard or URL-safe alphabet, padding optional), or null.
+ * `Buffer.from(text, "base64")` tolerates a length one past a quartet, missing, short and excess padding
+ * (`AAAAA`, `AAA==`, `AAAA==`), so counting characters and subtracting the `=`s would undercount such
+ * input; the bound has to come from a shape the decoder cannot read differently.
+ */
+export declare function base64Size(text: string): number | null;
+export declare function handlePhysicalMailUpload(agent: OneShot, args: Record<string, unknown>): Promise<{
+    asset_id: string;
+    content_hash: string;
+    mime_type: string;
+}>;
+export {};

package/dist/tools/physical-mail.js

@@ -0,0 +1,105 @@
+/**
+ * The two Physical Mail steps that a generated route tool cannot carry (#1883): the send,
+ * which needs an idempotency key header beside the quote id and the approval id, and the
+ * artwork upload, whose body is a raw PDF, PNG or JPEG. Both go through the SDK's
+ * `physicalMail` (libs/agent-sdk/src/physical-mail.ts). The other seven routes (validate,
+ * preview, quote, approve, recover, order, cancel) are generated from the declaration.
+ */
+/** The route's own limit (`uploadArtwork` in services/physical-mail/service.ts): 20 MB. */
+export const PHYSICAL_MAIL_ASSET_LIMIT_BYTES = 20 * 1024 * 1024;
+export const PHYSICAL_MAIL_ASSET_TYPES = ["application/pdf", "image/png", "image/jpeg"];
+export const physicalMailSendTool = {
+    name: "oneshot_physical_mail_send",
+    description: "Print and post an approved mailpiece. Paid: the quote's total_usdc is charged (see Pricing), and the receipt is on the order. " +
+        "Needs the quote_id from oneshot_physical_mail_preview and the approval_id from oneshot_physical_mail_approve. " +
+        "Give an idempotency_key you keep: a retry with the same key returns the same order instead of sending twice, and " +
+        "oneshot_physical_mail_recover finds the order by it after a timeout. Returns the order (order_id, order_status, " +
+        "payment_status, receipt_id). Delivery is a postal observation, never evidence the mail was read.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            quote_id: { type: "string", description: "Quote id from oneshot_physical_mail_preview" },
+            approval_id: { type: "string", description: "Approval id from oneshot_physical_mail_approve (the quote's own approval)" },
+            idempotency_key: {
+                type: "string",
+                description: "A key you persist for this send (1-255 characters: letters, digits, _ . : -). Reuse it to retry safely.",
+            },
+            memo: { type: "string", description: "Why this mail is being sent (audit trail, max 1000 characters; optional)" },
+            max_cost: { type: "number", description: "Refuse to pay more than this many USDC (optional)" },
+            policy_approval_id: {
+                type: "string",
+                description: "Only when retrying a send the action policy held: the approval_id from the approval_required error, once a human approved it. Not the quote's approval_id.",
+            },
+        },
+        required: ["quote_id", "approval_id", "idempotency_key"],
+    },
+};
+export async function handlePhysicalMailSend(agent, args) {
+    return agent.physicalMail.send({
+        quote_id: args.quote_id,
+        approval_id: args.approval_id,
+        idempotencyKey: args.idempotency_key,
+        memo: args.memo,
+        maxCost: args.max_cost,
+        approvalId: args.policy_approval_id,
+    });
+}
+export const physicalMailUploadTool = {
+    name: "oneshot_physical_mail_upload",
+    description: "Upload print-ready artwork for a letter or postcard and get the asset id that oneshot_physical_mail_preview takes in " +
+        "artwork.file (a letter needs a PDF) or artwork.front and artwork.back (a postcard). Free. The file is sent as base64; " +
+        "it must decode to at most 20 MB. An asset is immutable: upload a new one to change the artwork.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            content: { type: "string", description: "The file, base64-encoded (standard or URL-safe alphabet, padding optional)" },
+            content_type: { type: "string", enum: [...PHYSICAL_MAIL_ASSET_TYPES], description: "The file's media type" },
+        },
+        required: ["content", "content_type"],
+    },
+};
+/** Decodes the base64 `content`, refusing anything that is not base64 or that would exceed the route's limit before any bytes are sent. */
+export function decodeArtwork(args) {
+    const mime = args.content_type;
+    if (!PHYSICAL_MAIL_ASSET_TYPES.includes(mime)) {
+        throw new Error(`oneshot_physical_mail_upload: content_type must be one of ${PHYSICAL_MAIL_ASSET_TYPES.join(", ")}`);
+    }
+    if (typeof args.content !== "string" || args.content.length === 0)
+        throw new Error("oneshot_physical_mail_upload: content is required");
+    const text = args.content.replace(/\s+/g, "");
+    const size = base64Size(text);
+    if (size === null)
+        throw new Error("oneshot_physical_mail_upload: content is not base64");
+    if (size > PHYSICAL_MAIL_ASSET_LIMIT_BYTES) {
+        throw new Error(`oneshot_physical_mail_upload: the file is ${size} bytes; the limit is ${PHYSICAL_MAIL_ASSET_LIMIT_BYTES} bytes (20 MB)`);
+    }
+    const data = Buffer.from(text, "base64");
+    if (data.length === 0)
+        throw new Error("oneshot_physical_mail_upload: content decodes to nothing");
+    // The decoder is lenient; the structural check above is what bounds the size, and this guards the limit regardless.
+    if (data.length > PHYSICAL_MAIL_ASSET_LIMIT_BYTES) {
+        throw new Error(`oneshot_physical_mail_upload: the file is ${data.length} bytes; the limit is ${PHYSICAL_MAIL_ASSET_LIMIT_BYTES} bytes (20 MB)`);
+    }
+    return { data: new Uint8Array(data), mime: mime };
+}
+/**
+ * The decoded size of structurally valid base64 (standard or URL-safe alphabet, padding optional), or null.
+ * `Buffer.from(text, "base64")` tolerates a length one past a quartet, missing, short and excess padding
+ * (`AAAAA`, `AAA==`, `AAAA==`), so counting characters and subtracting the `=`s would undercount such
+ * input; the bound has to come from a shape the decoder cannot read differently.
+ */
+export function base64Size(text) {
+    if (!/^[A-Za-z0-9+/_-]*={0,2}$/.test(text))
+        return null;
+    const body = text.replace(/=+$/, "");
+    const padding = text.length - body.length;
+    const rem = body.length % 4;
+    // A body is never one character past a quartet, and padding, when given, is exactly what completes the last one.
+    if (body.length === 0 || rem === 1 || (padding > 0 && padding !== (4 - rem) % 4))
+        return null;
+    return Math.floor((body.length * 3) / 4);
+}
+export async function handlePhysicalMailUpload(agent, args) {
+    const { data, mime } = decodeArtwork(args);
+    return agent.physicalMail.uploadArtwork(data, mime);
+}