From 315749a87f658d88eb924df9da276e452bb7a57c Mon Sep 17 00:00:00 2001 From: Sanjith Sambath Date: Sun, 12 Jul 2026 21:54:49 -0700 Subject: [PATCH 1/2] chore: track toolkit 0.5.0 / 0.3.0 (structured output + native errors) Bump compatibility pins to agentmail-toolkit TypeScript 0.5.0 / Python 0.3.0 and document the toolkit's new contract in the agentmail-toolkit skill: every tool declares an output schema, MCP calls return validated structuredContent, and adapters signal failures through their framework's native error channel (throw / isError) instead of returning an error string. BLOCKED on the 0.5.0 / 0.3.0 npm + PyPI publish: check_compatibility.py gates on the registry 'latest', so CI stays red until those versions go live. Merge after publishing. Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 5 +++++ compatibility.json | 6 +++--- skills/agentmail-toolkit/SKILL.md | 10 +++++++++- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68990cf..93009be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ All notable changes to the AgentMail plugin are documented here. +## Unreleased + +- Track AgentMail Toolkit TypeScript 0.5.0 and Python 0.3.0. +- Document the toolkit's structured-output contract (every tool declares an output schema; MCP calls return validated `structuredContent`) and its framework-native error signaling (adapters throw / MCP returns `isError` on failure, instead of returning an error string). **Blocked on the 0.5.0 / 0.3.0 npm and PyPI publish — the compatibility CI gate stays red until those versions are the registry `latest`.** + ## 0.3.0 - 2026-07-10 - Use the hosted AgentMail MCP server with OAuth for Claude, Codex, and Cursor. diff --git a/compatibility.json b/compatibility.json index cbfa4b3..cac0ad6 100644 --- a/compatibility.json +++ b/compatibility.json @@ -1,13 +1,13 @@ { - "verifiedAt": "2026-07-10", + "verifiedAt": "2026-07-12", "agentmail": { "typescript": "0.5.14", "python": "0.5.6" }, "cli": "0.7.12", "toolkit": { - "typescript": "0.4.2", - "python": "0.2.7" + "typescript": "0.5.0", + "python": "0.3.0" }, "hostedMcp": { "url": "https://mcp.agentmail.to/mcp", diff --git a/skills/agentmail-toolkit/SKILL.md b/skills/agentmail-toolkit/SKILL.md index 88b4b76..bbe44fa 100644 --- a/skills/agentmail-toolkit/SKILL.md +++ b/skills/agentmail-toolkit/SKILL.md @@ -53,7 +53,7 @@ import { AgentMailToolkit } from "agentmail-toolkit/mcp"; const tools = new AgentMailToolkit().getTools(); ``` -Each tool provides a name, title, description, input schema, callback, and annotations for registration on your own MCP server. The Python package does not ship an MCP adapter. +Each tool provides a name, title, description, input schema, output schema, callback, and complete annotations for registration on your own MCP server. On a successful call the MCP adapter returns `structuredContent` (validated against the output schema) alongside the JSON text block; on failure it returns an `isError` result. The Python package does not ship an MCP adapter. ### Existing client @@ -127,6 +127,14 @@ class EmailAssistant(Agent): Subclass the LiveKit `Agent` and pass instructions and toolkit tools through `super().__init__`. +## Results and errors + +Requires toolkit TypeScript >= 0.5.0 or Python >= 0.3.0. + +- Every tool declares an output schema. MCP tool calls return validated `structuredContent` plus a matching JSON text block on success; void operations (deletes) return a stable `{ success: true }` object. +- A failed tool call is signaled through each framework's native error channel, not as a successful result. The Vercel AI SDK, LangChain, and clawdbot adapters (and the generic export) **throw** on failure — surfacing a distinct tool-error the model can tell apart from a normal result — and the MCP adapter returns `isError: true`. Do not treat a returned value as an error string; catch the thrown error or check `isError`. +- Error messages are concise and bounded (the API's own reason, not a raw SDK dump). + ## Safety - Limit tools to the workflow’s needs. From 835297c22b4ac050e31ace745488e1e4001b5a67 Mon Sep 17 00:00:00 2001 From: Sanjith Sambath Date: Sun, 12 Jul 2026 22:32:10 -0700 Subject: [PATCH 2/2] ci: pin plugin validation to agentmail-toolkit 0.5.0 The blocking PR gate (validate.yml) type-checks the TypeScript examples against a hardcoded toolkit version, separate from compatibility.json. Bump it to 0.5.0 so the plugin's examples are actually validated against the new toolkit (and the throw-on-error change is exercised). This also makes the gate correctly RED until 0.5.0 is published, since installing an unpublished version 404s. Co-Authored-By: Claude Fable 5 --- .github/workflows/validate.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 5d8ea02..0c2e2ee 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -41,7 +41,7 @@ jobs: tmp="$(mktemp -d)" cp tests/sdk_typescript.ts tests/webhook_typescript.ts tests/webhook_verification.ts tests/package.json "$tmp/" cd "$tmp" - npm install --no-save "agentmail@0.5.14" "agentmail-toolkit@0.4.2" "ai@6" "langchain@1" "svix" "express" "@types/express" "typescript@5.9.3" "tsx" "@types/node@22" + npm install --no-save "agentmail@0.5.14" "agentmail-toolkit@0.5.0" "ai@6" "langchain@1" "svix" "express" "@types/express" "typescript@5.9.3" "tsx" "@types/node@22" ./node_modules/.bin/tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext sdk_typescript.ts webhook_typescript.ts webhook_verification.ts ./node_modules/.bin/tsx webhook_verification.ts