@mantyx/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add support for a2a, mcp and local versions
+
+### Fixed
+
+- Changelo
+
+## [0.2.0] — 2026-05-04
+
 ### Fixed
 
 - Use correct default base url
@@ -21,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.0] — 2026-05-02
 
-[unreleased]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.1.1..HEAD
+[unreleased]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.2.0..HEAD
+[0.2.0]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.1.1..v0.2.0
 [0.1.1]: https://github.com/mantyx-io/mantyx-sdk/compare/v0.1.0..v0.1.1
 [0.1.0]: https://github.com/mantyx-io/mantyx-sdk/releases/tag/v0.1.0

package/README.md

@@ -6,13 +6,20 @@ locally-executed tools, run them remotely, and stream events back into your
 process.
 
 - LLM loop runs on MANTYX (BYOK or platform-hosted models).
-- Server-side tools (`mantyx`, `mantyx_plugin`) execute inside MANTYX.
-- Local tools execute inside *your* process; the SDK shuttles inputs and
-  outputs over an SSE stream + a tool-result POST.
+- Server-resolved tools (`mantyx`, `mantyx_plugin`, `a2a`, `mcp`) execute
+  inside MANTYX — including remote Agent2Agent peers and remote MCP servers.
+- Client-resolved tools (`local`, `a2a_local`, `mcp_local`) execute inside
+  *your* process; the SDK shuttles inputs and outputs over an SSE stream +
+  a tool-result POST.
+- Tunable provider thinking via `reasoningLevel` (string anchors or 0–100).
 - One-shot runs and multi-turn sessions, both with persisted observability.
 - Authenticated with a single workspace API key.
 
-For background, see the [agent-runs protocol spec](./docs/agent-runs-protocol.md).
+For background, see the [agent-runs protocol spec](./docs/agent-runs-protocol.md)
+and the messaging-layer reference in [`docs/wire-protocol.md`](./docs/wire-protocol.md)
+— the latter pins down the exact `local_tool_call` event shape and the
+resolved data structures (`a2a_local` Agent Card, `mcp_local` `Tool[]`)
+that this SDK ships.
 
 ## Install
 
@@ -22,9 +29,11 @@ npm install @mantyx/sdk zod
 # or: yarn add @mantyx/sdk zod
 ```
 
-Requires Node.js 18.17+ (for `fetch` and `ReadableStream`). `zod` is the only
-runtime dependency the SDK adds; the rest is the standard library and your
-own modules.
+Requires Node.js 18.17+ (for `fetch` and `ReadableStream`). The SDK depends
+on `zod` (parameter schemas) and `@modelcontextprotocol/sdk` (the official
+MCP TypeScript SDK that powers `defineLocalMcp`'s stdio + Streamable HTTP
+transports). The MCP SDK is loaded lazily — apps that never use
+`defineLocalMcp` don't pay its startup cost.
 
 ## Quickstart
 
@@ -103,6 +112,190 @@ Notes:
 The same `agentId` field works on `client.createSession({ ... })` for
 multi-turn conversations against a persisted agent.
 
+## Agent2Agent delegation
+
+Hand a turn off to another agent — either a remote peer MANTYX dials directly
+(`mantyxA2A`) or a peer that only the SDK can reach (`defineLocalA2A`). The
+model addresses both with the same `{ message: string }` argument shape, so
+an agent prompt that uses one works unchanged with the other.
+
+`defineLocalA2A` is fully URL-driven: pass the Agent Card URL and the SDK
+takes care of the rest — fetching the card on the first run, shipping it
+inline as part of the spec, and POSTing JSON-RPC `message/send` to the
+card's `url` whenever MANTYX emits a `local_tool_call`. You don't write any
+A2A code yourself.
+
+```ts
+import { MantyxClient, defineLocalA2A, mantyxA2A } from "@mantyx/sdk";
+
+const client = new MantyxClient({ apiKey: "...", workspaceSlug: "acme" });
+
+await client.runAgent({
+  systemPrompt: "You are a helpful router. Delegate billing to billing_agent.",
+  prompt: "Why was I charged twice last month?",
+  tools: [
+    // Public peer MANTYX dials directly.
+    mantyxA2A({
+      name: "billing_agent",
+      description: "Delegate billing questions to the Acme billing agent.",
+      agentCardUrl: "https://billing.acme.com/.well-known/agent-card.json",
+      headers: { Authorization: `Bearer ${process.env.BILLING_TOKEN}` },
+    }),
+    // Intranet peer the SDK reaches on MANTYX's behalf — URL only.
+    defineLocalA2A({
+      name: "intranet_hr",
+      agentCardUrl: "https://hr.intranet.acme/.well-known/agent-card.json",
+      headers: { Authorization: `Bearer ${process.env.HR_TOKEN}` },
+    }),
+  ],
+});
+```
+
+The same `headers` are sent on both the card fetch *and* every subsequent
+`message/send` POST, which is typically what intranet peers want. The SDK
+caches the resolved card on the tool ref for the duration of the run /
+session — re-construct the ref to force a refetch.
+
+> **Headers and secrets.** The `headers` you pass to `mantyxA2A` are forwarded
+> as-is. For long-lived credentials, register the peer as a workspace
+> `ExternalAgent` instead — those headers support `{{secret:NAME}}`
+> placeholders. Use `mantyxA2A` for short-lived, per-run tokens minted by
+> your application.
+
+### Exposing an agent over A2A
+
+The inverse direction also works: wrap a MANTYX agent (ephemeral spec or a
+persisted `agentId`) and serve it as an Agent2Agent peer using the official
+[`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) library. Other
+agents can then discover it at `/.well-known/agent-card.json` and call
+`message/send` over JSON-RPC — including MANTYX agents elsewhere in your
+estate consuming this one via `mantyxA2A` or `defineLocalA2A`.
+
+```ts
+import { MantyxClient } from "@mantyx/sdk";
+import { serveAgentOverA2A } from "@mantyx/sdk/a2a-server";
+
+const client = new MantyxClient({ apiKey: "...", workspaceSlug: "acme" });
+
+const handle = await serveAgentOverA2A({
+  client,
+  agent: { agentId: "agent_cm6abc123" }, // or { systemPrompt, modelId, tools }
+  port: 4000,
+  agentCard: {
+    name: "Acme Support",
+    description: "Customer support questions.",
+    protocolVersion: "0.3.0",
+    version: "1.0.0",
+    url: "http://localhost:4000",
+    skills: [{ id: "support", name: "Support", tags: ["support"] }],
+    capabilities: { streaming: true, pushNotifications: false },
+    defaultInputModes: ["text"],
+    defaultOutputModes: ["text"],
+  },
+});
+
+console.log(`A2A peer up on ${handle.url}`);
+// later: await handle.close();
+```
+
+`@a2a-js/sdk` and `express` are declared as **optional peer dependencies**,
+so apps that don't expose an A2A server pay zero bundle cost. Install them
+on demand:
+
+```bash
+npm install @a2a-js/sdk express
+```
+
+Each unique A2A `contextId` opens a long-lived MANTYX session by default, so
+multi-turn `message/send` calls share conversational history. Pass
+`conversation: "stateless"` to reduce every A2A request to a one-shot
+`runAgent` call.
+
+For lower-level integration (mounting the executor in your own Express /
+Fastify / Connect app), `@mantyx/sdk/a2a-server` also exports a
+`MantyxAgentExecutor` class implementing `@a2a-js/sdk/server`'s
+`AgentExecutor` interface.
+
+## MCP connectors
+
+Expose every tool published by an MCP server to the agent loop in one go,
+without listing them individually.
+
+```ts
+import { MantyxClient, mantyxMcp, defineLocalMcp } from "@mantyx/sdk";
+
+const client = new MantyxClient({ apiKey: "...", workspaceSlug: "acme" });
+
+await client.runAgent({
+  systemPrompt: "You are a developer assistant with GitHub + filesystem access.",
+  prompt: "Summarize the latest 5 issues on octocat/hello-world.",
+  tools: [
+    // Remote MCP server (Streamable HTTP) — MANTYX lists the catalog at run
+    // start and proxies every call. Tools surface as `github_<tool>`.
+    mantyxMcp({
+      name: "github",
+      url: "https://mcp.github.com/v1",
+      headers: { Authorization: `Bearer ${process.env.GH_PAT}` },
+      toolFilter: ["search_issues", "get_repo"],
+    }),
+    // Local MCP server — fully managed by the SDK. Pass either a
+    // Streamable HTTP `url` *or* an stdio `command`; the SDK opens the
+    // transport, runs `Initialize` + `tools/list`, ships the resolved
+    // catalog inline, and forwards every invocation to `tools/call`. The
+    // model sees `<server>_<tool>` (`fs_read_file`, `fs_list_dir`, …) —
+    // same shape as `mantyxMcp` above.
+
+    // (a) Streamable HTTP MCP server.
+    defineLocalMcp({
+      name: "fs",
+      url: "http://localhost:8080/mcp",
+      headers: { Authorization: `Bearer ${process.env.FS_TOKEN}` },
+    }),
+
+    // (b) stdio MCP server — the SDK spawns the process for you.
+    // defineLocalMcp({
+    //   name: "fs",
+    //   command: "mcp-server-filesystem",
+    //   args: ["/workspace"],
+    //   env: { LOG_LEVEL: "info" },
+    // }),
+  ],
+});
+```
+
+The MCP transport is opened lazily on the first `runAgent` / first
+`session.send`, kept warm for subsequent calls within the same run /
+session, and closed when the run completes or `session.end()` is called.
+If the MCP server can't be reached, the SDK throws before submitting the
+spec — you get the failure synchronously rather than mid-conversation.
+
+If a remote (`kind: "mcp"`) MCP server is unreachable when the run starts,
+MANTYX still exposes a single `<server>_unavailable` stub so the model can
+tell the user why the connector is missing.
+
+## Reasoning effort (`reasoningLevel`)
+
+Crank up provider thinking on reasoning models without writing
+provider-specific code:
+
+```ts
+await client.runAgent({
+  systemPrompt: "...",
+  prompt: "Plan a multi-week migration.",
+  reasoningLevel: "high", // or 80, etc.
+});
+```
+
+| Form         | Values                                       | Notes |
+| ------------ | -------------------------------------------- | ----- |
+| String       | `"off"`, `"low"`, `"medium"`, `"high"`        | Snaps to the same anchors the web composer uses (Fast=30, Moderate=50, Smart=80; off=0). |
+| Number       | integer `0`–`100`                             | `0` explicitly disables provider thinking on reasoning models. |
+
+The server maps this onto each LLM's native dial — `reasoning.effort` for
+OpenAI, `thinkingConfig` for Gemini, extended-thinking budget for Anthropic.
+Non-reasoning models silently ignore it. On sessions, `reasoningLevel`
+inherits from the session and can be overridden per `session.send`.
+
 ## Picking a model
 
 ```ts
@@ -248,11 +441,15 @@ interface MantyxClientOptions {
 
 ### Tools
 
-| Helper                     | Use case                                                     |
-| -------------------------- | ------------------------------------------------------------ |
-| `defineLocalTool(opts)`    | Define a local tool with a Zod parameter schema and handler. |
-| `mantyxTool(id)`           | Reference an existing MANTYX tool by id.                     |
-| `mantyxPluginTool(name)`   | Reference an installed platform plugin tool by name.         |
+| Helper                     | Use case                                                                |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `defineLocalTool(opts)`    | Define a local tool with a Zod parameter schema and handler.            |
+| `defineLocalA2A(opts)`     | Local Agent2Agent peer — pass an `agentCardUrl`; the SDK fetches the card and speaks `message/send` for you. |
+| `defineLocalMcp(opts)`     | Local MCP server — pass either a Streamable HTTP `url` or an stdio `command`; the SDK runs `Initialize` + `tools/list` + `tools/call` for you. |
+| `mantyxTool(id)`           | Reference an existing MANTYX tool by id.                                |
+| `mantyxPluginTool(name)`   | Reference an installed platform plugin tool by name.                    |
+| `mantyxA2A(opts)`          | Remote Agent2Agent peer reachable from MANTYX (server-resolved).        |
+| `mantyxMcp(opts)`          | Remote MCP server (Streamable HTTP) MANTYX dials and proxies for you.   |
 
 ### Errors
 
@@ -272,6 +469,8 @@ Self-contained example projects live under [`examples/`](./examples/):
 - `examples/mixed-tools` — combines local, MANTYX, and plugin tools.
 - `examples/streaming` — token streaming to stdout.
 - `examples/list-models` — model catalog + pick-and-run.
+- `examples/a2a-tools` — remote (`mantyxA2A`) + local (`defineLocalA2A`) Agent2Agent peers.
+- `examples/mcp-tools` — remote (`mantyxMcp`) + local (`defineLocalMcp`) MCP servers.
 
 Each example is its own project (`package.json`, `tsconfig.json`, `README.md`)
 so you can copy any one of them out of the repo and run it standalone.

package/dist/a2a-server.cjs

@@ -0,0 +1,404 @@
+"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)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  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/a2a-server.ts
+var a2a_server_exports = {};
+__export(a2a_server_exports, {
+  MantyxAgentExecutor: () => MantyxAgentExecutor,
+  serveAgentOverA2A: () => serveAgentOverA2A
+});
+module.exports = __toCommonJS(a2a_server_exports);
+
+// src/errors.ts
+var MantyxError = class extends Error {
+  code;
+  status;
+  hint;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "MantyxError";
+    this.code = opts.code ?? "mantyx_error";
+    this.status = opts.status;
+    this.hint = opts.hint;
+  }
+};
+var MantyxRunError = class extends MantyxError {
+  runId;
+  subtype;
+  constructor(runId, subtype, message) {
+    super(message, { code: subtype });
+    this.name = "MantyxRunError";
+    this.runId = runId;
+    this.subtype = subtype;
+  }
+};
+
+// src/zod-to-json-schema.ts
+var import_zod = require("zod");
+
+// src/a2a-server.ts
+var MantyxAgentExecutor = class {
+  client;
+  agent;
+  conversation;
+  maxSessions;
+  onAssistantDelta;
+  /** contextId -> live MANTYX session. Maintained as an LRU map. */
+  sessions = /* @__PURE__ */ new Map();
+  /** taskIds we've been asked to cancel; checked between turns. */
+  cancelled = /* @__PURE__ */ new Set();
+  /** Pending AbortControllers per task, used for cooperative cancel. */
+  inFlight = /* @__PURE__ */ new Map();
+  constructor(options) {
+    if (!options.client) {
+      throw new MantyxError("MantyxAgentExecutor: `client` is required");
+    }
+    validateAgentSpec(options.agent);
+    this.client = options.client;
+    this.agent = options.agent;
+    this.conversation = options.conversation ?? "auto";
+    this.maxSessions = options.maxSessions ?? 1024;
+    if (options.onAssistantDelta) this.onAssistantDelta = options.onAssistantDelta;
+  }
+  async execute(requestContext, eventBus) {
+    const { userMessage, taskId, contextId, task } = requestContext;
+    const userText = extractText(userMessage);
+    const abort = new AbortController();
+    this.inFlight.set(taskId, abort);
+    try {
+      if (!task) {
+        eventBus.publish({
+          kind: "task",
+          id: taskId,
+          contextId,
+          status: { state: "submitted", timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+          history: [userMessage]
+        });
+      }
+      eventBus.publish(statusUpdate(taskId, contextId, "working", false));
+      if (this.cancelled.has(taskId)) {
+        eventBus.publish(statusUpdate(taskId, contextId, "canceled", true));
+        eventBus.finished();
+        return;
+      }
+      const onDelta = (delta) => {
+        if (this.onAssistantDelta) {
+          this.onAssistantDelta(delta, requestContext, eventBus);
+          return;
+        }
+        eventBus.publish(deltaStatusUpdate(taskId, contextId, delta));
+      };
+      let result;
+      try {
+        result = await this.runOnce(contextId, userText, onDelta, abort.signal);
+      } catch (err) {
+        eventBus.publish(
+          completedStatusUpdate(
+            taskId,
+            contextId,
+            this.cancelled.has(taskId) ? "canceled" : "failed",
+            errorText(err)
+          )
+        );
+        eventBus.finished();
+        return;
+      }
+      eventBus.publish(completedStatusUpdate(taskId, contextId, "completed", result.text ?? ""));
+      eventBus.finished();
+    } finally {
+      this.inFlight.delete(taskId);
+      this.cancelled.delete(taskId);
+    }
+  }
+  async cancelTask(taskId, eventBus) {
+    this.cancelled.add(taskId);
+    const ctrl = this.inFlight.get(taskId);
+    if (ctrl) ctrl.abort();
+    void eventBus;
+  }
+  /**
+   * Close every cached session. Idempotent. Safe to call from server shutdown
+   * paths.
+   */
+  async close() {
+    const sessions = Array.from(this.sessions.values());
+    this.sessions.clear();
+    await Promise.allSettled(sessions.map((s) => s.end()));
+  }
+  // -------------------------------------------------- private session helpers
+  async runOnce(contextId, prompt, onAssistantDelta, signal) {
+    if (this.conversation === "stateless") {
+      const runSpec = {
+        ...specForRun(this.agent),
+        prompt,
+        onAssistantDelta,
+        signal
+      };
+      return this.client.runAgent(runSpec);
+    }
+    const session = await this.getOrCreateSession(contextId);
+    return session.send(prompt, { onAssistantDelta, signal });
+  }
+  async getOrCreateSession(contextId) {
+    const existing = this.sessions.get(contextId);
+    if (existing) {
+      this.sessions.delete(contextId);
+      this.sessions.set(contextId, existing);
+      return existing;
+    }
+    const sessionSpec = specForSession(this.agent, contextId);
+    const session = await this.client.createSession(sessionSpec);
+    this.sessions.set(contextId, session);
+    await this.evictIfNeeded();
+    return session;
+  }
+  async evictIfNeeded() {
+    while (this.sessions.size > this.maxSessions) {
+      const oldestKey = this.sessions.keys().next().value;
+      if (!oldestKey) break;
+      const oldest = this.sessions.get(oldestKey);
+      this.sessions.delete(oldestKey);
+      try {
+        await oldest.end();
+      } catch {
+      }
+    }
+  }
+};
+async function serveAgentOverA2A(options) {
+  const a2a = await loadServerSdk();
+  const expressMod = await loadExpress();
+  const executor = new MantyxAgentExecutor(options);
+  const requestHandler = new a2a.DefaultRequestHandler(
+    options.agentCard,
+    new a2a.InMemoryTaskStore(),
+    executor
+  );
+  const app = expressMod();
+  app.use(expressMod.json());
+  const cardPath = options.agentCardPath ?? "/.well-known/agent-card.json";
+  const jsonRpcPath = options.jsonRpcPath ?? "/";
+  const restPath = options.restPath === void 0 ? "/v1" : options.restPath;
+  app.use(
+    cardPath,
+    a2a.expressApp.agentCardHandler({ agentCardProvider: requestHandler })
+  );
+  if (restPath !== false) {
+    app.use(
+      restPath,
+      a2a.expressApp.restHandler({
+        requestHandler,
+        userBuilder: a2a.expressApp.UserBuilder.noAuthentication
+      })
+    );
+  }
+  app.use(
+    jsonRpcPath,
+    a2a.expressApp.jsonRpcHandler({
+      requestHandler,
+      userBuilder: a2a.expressApp.UserBuilder.noAuthentication
+    })
+  );
+  const port = options.port ?? 0;
+  const host = options.host ?? "0.0.0.0";
+  const server = app.listen(port, host);
+  await new Promise((resolve, reject) => {
+    server.once("listening", resolve);
+    server.once("error", reject);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw new MantyxError("serveAgentOverA2A: failed to bind HTTP listener");
+  }
+  return {
+    port: address.port,
+    url: `http://${displayHost(host)}:${address.port}`,
+    close: async () => {
+      await new Promise(
+        (resolve, reject) => server.close((err) => err ? reject(err) : resolve())
+      );
+      await executor.close();
+    }
+  };
+}
+function statusUpdate(taskId, contextId, state, final) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: { state, timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+    final
+  };
+}
+function deltaStatusUpdate(taskId, contextId, delta) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state: "working",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: {
+        kind: "message",
+        messageId: randomMessageId(),
+        role: "agent",
+        parts: [{ kind: "text", text: delta }],
+        contextId,
+        taskId
+      }
+    },
+    final: false
+  };
+}
+function completedStatusUpdate(taskId, contextId, state, text) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      message: {
+        kind: "message",
+        messageId: randomMessageId(),
+        role: "agent",
+        parts: [{ kind: "text", text }],
+        contextId,
+        taskId
+      }
+    },
+    final: true
+  };
+}
+function extractText(message) {
+  if (!message) return "";
+  const parts = message.parts ?? [];
+  const out = [];
+  for (const p of parts) {
+    if (p.kind === "text") {
+      const t = p.text;
+      if (typeof t === "string") out.push(t);
+    }
+  }
+  return out.join("\n");
+}
+function specForRun(spec) {
+  const out = {};
+  if (spec.agentId) out.agentId = spec.agentId;
+  if (spec.systemPrompt) out.systemPrompt = spec.systemPrompt;
+  if (spec.modelId) out.modelId = spec.modelId;
+  if (spec.tools) out.tools = spec.tools;
+  if (spec.reasoningLevel !== void 0) out.reasoningLevel = spec.reasoningLevel;
+  if (spec.metadata) out.metadata = spec.metadata;
+  if (spec.budgets) out.budgets = spec.budgets;
+  if (spec.name) out.name = spec.name;
+  return out;
+}
+function specForSession(spec, contextId) {
+  const out = {};
+  if (spec.agentId) out.agentId = spec.agentId;
+  if (spec.systemPrompt) out.systemPrompt = spec.systemPrompt;
+  if (spec.modelId) out.modelId = spec.modelId;
+  if (spec.tools) out.tools = spec.tools;
+  if (spec.reasoningLevel !== void 0) out.reasoningLevel = spec.reasoningLevel;
+  const meta = { ...spec.metadata ?? {} };
+  if (!meta.a2a_context_id) meta.a2a_context_id = contextId;
+  out.metadata = meta;
+  if (spec.budgets) out.budgets = spec.budgets;
+  if (spec.name) out.name = spec.name;
+  return out;
+}
+function validateAgentSpec(spec) {
+  if (!spec.agentId && (!spec.systemPrompt || spec.systemPrompt.length === 0)) {
+    throw new MantyxError(
+      "MantyxAgentExecutor: `agent.agentId` or `agent.systemPrompt` is required"
+    );
+  }
+}
+function errorText(err) {
+  if (err instanceof MantyxRunError) {
+    return `MANTYX run failed (${err.subtype ?? "unknown"}): ${err.message}`;
+  }
+  if (err instanceof Error) return err.message;
+  try {
+    return String(err);
+  } catch {
+    return "unknown error";
+  }
+}
+function randomMessageId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function displayHost(host) {
+  if (host === "0.0.0.0" || host === "::") return "localhost";
+  return host;
+}
+async function loadExpress() {
+  try {
+    const mod = await import("express");
+    return "default" in mod ? mod.default : mod;
+  } catch (err) {
+    throw new MantyxError(
+      "serveAgentOverA2A: `express` is required but not installed. Run `npm install express @a2a-js/sdk` to enable the A2A server."
+    );
+  }
+}
+async function loadServerSdk() {
+  let server;
+  let express;
+  try {
+    server = await import("@a2a-js/sdk/server");
+  } catch (err) {
+    throw new MantyxError(
+      "serveAgentOverA2A: `@a2a-js/sdk` is required but not installed. Run `npm install @a2a-js/sdk express` to enable the A2A server."
+    );
+  }
+  try {
+    express = await import("@a2a-js/sdk/server/express");
+  } catch (err) {
+    throw new MantyxError(
+      "serveAgentOverA2A: `@a2a-js/sdk/server/express` could not be loaded; ensure the installed `@a2a-js/sdk` is at least v0.3."
+    );
+  }
+  return {
+    DefaultRequestHandler: server.DefaultRequestHandler,
+    InMemoryTaskStore: server.InMemoryTaskStore,
+    expressApp: express
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MantyxAgentExecutor,
+  serveAgentOverA2A
+});
+//# sourceMappingURL=a2a-server.cjs.map