@pyai/mcp 0.2.0 → 0.3.1

package/dist/tools.js

@@ -9,11 +9,39 @@
  * remaining tools require a key (env `PYAI_API_KEY` or one adopted from
  * `create_sandbox_key`).
  */
-import { writeFile } from "node:fs/promises";
+import { writeFile, lstat, realpath } from "node:fs/promises";
+import { resolve, relative, isAbsolute, dirname, basename } from "node:path";
+import { Ajv } from "ajv";
+import { API_TOOLS } from "./generated-tools.js";
+import { EXTRA_TOOLS, EXTRA_SCOPES, extraTool } from "./extra-tools.js";
+import { GUIDE, WORKFLOWS, SEARCH_TERMS } from "./workflows.js";
 import { PyAIError } from "./client.js";
+export const localContext = {
+    mode: "stdio",
+    outputRoot: process.cwd(),
+    audio: async (bytes, mimeType) => {
+        if (bytes.length > 8 * 1024 * 1024)
+            return toolError("Audio exceeds the inline limit. Use output_path with Speak or download with the CLI.", "artifact_too_large");
+        return {
+            content: [
+                {
+                    type: "audio",
+                    data: Buffer.from(bytes).toString("base64"),
+                    mimeType,
+                },
+            ],
+            structuredContent: { bytes: bytes.length, mime_type: mimeType },
+        };
+    },
+};
 function text(value) {
     const s = typeof value === "string" ? value : JSON.stringify(value, null, 2);
-    return { content: [{ type: "text", text: s }] };
+    return {
+        content: [{ type: "text", text: s }],
+        structuredContent: typeof value === "object" && value !== null
+            ? value
+            : { text: s },
+    };
 }
 /** Tools that need a configured key. create_sandbox_key + get_started do not. */
 const KEY_REQUIRED = new Set([
@@ -23,61 +51,25 @@ const KEY_REQUIRED = new Set([
     "create_transcription_job",
     "get_transcription_job",
     "whoami",
+    "configure_amd",
+    "get_amd_call",
+    "list_amd_calls",
+    "enable_recap",
+    "get_recap",
+    "list_recap_calls",
+    "create_recap",
 ]);
-const GET_STARTED = [
-    "# Build with the PyAI voice API",
-    "",
-    "Source of truth (fetch it; never invent endpoints):",
-    "- OpenAPI spec: https://api.pyai.com/openapi.json",
-    "- Curated agent index: https://api.pyai.com/llms.txt",
-    "- Docs: https://docs.pyai.com",
-    "",
-    "## 1. Get a key (zero steps)",
-    "Call the `create_sandbox_key` MCP tool — it returns a free `pyai_test_...` key",
-    "that works on the first call (no card, no 402). Store it in `PYAI_API_KEY`.",
-    "For production, create a live key at https://console.pyai.com.",
-    "",
-    "## 2. Install the SDK (preferred over hand-rolled fetch)",
-    "- TypeScript/JS: `npm install @pyai/sdk` then `import PyAI from \"@pyai/sdk\"`",
-    "- Python: `pip install pyai-sdk` then `from pyai import PyAI`",
-    "Keys are opaque (<=512 chars): never parse/split/decode/log them; read from env.",
-    "",
-    "## 3. Text-to-speech (Speak)",
-    "```ts",
-    "import PyAI from \"@pyai/sdk\";",
-    "const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });",
-    "const audio = await pyai.audio.speech({ input: \"Hello from PyAI\", response_format: \"mp3\" });",
-    "// `audio` is an ArrayBuffer of MP3 bytes — write it to a file or stream it.",
-    "```",
-    "",
-    "## 4. Speech-to-text (Hear)",
-    "```ts",
-    "const res = await pyai.audio.transcriptions.create({ file: blob, filename: \"audio.wav\" });",
-    "console.log(res.text);",
-    "```",
-    "",
-    "## 5. Realtime voice agent (Omni)",
-    "Open a WebSocket to `wss://api.pyai.com/v1/omni?format=pcm16&rate=24000`,",
-    "authenticate with the subprotocol `pyai-key.<key>` (browser-safe) or `?api_key=<key>`",
-    "(server). Omni is zero-state — send a `{type:\"configure\"}` frame after connect.",
-    "In the browser, mint a short-lived token server-side with `pyai.omni.createSession(...)`",
-    "instead of shipping a secret key.",
-    "",
-    "## 6. Errors — branch on the stable `error.code`",
-    "`402 credit_exhausted` (add credit / use a sandbox key), `403 forbidden` (missing scope),",
-    "`429 rate_limit_exceeded` (back off, honor `Retry-After`). Don't retry 4xx except 429.",
-].join("\n");
-export const TOOLS = [
+const LEGACY_TOOLS = [
     {
         name: "create_sandbox_key",
-        description: "Get a FREE PyAI sandbox key with no human steps (no email, card, or signup). " +
-            "Returns a pyai_test_ key that works on the first call and is adopted for the rest " +
-            "of this session, so the other tools work immediately. Call this FIRST if no " +
-            "PYAI_API_KEY is set. The returned key should be stored in the app's PYAI_API_KEY env var.",
+        description: "Create a NEW isolated sandbox only when the user asks to try PyAI without an account. Local stdio only. Adopts the key privately for this session; never returns the secret. Prefer pyai login to use an existing workspace.",
         inputSchema: {
             type: "object",
             properties: {
-                label: { type: "string", description: "Optional label (e.g. your app name) shown in the PyAI console." },
+                label: {
+                    type: "string",
+                    description: "Optional label (e.g. your app name) shown in the PyAI console.",
+                },
             },
             additionalProperties: false,
         },
@@ -85,20 +77,32 @@ export const TOOLS = [
     {
         name: "get_started",
         description: "Return a concise, correct quickstart for building with PyAI (auth, SDK install, " +
-            "TTS/STT/realtime snippets, error handling). No key or network needed — read this " +
+            "TTS/STT/realtime snippets, error handling). No key or network needed, read this " +
             "before writing PyAI code so you use the right endpoints and the official SDK.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
     },
     {
         name: "whoami",
         description: "Introspect the active key (GET /v1/me): org, environment (test/live), granted scopes, " +
             "and rate-limit/credit posture. Use it to self-diagnose a 401/403/402.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
     },
     {
         name: "list_models",
         description: "List the available PyAI models (catalog). No arguments.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
     },
     {
         name: "list_voices",
@@ -107,8 +111,14 @@ export const TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
-                gender: { type: "string", description: "Filter by voice gender (e.g. female, male)." },
-                region: { type: "string", description: "Filter by accent/region (e.g. en_us, en_gb)." },
+                gender: {
+                    type: "string",
+                    description: "Filter by voice gender (e.g. female, male).",
+                },
+                region: {
+                    type: "string",
+                    description: "Filter by accent/region (e.g. en_us, en_gb).",
+                },
             },
             additionalProperties: false,
         },
@@ -117,17 +127,27 @@ export const TOOLS = [
         name: "synthesize_speech",
         description: "Text-to-speech. Synthesizes `input` with `voice` and writes the audio to " +
             "`output_path`. Returns the file path and byte count. Note: consumes sandbox " +
-            "usage quota — for writing app code, prefer get_started over running this.",
+            "usage quota, for writing app code, prefer get_started over running this.",
         inputSchema: {
             type: "object",
             properties: {
                 input: { type: "string", description: "Text to synthesize." },
-                voice: { type: "string", description: "Voice id from list_voices. Omit for the account default." },
-                output_path: { type: "string", description: "Absolute file path to write the audio to." },
-                model: { type: "string", description: "Defaults to pyai-voice." },
-                response_format: { type: "string", enum: ["wav", "mp3", "opus", "pcm"], description: "Defaults to wav." },
+                voice: {
+                    type: "string",
+                    description: "Voice id from list_voices. Omit for the account default.",
+                },
+                output_path: {
+                    type: "string",
+                    description: "Absolute file path to write the audio to.",
+                },
+                model: { type: "string", description: "Defaults to pyai-speak." },
+                response_format: {
+                    type: "string",
+                    enum: ["wav", "mp3", "opus", "pcm"],
+                    description: "Defaults to wav.",
+                },
             },
-            required: ["input", "output_path"],
+            required: ["input"],
             additionalProperties: false,
         },
     },
@@ -138,10 +158,29 @@ export const TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
-                audio_url: { type: "string", description: "https URL of the audio to transcribe." },
+                audio_url: {
+                    type: "string",
+                    description: "https URL of the audio to transcribe.",
+                },
                 model: { type: "string" },
-                diarize: { type: "boolean", description: "Single-track speaker diarization." },
-                channel: { type: "boolean", description: "Dual-channel (stereo) per-channel speakers." },
+                diarize: {
+                    type: "boolean",
+                    description: "Single-track speaker diarization.",
+                },
+                channel: {
+                    type: "boolean",
+                    description: "Dual-channel (stereo) per-channel speakers.",
+                },
+                call_id: {
+                    type: "string",
+                    description: "Stable id for the post-call Recap. Defaults to the job id.",
+                },
+                pack_id: {
+                    type: "string",
+                    description: "Optional Recap pack (default sales_outbound).",
+                },
+                call_direction: { type: "string", enum: ["inbound", "outbound"] },
+                customer_name: { type: "string" },
                 output_formats: {
                     type: "array",
                     items: { type: "string", enum: ["json", "srt", "vtt"] },
@@ -157,31 +196,318 @@ export const TOOLS = [
         description: "Get the status + result of a transcription job by id.",
         inputSchema: {
             type: "object",
-            properties: { job_id: { type: "string", description: "The job_id from create_transcription_job." } },
+            properties: {
+                job_id: {
+                    type: "string",
+                    description: "The job_id from create_transcription_job.",
+                },
+            },
             required: ["job_id"],
             additionalProperties: false,
         },
     },
+    {
+        name: "configure_amd",
+        description: "Set the PyAI AMD (answering-machine detection) operating point + webhook (POST /v1/amd/config). " +
+            "`aggressiveness` is one dial 0-1: near 0 is human-safe (never hang up on a person), near 1 fires " +
+            "'machine' fast. The realtime detection itself is a Twilio Media Streams WebSocket " +
+            "(wss /v1/amd/stream), a one-line-TwiML drop-in, not an MCP tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                aggressiveness: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 1,
+                    description: "Operating point 0-1 (default 0.25).",
+                },
+                webhook_url: {
+                    type: "string",
+                    description: "https URL to POST amd.call.completed events to.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_amd_calls",
+        description: "List recent PyAI AMD decisions (GET /v1/amd/calls). Each carries answered_by (human/voicemail/ivr/" +
+            "screening/sit_invalid/…), answered_by_twilio (Twilio's enum, for routing parity), confidence, " +
+            "decision_ms, and the word-level reason.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Max results (1-100, default 20).",
+                },
+                session_label: {
+                    type: "string",
+                    description: "Filter by the opaque connect-URL/TwiML tag.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_amd_call",
+        description: "Get one PyAI AMD decision by call id (GET /v1/amd/calls/{id}): who/what answered, with the reason.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                call_id: {
+                    type: "string",
+                    description: "The call id the decision was recorded under.",
+                },
+            },
+            required: ["call_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "enable_recap",
+        description: "Enable Recap for the key's org (PUT /v1/recap/config). Sandbox keys already mint with Recap on; " +
+            "call this to set a webhook or pack, or to enable Recap on a signup/live key. Requires recap:configure.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                enabled: { type: "boolean", description: "Defaults to true." },
+                webhook_url: {
+                    type: "string",
+                    description: "https URL for recap.complete events.",
+                },
+                default_pack_id: {
+                    type: "string",
+                    description: "Defaults to sales_outbound.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_recap",
+        description: "Submit speaker-labelled utterances and get a recap.call (POST /v1/recap/calls/{call_id}). " +
+            "Poll with get_recap. Prefer this over a DIY LLM summary. Requires recap:read and Recap enabled.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                call_id: {
+                    type: "string",
+                    description: "Stable id you will read back.",
+                },
+                utterances: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            speaker_role: { type: "string", enum: ["agent", "customer"] },
+                            text: { type: "string" },
+                            offset_s: { type: "number" },
+                            duration_s: { type: "number" },
+                        },
+                        required: ["speaker_role", "text", "offset_s", "duration_s"],
+                    },
+                },
+                pack_id: { type: "string" },
+                call_direction: { type: "string", enum: ["inbound", "outbound"] },
+                customer_name: { type: "string" },
+            },
+            required: ["call_id", "utterances"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_recap",
+        description: "Read one Recap by call id (GET /v1/recap/calls/{call_id}). When complete, `record` is recap.record.v1 " +
+            "(tldr, summary, action_items, disposition, next_steps, talk_ratio, signals, fields).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                call_id: {
+                    type: "string",
+                    description: "The call_id passed to create_recap or the Hear job.",
+                },
+            },
+            required: ["call_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_recap_calls",
+        description: "List recent Recap records (GET /v1/recap/calls). Requires recap:read and Recap enabled.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Max results (1-100, default 20).",
+                },
+                status: {
+                    type: "string",
+                    enum: ["pending", "processing", "complete", "failed"],
+                },
+            },
+            additionalProperties: false,
+        },
+    },
 ];
+const readOnly = new Set([
+    "get_started",
+    "whoami",
+    "list_models",
+    "list_voices",
+    "get_transcription_job",
+    "list_amd_calls",
+    "get_amd_call",
+    "get_recap",
+    "list_recap_calls",
+    "discover_tools",
+    "get_dub_capabilities",
+    "get_dub_job",
+    "get_dub_audio",
+    "get_cast_render",
+    "get_cast_audio",
+]);
+export const TOOL_SCOPES = {
+    synthesize_speech: "speak:synthesize",
+    create_transcription_job: "transcribe:jobs",
+    get_transcription_job: "transcribe:jobs",
+    configure_amd: "amd:configure",
+    get_amd_call: "amd:read",
+    list_amd_calls: "amd:read",
+    enable_recap: "recap:configure",
+    create_recap: "recap:read",
+    get_recap: "recap:read",
+    list_recap_calls: "recap:read",
+    ...EXTRA_SCOPES,
+    ...Object.fromEntries(API_TOOLS.map((t) => [t.name, t.route.scope])),
+};
+export const TOOLS = [
+    ...LEGACY_TOOLS,
+    ...API_TOOLS.map(({ route, ...tool }) => tool),
+    ...EXTRA_TOOLS,
+].map((t) => ({
+    ...t,
+    // Every client receives a display title, including handwritten tools.
+    // Keep protocol names stable and preserve acronyms in human-facing labels.
+    title: t.title ??
+        (t.name === "whoami"
+            ? "Who Am I"
+            : t.name
+                .split("_")
+                .map((word) => word === "amd" ? "AMD" : word[0].toUpperCase() + word.slice(1))
+                .join(" ")),
+    annotations: t.annotations ?? {
+        readOnlyHint: readOnly.has(t.name),
+        destructiveHint: ["configure_amd", "enable_recap"].includes(t.name),
+        idempotentHint: readOnly.has(t.name),
+        openWorldHint: !["get_started", "discover_tools"].includes(t.name),
+    },
+    _meta: {
+        securitySchemes: TOOL_SCOPES[t.name]
+            ? [{ type: "oauth2", scopes: [TOOL_SCOPES[t.name]] }]
+            : [{ type: "noauth" }],
+    },
+}));
+const ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
+const validators = new Map(TOOLS.map((t) => [t.name, ajv.compile(t.inputSchema)]));
 function str(args, key) {
     const v = args[key];
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
-export async function callTool(name, args, client) {
-    if (KEY_REQUIRED.has(name) && !client.hasKey) {
-        return toolError("No PyAI key configured. Call the `create_sandbox_key` tool first to get a free key with no setup, " +
-            "or set the PYAI_API_KEY env var to a pyai_test_/pyai_live_ key.");
+export async function callTool(name, args, client, ctx = localContext) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool)
+        return toolError(`Unknown tool: ${name}`, "unknown_tool");
+    const validator = validators.get(name);
+    if (!validator(args))
+        return toolError(`Invalid arguments: ${ajv.errorsText(validator.errors, { separator: "; " })}`, "invalid_arguments");
+    if (name === "create_sandbox_key" && ctx.mode === "http")
+        return toolError("Use your host OAuth connection to authorize an existing project. Sandbox creation is local-only.", "local_only");
+    const scope = TOOL_SCOPES[name];
+    if (ctx.scopes && scope && !ctx.scopes.includes(scope))
+        return {
+            ...toolError(`This connection needs ${scope}. Reconnect and approve that permission.`, "insufficient_scope"),
+            _meta: {
+                "mcp/www_authenticate": [
+                    `Bearer error="insufficient_scope", scope="${scope}", resource_metadata="https://api.pyai.com/.well-known/oauth-protected-resource/mcp"`,
+                ],
+            },
+        };
+    if (name === "discover_tools") {
+        const words = String(args.query ?? "")
+            .toLowerCase()
+            .match(/[a-z0-9]+/g)
+            ?.filter((w) => ![
+            "a",
+            "an",
+            "the",
+            "to",
+            "in",
+            "for",
+            "this",
+            "my",
+            "use",
+            "create",
+            "get",
+            "and",
+            "i",
+            "want",
+        ].includes(w)) ?? [];
+        const matches = Object.entries(WORKFLOWS)
+            .map(([key, w]) => ({
+            key,
+            w,
+            score: words.reduce((score, word) => score +
+                Number(`${key} ${SEARCH_TERMS[key]} ${w.title} ${w.example}`
+                    .toLowerCase()
+                    .includes(word)), 0),
+        }))
+            .filter((m) => m.score > 0)
+            .sort((a, b) => b.score - a.score);
+        const selected = matches.length
+            ? matches
+            : Object.entries(WORKFLOWS).map(([key, w]) => ({ key, w, score: 0 }));
+        const names = new Set(selected.flatMap((m) => [...m.w.tools]));
+        return text({
+            workflows: selected.map(({ key, w }) => ({ product: key, ...w })),
+            tools: TOOLS.filter((t) => names.has(t.name)).map((t) => ({
+                name: t.name,
+                description: t.description,
+            })),
+            guide: "pyai://guide",
+        });
+    }
+    if ((KEY_REQUIRED.has(name) || scope) && !client.hasKey) {
+        return toolError("No PyAI connection. Run pyai login for local MCP, connect through OAuth for hosted MCP, or explicitly request create_sandbox_key for a new local sandbox.", "authentication_required");
     }
     try {
+        const generated = API_TOOLS.find((t) => t.name === name);
+        if (generated) {
+            const path = generated.route.path.replace(/\{([^}]+)\}/g, (_, key) => encodeURIComponent(String(args[key])));
+            const query = new URLSearchParams();
+            for (const key of generated.route.query)
+                if (args[key] !== undefined)
+                    query.set(key, String(args[key]));
+            return text(await client.json(generated.route.method, path + (query.size ? "?" + query.toString() : ""), args.body));
+        }
+        const extra = await extraTool(name, args, client, ctx);
+        if (extra)
+            return extra;
         switch (name) {
             case "get_started":
-                return text(GET_STARTED);
+                return text(GUIDE);
             case "create_sandbox_key": {
                 const label = str(args, "label");
                 const result = await client.postJson("/v1/sandbox/keys", label ? { label } : {});
                 if (result && typeof result.api_key === "string")
                     client.setApiKey(result.api_key);
-                return text(result);
+                const { api_key: _secret, ...safe } = result;
+                return text({
+                    ...safe,
+                    credential_saved: "session",
+                    next_step: "Call whoami; the key remains private inside this MCP process.",
+                });
             }
             case "whoami":
                 return text(await client.getJson("/v1/me"));
@@ -201,16 +527,48 @@ export async function callTool(name, args, client) {
                 const outputPath = str(args, "output_path");
                 if (!input)
                     return toolError("`input` is required.");
-                if (!outputPath)
-                    return toolError("`output_path` is required.");
-                const body = { model: str(args, "model") ?? "pyai-voice", input };
+                if (outputPath && ctx.mode !== "stdio")
+                    return toolError("output_path is local-only. Remote speech returns playable audio or a download.", "invalid_arguments");
+                let target;
+                if (outputPath) {
+                    const root = resolve(ctx.outputRoot ?? process.cwd());
+                    target = resolve(root, outputPath);
+                    const rel = relative(root, target);
+                    if (!rel || rel.startsWith("..") || isAbsolute(rel))
+                        return toolError("output_path must be inside the MCP working directory.", "invalid_arguments");
+                    const parent = await realpath(dirname(target));
+                    const realRoot = await realpath(root);
+                    const parentRel = relative(realRoot, parent);
+                    if (parentRel.startsWith("..") || isAbsolute(parentRel))
+                        return toolError("Output parent escapes the working directory.", "invalid_arguments");
+                    target = resolve(parent, basename(target));
+                    const exists = await lstat(target).then(() => true, (e) => {
+                        if (e.code === "ENOENT")
+                            return false;
+                        throw e;
+                    });
+                    if (exists)
+                        return toolError("Output already exists. Choose a new filename.", "output_exists");
+                }
+                const body = {
+                    model: str(args, "model") ?? "pyai-speak",
+                    input,
+                    response_format: str(args, "response_format") ?? "mp3",
+                };
                 if (str(args, "voice"))
                     body.voice = str(args, "voice");
                 if (str(args, "response_format"))
                     body.response_format = str(args, "response_format");
-                const bytes = await client.postForBytes("/v1/audio/speech", body);
-                await writeFile(outputPath, bytes);
-                return text({ output_path: outputPath, bytes: bytes.byteLength, status: "ok" });
+                const { bytes, mimeType } = await client.bytes("POST", "/v1/audio/speech", body);
+                if (target) {
+                    await writeFile(target, bytes, { flag: "wx" });
+                    return text({
+                        output_path: target,
+                        bytes: bytes.length,
+                        status: "ok",
+                    });
+                }
+                return ctx.audio(bytes, mimeType);
             }
             case "create_transcription_job": {
                 const audioUrl = str(args, "audio_url");
@@ -225,6 +583,14 @@ export async function callTool(name, args, client) {
                     body.channel = args.channel;
                 if (Array.isArray(args.output_formats))
                     body.output_formats = args.output_formats;
+                if (str(args, "call_id"))
+                    body.call_id = str(args, "call_id");
+                if (str(args, "pack_id"))
+                    body.pack_id = str(args, "pack_id");
+                if (str(args, "call_direction"))
+                    body.call_direction = str(args, "call_direction");
+                if (str(args, "customer_name"))
+                    body.customer_name = str(args, "customer_name");
                 return text(await client.postJson("/v1/transcription/jobs", body));
             }
             case "get_transcription_job": {
@@ -233,6 +599,70 @@ export async function callTool(name, args, client) {
                     return toolError("`job_id` is required.");
                 return text(await client.getJson(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`));
             }
+            case "configure_amd": {
+                const body = {};
+                if (typeof args.aggressiveness === "number")
+                    body.aggressiveness = args.aggressiveness;
+                if (str(args, "webhook_url"))
+                    body.webhook_url = str(args, "webhook_url");
+                return text(await client.postJson("/v1/amd/config", body));
+            }
+            case "list_amd_calls": {
+                const q = new URLSearchParams();
+                if (typeof args.limit === "number")
+                    q.set("limit", String(args.limit));
+                if (str(args, "session_label"))
+                    q.set("session_label", str(args, "session_label"));
+                const qs = q.toString();
+                return text(await client.getJson(`/v1/amd/calls${qs ? `?${qs}` : ""}`));
+            }
+            case "get_amd_call": {
+                const callId = str(args, "call_id");
+                if (!callId)
+                    return toolError("`call_id` is required.");
+                return text(await client.getJson(`/v1/amd/calls/${encodeURIComponent(callId)}`));
+            }
+            case "enable_recap": {
+                const body = {
+                    enabled: args.enabled === undefined ? true : Boolean(args.enabled),
+                };
+                if (str(args, "webhook_url"))
+                    body.webhook_url = str(args, "webhook_url");
+                if (str(args, "default_pack_id"))
+                    body.default_pack_id = str(args, "default_pack_id");
+                return text(await client.putJson("/v1/recap/config", body));
+            }
+            case "create_recap": {
+                const callId = str(args, "call_id");
+                if (!callId)
+                    return toolError("`call_id` is required.");
+                if (!Array.isArray(args.utterances) || args.utterances.length === 0) {
+                    return toolError("`utterances` must be a non-empty array.");
+                }
+                const body = { utterances: args.utterances };
+                if (str(args, "pack_id"))
+                    body.pack_id = str(args, "pack_id");
+                if (str(args, "call_direction"))
+                    body.call_direction = str(args, "call_direction");
+                if (str(args, "customer_name"))
+                    body.customer_name = str(args, "customer_name");
+                return text(await client.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, body));
+            }
+            case "get_recap": {
+                const callId = str(args, "call_id");
+                if (!callId)
+                    return toolError("`call_id` is required.");
+                return text(await client.getJson(`/v1/recap/calls/${encodeURIComponent(callId)}`));
+            }
+            case "list_recap_calls": {
+                const q = new URLSearchParams();
+                if (typeof args.limit === "number")
+                    q.set("limit", String(args.limit));
+                if (str(args, "status"))
+                    q.set("status", str(args, "status"));
+                const qs = q.toString();
+                return text(await client.getJson(`/v1/recap/calls${qs ? `?${qs}` : ""}`));
+            }
             default:
                 return toolError(`Unknown tool: ${name}`);
         }
@@ -243,11 +673,26 @@ export async function callTool(name, args, client) {
                 return toolError("Sandbox-key minting is not enabled on this deployment. Create a free key at " +
                     "https://console.pyai.com and set it as PYAI_API_KEY.");
             }
-            return toolError(`PyAI API error ${err.status}${err.code ? ` (${err.code})` : ""}: ${err.message}`);
+            return {
+                ...toolError(`PyAI API error ${err.status} (${err.code ?? "api_error"}): ${err.message}`, err.code ?? "api_error"),
+                structuredContent: {
+                    error: {
+                        code: err.code ?? "api_error",
+                        status: err.status,
+                        request_id: err.requestId,
+                        retry_after: err.retryAfter,
+                        message: err.message,
+                    },
+                },
+            };
         }
         return toolError(`Tool failed: ${err.message}`);
     }
 }
-function toolError(message) {
-    return { content: [{ type: "text", text: message }], isError: true };
+function toolError(message, code = "tool_error") {
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: { code, message } },
+        isError: true,
+    };
 }