@mantyx/sdk 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -26,13 +36,21 @@ __export(index_exports, {
   MantyxClient: () => MantyxClient,
   MantyxError: () => MantyxError,
   MantyxNetworkError: () => MantyxNetworkError,
+  MantyxParseError: () => MantyxParseError,
   MantyxRunError: () => MantyxRunError,
   MantyxToolError: () => MantyxToolError,
   SDK_VERSION: () => SDK_VERSION,
+  defineLocalA2A: () => defineLocalA2A,
+  defineLocalMcp: () => defineLocalMcp,
   defineLocalTool: () => defineLocalTool,
+  isLocalA2ATool: () => isLocalA2ATool,
+  isLocalMcpServer: () => isLocalMcpServer,
   isLocalTool: () => isLocalTool,
+  mantyxA2A: () => mantyxA2A,
+  mantyxMcp: () => mantyxMcp,
   mantyxPluginTool: () => mantyxPluginTool,
   mantyxTool: () => mantyxTool,
+  parseRunOutput: () => parseRunOutput,
   readSseStream: () => readSseStream,
   toToolParametersWire: () => toToolParametersWire,
   zodToJsonSchema: () => zodToJsonSchema
@@ -87,6 +105,361 @@ var MantyxRunError = class extends MantyxError {
     this.subtype = subtype;
   }
 };
+var MantyxParseError = class extends MantyxError {
+  text;
+  constructor(message, text, opts = {}) {
+    super(message, { code: "output_parse_failed" });
+    this.name = "MantyxParseError";
+    this.text = text;
+    if (opts.cause !== void 0) {
+      this.cause = opts.cause;
+    }
+  }
+};
+
+// src/tools.ts
+function defineLocalTool(opts) {
+  assertToolName(opts.name);
+  return {
+    kind: "local",
+    name: opts.name,
+    description: opts.description ?? "",
+    parameters: opts.parameters,
+    execute: opts.execute
+  };
+}
+function mantyxTool(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error("mantyxTool(id): id must be a non-empty string");
+  }
+  return { kind: "mantyx", id };
+}
+function mantyxPluginTool(name) {
+  if (typeof name !== "string" || !name.startsWith("@") || !name.includes("/")) {
+    throw new Error(
+      `mantyxPluginTool(name): expected "@plugin-slug/tool-name", got ${JSON.stringify(name)}`
+    );
+  }
+  return { kind: "mantyx_plugin", name };
+}
+function mantyxA2A(opts) {
+  assertToolName(opts.name);
+  if (typeof opts.agentCardUrl !== "string" || opts.agentCardUrl.length === 0) {
+    throw new Error("mantyxA2A: agentCardUrl is required");
+  }
+  return {
+    kind: "a2a",
+    name: opts.name,
+    ...opts.description !== void 0 ? { description: opts.description } : {},
+    agentCardUrl: opts.agentCardUrl,
+    ...opts.headers ? { headers: { ...opts.headers } } : {},
+    ...opts.contextId ? { contextId: opts.contextId } : {}
+  };
+}
+function defineLocalA2A(opts) {
+  assertToolName(opts.name);
+  if (typeof opts.agentCardUrl !== "string" || opts.agentCardUrl.length === 0) {
+    throw new Error("defineLocalA2A: `agentCardUrl` is required");
+  }
+  return {
+    kind: "a2a_local",
+    name: opts.name,
+    agentCardUrl: opts.agentCardUrl,
+    headers: opts.headers ? { ...opts.headers } : void 0
+  };
+}
+function mantyxMcp(opts) {
+  assertToolName(opts.name);
+  if (typeof opts.url !== "string" || opts.url.length === 0) {
+    throw new Error("mantyxMcp: url is required");
+  }
+  return {
+    kind: "mcp",
+    name: opts.name,
+    url: opts.url,
+    ...opts.headers ? { headers: { ...opts.headers } } : {},
+    ...opts.toolFilter ? { toolFilter: [...opts.toolFilter] } : {}
+  };
+}
+function defineLocalMcp(opts) {
+  assertToolName(opts.name);
+  const hasHttp = typeof opts.url === "string" && opts.url.length > 0;
+  const hasStdio = typeof opts.command === "string" && opts.command.length > 0;
+  if (hasHttp && hasStdio) {
+    throw new Error(
+      "defineLocalMcp: pass either `url` (Streamable HTTP) or `command` (stdio), not both"
+    );
+  }
+  if (!hasHttp && !hasStdio) {
+    throw new Error(
+      "defineLocalMcp: one of `url` (Streamable HTTP) or `command` (stdio) is required"
+    );
+  }
+  if (hasHttp) {
+    const url = opts.url;
+    return {
+      kind: "mcp_local",
+      name: opts.name,
+      http: {
+        url,
+        ...opts.headers ? { headers: { ...opts.headers } } : {}
+      },
+      stdio: void 0
+    };
+  }
+  const command = opts.command;
+  return {
+    kind: "mcp_local",
+    name: opts.name,
+    http: void 0,
+    stdio: {
+      command,
+      ...opts.args ? { args: [...opts.args] } : {},
+      ...opts.env ? { env: { ...opts.env } } : {},
+      ...opts.cwd ? { cwd: opts.cwd } : {}
+    }
+  };
+}
+function isLocalTool(t) {
+  return t.kind === "local";
+}
+function isLocalA2ATool(t) {
+  return t.kind === "a2a_local";
+}
+function isLocalMcpServer(t) {
+  return t.kind === "mcp_local";
+}
+var TOOL_NAME_RE = /^[a-zA-Z0-9_]{1,64}$/;
+function assertToolName(name) {
+  if (!TOOL_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid tool name ${JSON.stringify(name)}: must match /^[a-zA-Z0-9_]{1,64}$/`
+    );
+  }
+}
+function prefixedMcpToolName(serverName, toolName) {
+  const prefix = `${serverName}_`;
+  return toolName.startsWith(prefix) ? toolName : `${prefix}${toolName}`;
+}
+
+// src/local-resolver.ts
+async function resolveLocalRefs(tools, opts = { fetch: globalThis.fetch }) {
+  if (!tools || tools.length === 0) return { newlyOpenedMcp: [] };
+  const newlyOpenedMcp = [];
+  const work = [];
+  for (const t of tools) {
+    if (isLocalA2ATool(t)) {
+      if (t._resolvedCard) continue;
+      work.push(resolveA2A(t, opts.fetch));
+    } else if (isLocalMcpServer(t)) {
+      if (t._resolved) continue;
+      work.push(
+        resolveMcp(t).then((resolved) => {
+          if (resolved) newlyOpenedMcp.push(t);
+        })
+      );
+    }
+  }
+  await Promise.all(work);
+  return { newlyOpenedMcp };
+}
+async function resolveA2A(t, fetchImpl) {
+  const headers = { Accept: "application/json", ...t.headers ?? {} };
+  const res = await fetchImpl(t.agentCardUrl, { method: "GET", headers });
+  if (!res.ok) {
+    throw new Error(
+      `defineLocalA2A(${JSON.stringify(t.name)}): GET ${t.agentCardUrl} returned ${res.status} ${res.statusText}`
+    );
+  }
+  const card = await res.json();
+  if (!card || typeof card !== "object" || typeof card.name !== "string" || !card.name) {
+    throw new Error(
+      `defineLocalA2A(${JSON.stringify(t.name)}): ${t.agentCardUrl} did not return a valid Agent Card (missing required \`name\` field)`
+    );
+  }
+  t._resolvedCard = card;
+}
+async function resolveMcp(t) {
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  let transport;
+  let connect;
+  if (t.http) {
+    const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    const httpTransport = new StreamableHTTPClientTransport(new URL(t.http.url), {
+      requestInit: t.http.headers ? { headers: t.http.headers } : {}
+    });
+    transport = httpTransport;
+    connect = (c) => c.connect(httpTransport);
+  } else if (t.stdio) {
+    const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    const stdioTransport = new StdioClientTransport({
+      command: t.stdio.command,
+      ...t.stdio.args ? { args: t.stdio.args } : {},
+      ...t.stdio.env ? { env: t.stdio.env } : {},
+      ...t.stdio.cwd ? { cwd: t.stdio.cwd } : {}
+    });
+    transport = stdioTransport;
+    connect = (c) => c.connect(stdioTransport);
+  } else {
+    throw new Error(
+      `defineLocalMcp(${JSON.stringify(t.name)}): missing transport (no \`url\` or \`command\` was provided)`
+    );
+  }
+  const client = new Client({ name: "@mantyx/sdk", version: "0.3.0" }, { capabilities: {} });
+  try {
+    await connect(client);
+  } catch (err) {
+    throw new Error(
+      `defineLocalMcp(${JSON.stringify(t.name)}): failed to connect \u2014 ${err.message}`,
+      { cause: err }
+    );
+  }
+  const serverInfo = client.getServerVersion() ?? { name: t.name };
+  const listed = await client.listTools();
+  const tools = listed.tools.map((tool) => {
+    const out = {
+      name: tool.name,
+      inputSchema: tool.inputSchema
+    };
+    if (typeof tool.description === "string") out.description = tool.description;
+    if (tool.annotations) out.annotations = tool.annotations;
+    return out;
+  });
+  const close = async () => {
+    try {
+      await client.close();
+    } catch {
+    }
+    try {
+      const t2 = transport;
+      if (t2.close) await t2.close();
+    } catch {
+    }
+  };
+  t._resolved = {
+    serverInfo,
+    tools,
+    client,
+    close
+  };
+  return true;
+}
+async function closeMcpRefs(tools) {
+  if (!tools || tools.length === 0) return;
+  const closes = [];
+  for (const t of tools) {
+    if (!isLocalMcpServer(t)) continue;
+    const resolved = t._resolved;
+    if (!resolved) continue;
+    t._resolved = void 0;
+    closes.push(resolved.close());
+  }
+  await Promise.all(closes);
+}
+async function callA2A(t, args, opts = { fetch: globalThis.fetch }) {
+  const card = t._resolvedCard;
+  if (!card) {
+    throw new Error(
+      `defineLocalA2A(${JSON.stringify(t.name)}): agent card has not been resolved yet`
+    );
+  }
+  const url = typeof card.url === "string" && card.url.length > 0 ? card.url : t.agentCardUrl;
+  const body = {
+    jsonrpc: "2.0",
+    id: cryptoRandomId(),
+    method: "message/send",
+    params: {
+      message: {
+        kind: "message",
+        role: "user",
+        messageId: cryptoRandomId(),
+        parts: [{ kind: "text", text: args.message }]
+      }
+    }
+  };
+  const res = await opts.fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...t.headers ?? {}
+    },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    throw new Error(
+      `A2A message/send to ${url} returned ${res.status} ${res.statusText}`
+    );
+  }
+  const json = await res.json();
+  if (json.error) {
+    throw new Error(`A2A peer reported error ${json.error.code}: ${json.error.message}`);
+  }
+  return extractA2AReplyText(json.result);
+}
+function extractA2AReplyText(result) {
+  if (result == null) return "";
+  if (typeof result === "string") return result;
+  if (typeof result !== "object") return JSON.stringify(result);
+  const obj = result;
+  if (Array.isArray(obj.parts)) {
+    const text = textFromParts(obj.parts);
+    if (text) return text;
+  }
+  const status = obj.status;
+  const statusMessage = status?.message;
+  if (Array.isArray(statusMessage?.parts)) {
+    const text = textFromParts(statusMessage.parts);
+    if (text) return text;
+  }
+  const artifacts = obj.artifacts;
+  if (Array.isArray(artifacts) && artifacts.length > 0) {
+    const last = artifacts[artifacts.length - 1];
+    if (Array.isArray(last.parts)) {
+      const text = textFromParts(last.parts);
+      if (text) return text;
+    }
+  }
+  return JSON.stringify(result);
+}
+function textFromParts(parts) {
+  const out = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const p = part;
+    if ((p.kind === "text" || p.type === "text") && typeof p.text === "string") {
+      out.push(p.text);
+    }
+  }
+  return out.join("\n");
+}
+async function callMcpTool(server, toolName, args) {
+  const resolved = server._resolved;
+  if (!resolved) {
+    throw new Error(
+      `defineLocalMcp(${JSON.stringify(server.name)}): MCP server has not been initialised`
+    );
+  }
+  const result = await resolved.client.callTool({ name: toolName, arguments: args });
+  if (result.isError) {
+    const text = textFromMcpContent(result.content) || "MCP tool reported an error";
+    throw new Error(text);
+  }
+  return textFromMcpContent(result.content);
+}
+function textFromMcpContent(content) {
+  if (!content || content.length === 0) return "";
+  const out = [];
+  for (const block of content) {
+    if (block.type === "text" && typeof block.text === "string") out.push(block.text);
+  }
+  return out.join("\n");
+}
+function cryptoRandomId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
 
 // src/sse.ts
 async function* readSseStream(body, opts = {}) {
@@ -163,39 +536,6 @@ function parseEventBlock(block) {
   };
 }
 
-// src/tools.ts
-function defineLocalTool(opts) {
-  if (!/^[a-zA-Z0-9_]{1,64}$/.test(opts.name)) {
-    throw new Error(
-      `Invalid local tool name ${JSON.stringify(opts.name)}: must match /^[a-zA-Z0-9_]{1,64}$/`
-    );
-  }
-  return {
-    kind: "local",
-    name: opts.name,
-    description: opts.description ?? "",
-    parameters: opts.parameters,
-    execute: opts.execute
-  };
-}
-function mantyxTool(id) {
-  if (typeof id !== "string" || id.length === 0) {
-    throw new Error("mantyxTool(id): id must be a non-empty string");
-  }
-  return { kind: "mantyx", id };
-}
-function mantyxPluginTool(name) {
-  if (typeof name !== "string" || !name.startsWith("@") || !name.includes("/")) {
-    throw new Error(
-      `mantyxPluginTool(name): expected "@plugin-slug/tool-name", got ${JSON.stringify(name)}`
-    );
-  }
-  return { kind: "mantyx_plugin", name };
-}
-function isLocalTool(t) {
-  return t.kind === "local";
-}
-
 // src/zod-to-json-schema.ts
 var import_zod = require("zod");
 function zodToJsonSchema(schema) {
@@ -310,47 +650,79 @@ var MantyxClient = class {
   }
   // ------------------------------------------------------------- One-shot
   async runAgent(spec) {
-    const handlers = collectLocalHandlers(spec.tools ?? []);
-    const created = await this.request({
-      method: "POST",
-      path: "/agent-runs",
-      body: serializeAgentSpec(spec, {
-        prompt: spec.prompt,
-        messages: spec.messages
-      })
-    });
-    return this.driveRun(created.runId, handlers, {
-      ...spec.onAssistantDelta ? { onAssistantDelta: spec.onAssistantDelta } : {},
-      ...spec.onEvent ? { onEvent: spec.onEvent } : {},
-      ...spec.signal ? { signal: spec.signal } : {}
-    });
+    const tools = spec.tools ?? [];
+    await resolveLocalRefs(tools, { fetch: this.options.fetch });
+    const handlers = collectLocalHandlers(tools);
+    try {
+      const created = await this.request({
+        method: "POST",
+        path: "/agent-runs",
+        body: serializeAgentSpec(spec, {
+          prompt: spec.prompt,
+          messages: spec.messages
+        })
+      });
+      return await this.driveRun(created.runId, handlers, {
+        ...spec.onAssistantDelta ? { onAssistantDelta: spec.onAssistantDelta } : {},
+        ...spec.onEvent ? { onEvent: spec.onEvent } : {},
+        ...spec.signal ? { signal: spec.signal } : {}
+      });
+    } finally {
+      await closeMcpRefs(tools);
+    }
   }
   async *streamAgent(spec) {
-    const handlers = collectLocalHandlers(spec.tools ?? []);
-    const created = await this.request({
-      method: "POST",
-      path: "/agent-runs",
-      body: serializeAgentSpec(spec, {
-        prompt: spec.prompt,
-        messages: spec.messages
-      })
-    });
-    yield* this.streamRunEvents(created.runId, handlers, spec.signal);
+    const tools = spec.tools ?? [];
+    await resolveLocalRefs(tools, { fetch: this.options.fetch });
+    const handlers = collectLocalHandlers(tools);
+    try {
+      const created = await this.request({
+        method: "POST",
+        path: "/agent-runs",
+        body: serializeAgentSpec(spec, {
+          prompt: spec.prompt,
+          messages: spec.messages
+        })
+      });
+      yield* this.streamRunEvents(created.runId, handlers, spec.signal);
+    } finally {
+      await closeMcpRefs(tools);
+    }
+  }
+  /**
+   * Internal registry of client-resolved tool handlers. Exposed for callers
+   * who drive the run loop manually via `driveRun` / `streamRunEvents`.
+   */
+  collectHandlers(tools) {
+    return collectLocalHandlers(tools);
   }
   // ------------------------------------------------------------- Sessions
   async createSession(spec) {
-    const handlers = collectLocalHandlers(spec.tools ?? []);
+    const tools = spec.tools ?? [];
+    await resolveLocalRefs(tools, { fetch: this.options.fetch });
+    const handlers = collectLocalHandlers(tools);
     const created = await this.request({
       method: "POST",
       path: "/agent-sessions",
       body: serializeAgentSpec(spec)
     });
-    return new AgentSession(this, created.sessionId, handlers);
+    return new AgentSession(this, created.sessionId, handlers, tools);
+  }
+  /**
+   * Re-emit a `local_tool_call` event into the right local handler. Useful
+   * for tests and for users who consume events via `streamAgent` themselves.
+   */
+  async dispatchLocalToolFromEvent(runId, ev, handlers) {
+    return this.dispatchLocalTool(runId, ev, handlers);
   }
   async resumeSession(sessionId, opts = {}) {
     await this.getSessionInfo(sessionId);
-    const handlers = collectLocalHandlers(opts.tools ?? []);
-    return new AgentSession(this, sessionId, handlers, opts.tools);
+    const tools = opts.tools ?? [];
+    if (tools.length > 0) {
+      await resolveLocalRefs(tools, { fetch: this.options.fetch });
+    }
+    const handlers = collectLocalHandlers(tools);
+    return new AgentSession(this, sessionId, handlers, tools);
   }
   async endSession(sessionId) {
     await this.request({
@@ -448,22 +820,49 @@ var MantyxClient = class {
     }
   }
   async dispatchLocalTool(runId, ev, handlers) {
-    const handler = handlers.get(ev.name);
-    if (!handler) {
-      await this.postToolResult(runId, ev.toolUseId, {
-        error: `No local handler registered for tool ${JSON.stringify(ev.name)}`
-      });
-      return;
-    }
+    const kind = ev.kind ?? "local";
     try {
-      const args = handler.parameters ? handler.parameters.parse?.(ev.args) ?? ev.args : ev.args;
-      const out = await handler.execute(args);
-      const resultText = typeof out === "string" ? out : JSON.stringify(out);
-      await this.postToolResult(runId, ev.toolUseId, { result: resultText });
+      let out;
+      if (kind === "a2a_local") {
+        const tool = handlers.a2aTools.get(ev.name);
+        if (!tool) {
+          await this.postToolResult(runId, ev.toolUseId, {
+            error: `No local A2A handler registered for tool ${JSON.stringify(ev.name)}`
+          });
+          return;
+        }
+        const message = typeof ev.args?.message === "string" ? ev.args.message : "";
+        out = await callA2A(tool, { message }, { fetch: this.options.fetch });
+      } else if (kind === "mcp_local") {
+        const serverName = ev.mcpServer ?? "";
+        const mcpToolName = ev.mcpToolName ?? "";
+        const server = handlers.mcpServers.get(serverName);
+        if (!server) {
+          await this.postToolResult(runId, ev.toolUseId, {
+            error: `No local MCP server registered as ${JSON.stringify(serverName)}`
+          });
+          return;
+        }
+        const upstreamName = mcpToolName.startsWith(`${serverName}_`) ? mcpToolName.slice(serverName.length + 1) : mcpToolName;
+        out = await callMcpTool(server, upstreamName, ev.args ?? {});
+      } else {
+        const handler = handlers.localTools.get(ev.name);
+        if (!handler) {
+          await this.postToolResult(runId, ev.toolUseId, {
+            error: `No local handler registered for tool ${JSON.stringify(ev.name)}`
+          });
+          return;
+        }
+        const args = handler.parameters ? handler.parameters.parse?.(ev.args) ?? ev.args : ev.args;
+        const result = await handler.execute(args);
+        out = typeof result === "string" ? result : JSON.stringify(result);
+      }
+      await this.postToolResult(runId, ev.toolUseId, { result: out });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      const handlerName = describeHandlerName(ev);
       await this.postToolResult(runId, ev.toolUseId, {
-        error: new MantyxToolError(handler.name, message).message
+        error: new MantyxToolError(handlerName, message).message
       });
     }
   }
@@ -541,22 +940,18 @@ var AgentSession = class {
   id;
   client;
   handlers;
-  toolsForResume;
-  constructor(client, id, handlers, toolsForResume) {
+  tools;
+  constructor(client, id, handlers, tools) {
     this.client = client;
     this.id = id;
     this.handlers = handlers;
-    this.toolsForResume = toolsForResume;
+    this.tools = tools ?? [];
   }
   async send(prompt, opts = {}) {
     const created = await this.client.request({
       method: "POST",
       path: `/agent-sessions/${encodeURIComponent(this.id)}/messages`,
-      body: {
-        prompt,
-        ...this.toolsForResume ? { tools: serializeToolRefs(this.toolsForResume) } : {},
-        ...opts.metadata && Object.keys(opts.metadata).length > 0 ? { metadata: opts.metadata } : {}
-      }
+      body: this.buildSessionMessageBody(prompt, opts)
     });
     return this.client.driveRun(created.runId, this.handlers, {
       ...opts.onAssistantDelta ? { onAssistantDelta: opts.onAssistantDelta } : {},
@@ -567,14 +962,22 @@ var AgentSession = class {
     const created = await this.client.request({
       method: "POST",
       path: `/agent-sessions/${encodeURIComponent(this.id)}/messages`,
-      body: {
-        prompt,
-        ...this.toolsForResume ? { tools: serializeToolRefs(this.toolsForResume) } : {},
-        ...opts.metadata && Object.keys(opts.metadata).length > 0 ? { metadata: opts.metadata } : {}
-      }
+      body: this.buildSessionMessageBody(prompt, opts)
     });
     yield* this.client.streamRunEvents(created.runId, this.handlers, opts.signal);
   }
+  buildSessionMessageBody(prompt, opts) {
+    const body = { prompt };
+    if (this.tools.length > 0) body.tools = serializeToolRefs(this.tools);
+    if (opts.metadata && Object.keys(opts.metadata).length > 0) body.metadata = opts.metadata;
+    if (opts.reasoningLevel !== void 0) {
+      body.reasoningLevel = normalizeReasoningLevel(opts.reasoningLevel);
+    }
+    if (opts.outputSchema !== void 0) {
+      body.outputSchema = normalizeOutputSchema(opts.outputSchema);
+    }
+    return body;
+  }
   async history() {
     const info = await this.client.getSessionInfo(this.id);
     return info.messages;
@@ -583,7 +986,11 @@ var AgentSession = class {
     return this.client.getSessionInfo(this.id);
   }
   async end() {
-    await this.client.endSession(this.id);
+    try {
+      await this.client.endSession(this.id);
+    } finally {
+      await closeMcpRefs(this.tools);
+    }
   }
 };
 function serializeAgentSpec(spec, extra = {}) {
@@ -597,6 +1004,12 @@ function serializeAgentSpec(spec, extra = {}) {
   if (spec.agentId) body.agentId = spec.agentId;
   if (spec.name) body.name = spec.name;
   if (spec.modelId) body.modelId = spec.modelId;
+  if (spec.reasoningLevel !== void 0) {
+    body.reasoningLevel = normalizeReasoningLevel(spec.reasoningLevel);
+  }
+  if (spec.outputSchema !== void 0) {
+    body.outputSchema = normalizeOutputSchema(spec.outputSchema);
+  }
   if (spec.budgets) body.budgets = spec.budgets;
   if (spec.metadata && Object.keys(spec.metadata).length > 0) body.metadata = spec.metadata;
   if (extra.prompt !== void 0) body.prompt = extra.prompt;
@@ -605,29 +1018,183 @@ function serializeAgentSpec(spec, extra = {}) {
 }
 function serializeToolRefs(tools) {
   return tools.map((t) => {
-    if (t.kind === "mantyx") return { kind: "mantyx", id: t.id };
-    if (t.kind === "mantyx_plugin") return { kind: "mantyx_plugin", name: t.name };
-    return {
-      kind: "local",
-      name: t.name,
-      description: t.description,
-      parameters: toToolParametersWire(t.parameters)
-    };
+    switch (t.kind) {
+      case "mantyx":
+        return { kind: "mantyx", id: t.id };
+      case "mantyx_plugin":
+        return { kind: "mantyx_plugin", name: t.name };
+      case "local":
+        return {
+          kind: "local",
+          name: t.name,
+          description: t.description,
+          parameters: toToolParametersWire(t.parameters)
+        };
+      case "a2a":
+        return {
+          kind: "a2a",
+          name: t.name,
+          ...t.description !== void 0 ? { description: t.description } : {},
+          agentCardUrl: t.agentCardUrl,
+          ...t.headers ? { headers: { ...t.headers } } : {},
+          ...t.contextId ? { contextId: t.contextId } : {}
+        };
+      case "a2a_local": {
+        const card = t._resolvedCard;
+        if (!card) {
+          throw new MantyxError(
+            `defineLocalA2A(${JSON.stringify(t.name)}): agent card has not been resolved yet (was \`runAgent\` / \`createSession\` skipped?)`
+          );
+        }
+        return {
+          kind: "a2a_local",
+          name: t.name,
+          // The wire ships the resolved A2A Agent Card. Shallow-clone so
+          // consumers can mutate the input later without affecting the
+          // wire payload.
+          agentCard: { ...card }
+        };
+      }
+      case "mcp":
+        return {
+          kind: "mcp",
+          name: t.name,
+          url: t.url,
+          ...t.headers ? { headers: { ...t.headers } } : {},
+          ...t.toolFilter ? { toolFilter: [...t.toolFilter] } : {}
+        };
+      case "mcp_local": {
+        const resolved = t._resolved;
+        if (!resolved) {
+          throw new MantyxError(
+            `defineLocalMcp(${JSON.stringify(t.name)}): MCP server has not been initialised yet`
+          );
+        }
+        const tools2 = resolved.tools.map((tool) => {
+          const wire = {
+            name: prefixedMcpToolName(t.name, tool.name),
+            inputSchema: tool.inputSchema
+          };
+          if (typeof tool.description === "string") wire.description = tool.description;
+          if (tool.annotations) wire.annotations = tool.annotations;
+          return wire;
+        });
+        return {
+          kind: "mcp_local",
+          name: t.name,
+          serverInfo: { ...resolved.serverInfo },
+          tools: tools2
+        };
+      }
+    }
   });
 }
 function collectLocalHandlers(tools) {
-  const map = /* @__PURE__ */ new Map();
+  const localTools = /* @__PURE__ */ new Map();
+  const a2aTools = /* @__PURE__ */ new Map();
+  const mcpServers = /* @__PURE__ */ new Map();
   for (const t of tools) {
-    if (isLocalTool(t)) map.set(t.name, t);
+    if (isLocalTool(t)) {
+      localTools.set(t.name, t);
+    } else if (isLocalA2ATool(t)) {
+      a2aTools.set(t.name, t);
+    } else if (isLocalMcpServer(t)) {
+      mcpServers.set(t.name, t);
+    }
+  }
+  return { localTools, a2aTools, mcpServers };
+}
+function describeHandlerName(ev) {
+  if (ev.kind === "mcp_local" && ev.mcpServer && ev.mcpToolName) {
+    return `${ev.mcpServer}/${ev.mcpToolName}`;
+  }
+  return ev.name;
+}
+function normalizeReasoningLevel(level) {
+  if (typeof level === "number") {
+    if (!Number.isFinite(level) || level < 0 || level > 100) {
+      throw new MantyxError(
+        `reasoningLevel must be a string anchor or an integer in 0..100, got ${level}`
+      );
+    }
+    return Math.trunc(level);
+  }
+  if (level === "off" || level === "low" || level === "medium" || level === "high") {
+    return level;
+  }
+  throw new MantyxError(
+    `reasoningLevel must be one of "off" | "low" | "medium" | "high" or a number 0..100, got ${JSON.stringify(level)}`
+  );
+}
+var OUTPUT_SCHEMA_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+var OUTPUT_SCHEMA_MAX_BYTES = 32 * 1024;
+function normalizeOutputSchema(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MantyxError(
+      `outputSchema must be an object of shape { name?, schema }, got ${JSON.stringify(value)}`
+    );
+  }
+  const out = {};
+  if (value.name !== void 0) {
+    if (typeof value.name !== "string" || !OUTPUT_SCHEMA_NAME_RE.test(value.name)) {
+      throw new MantyxError(
+        `outputSchema.name must match /^[a-zA-Z0-9_-]{1,64}$/, got ${JSON.stringify(value.name)}`
+      );
+    }
+    out.name = value.name;
+  }
+  const schema = value.schema;
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new MantyxError(
+      `outputSchema.schema must be a non-null JSON object (the JSON Schema root)`
+    );
+  }
+  out.schema = schema;
+  let serialized;
+  try {
+    serialized = JSON.stringify(out);
+  } catch (err) {
+    throw new MantyxError(
+      `outputSchema is not JSON-serialisable: ${err.message ?? String(err)}`
+    );
+  }
+  if (serialized.length > OUTPUT_SCHEMA_MAX_BYTES) {
+    throw new MantyxError(
+      `outputSchema serialised JSON is ${serialized.length} bytes; the server enforces a 32 KB limit`
+    );
+  }
+  return out;
+}
+function parseRunOutput(result, validator) {
+  let parsed;
+  try {
+    parsed = JSON.parse(result.text);
+  } catch (err) {
+    throw new MantyxParseError(
+      `Run ${result.runId} returned non-JSON text; cannot satisfy outputSchema`,
+      result.text,
+      { cause: err }
+    );
+  }
+  if (validator) {
+    try {
+      return validator(parsed);
+    } catch (err) {
+      throw new MantyxParseError(
+        `Run ${result.runId} output failed validation: ${err.message ?? String(err)}`,
+        result.text,
+        { cause: err }
+      );
+    }
   }
-  return map;
+  return parsed;
 }
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
 // src/version.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentSession,
@@ -636,13 +1203,21 @@ var SDK_VERSION = "0.2.0";
   MantyxClient,
   MantyxError,
   MantyxNetworkError,
+  MantyxParseError,
   MantyxRunError,
   MantyxToolError,
   SDK_VERSION,
+  defineLocalA2A,
+  defineLocalMcp,
   defineLocalTool,
+  isLocalA2ATool,
+  isLocalMcpServer,
   isLocalTool,
+  mantyxA2A,
+  mantyxMcp,
   mantyxPluginTool,
   mantyxTool,
+  parseRunOutput,
   readSseStream,
   toToolParametersWire,
   zodToJsonSchema