@ai-matrx/agents 0.28.1 → 0.29.1

package/dist/portable/mcp.d.cts

@@ -0,0 +1,81 @@
+import { CredentialsPort } from '@ai-matrx/data';
+import { M as MatrxTransport } from '../transport-CxD0fL8p.cjs';
+import { J as JsonValue, P as PortableAgentBundle } from '../types.generated-BydVlqDC.cjs';
+
+/**
+ * `@ai-matrx/agents/portable/mcp` — an agent's server tools as an MCP server.
+ *
+ * `createAgentToolsMcpHandler` answers MCP JSON-RPC (`initialize`,
+ * `tools/list`, `tools/call`, `ping`) for ONE agent. `tools/list` is the
+ * bundle's server tools (resolved by the realtime-tools funnel on the server);
+ * `tools/call` runs the tool through `POST /ai/tools/execute`, which
+ * re-resolves the agent's set and refuses anything outside it, and writes the
+ * same `cx_tool_call` row a turn-based call writes.
+ *
+ * Every call reads the credential FRESH from the `CredentialsPort` and carries
+ * `X-Organization-Id` — nothing is cached, and the token never leaves this
+ * process (the CLI only ever sees a URL). Signed out, a call answers one plain
+ * sentence instead of failing obscurely.
+ *
+ * Transport-neutral: the host feeds it the parsed JSON body of each HTTP POST
+ * (MCP "streamable HTTP") and writes back what it returns. Pure: no Node, no
+ * React, no I/O at import.
+ */
+
+/** The MCP protocol revisions this handler speaks, newest first. */
+declare const AGENT_TOOLS_MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+/** The server name the CLIs see (`mcp__matrx-agent__<tool>` in Claude Code). */
+declare const AGENT_TOOLS_MCP_SERVER_NAME = "matrx-agent";
+/** What a signed-out tool call answers. */
+declare const SIGNED_OUT_TOOL_MESSAGE = "Sign in to AI Matrx to use this tool.";
+/** What a call with no organization answers. */
+declare const NO_ORGANIZATION_TOOL_MESSAGE = "Pick an organization in AI Matrx to use this tool.";
+interface AgentToolsMcpOptions {
+    /** The bundle the session loaded — its `tools`, agent/version identity and `surface`. */
+    bundle: Pick<PortableAgentBundle, "agent_id" | "version_id" | "name" | "tools" | "surface">;
+    /** The credential source, read fresh per call. `null`/absent = signed out. */
+    credentials?: CredentialsPort | null;
+    /** The organization every call runs in (value or per-call getter). */
+    organizationId?: string | null | (() => string | null | undefined);
+    /** AI Matrx server base URL, no trailing slash. */
+    baseUrl: string;
+    /**
+     * One conversation id for the whole coding session, so its tool calls group
+     * under one `cx_conversation`. Default: a fresh id per handler.
+     */
+    conversationId?: string;
+    /** Test seam: replaces the transport built from the options above. */
+    transport?: MatrxTransport;
+    /** Every tool call's outcome, for the host's transcript or logs. */
+    onToolCall?: (event: {
+        name: string;
+        ok: boolean;
+        callId: string;
+    }) => void;
+}
+/** A JSON-RPC message, structurally. */
+interface McpJsonRpcMessage {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+/** What the host writes back: HTTP status, plus a JSON body when there is one. */
+interface McpHttpReply {
+    status: number;
+    body?: unknown;
+}
+interface AgentToolsMcpHandler {
+    /** Handle one parsed HTTP POST body (a message or a batch). */
+    handle(body: unknown): Promise<McpHttpReply>;
+    /** The tools `tools/list` returns, in MCP shape. */
+    listTools(): McpToolDescriptor[];
+}
+interface McpToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: Record<string, JsonValue>;
+}
+declare function createAgentToolsMcpHandler(options: AgentToolsMcpOptions): AgentToolsMcpHandler;
+
+export { AGENT_TOOLS_MCP_PROTOCOL_VERSIONS, AGENT_TOOLS_MCP_SERVER_NAME, type AgentToolsMcpHandler, type AgentToolsMcpOptions, type McpHttpReply, type McpJsonRpcMessage, type McpToolDescriptor, NO_ORGANIZATION_TOOL_MESSAGE, SIGNED_OUT_TOOL_MESSAGE, createAgentToolsMcpHandler };

package/dist/portable/mcp.d.ts

@@ -0,0 +1,81 @@
+import { CredentialsPort } from '@ai-matrx/data';
+import { M as MatrxTransport } from '../transport-CxD0fL8p.js';
+import { J as JsonValue, P as PortableAgentBundle } from '../types.generated-BydVlqDC.js';
+
+/**
+ * `@ai-matrx/agents/portable/mcp` — an agent's server tools as an MCP server.
+ *
+ * `createAgentToolsMcpHandler` answers MCP JSON-RPC (`initialize`,
+ * `tools/list`, `tools/call`, `ping`) for ONE agent. `tools/list` is the
+ * bundle's server tools (resolved by the realtime-tools funnel on the server);
+ * `tools/call` runs the tool through `POST /ai/tools/execute`, which
+ * re-resolves the agent's set and refuses anything outside it, and writes the
+ * same `cx_tool_call` row a turn-based call writes.
+ *
+ * Every call reads the credential FRESH from the `CredentialsPort` and carries
+ * `X-Organization-Id` — nothing is cached, and the token never leaves this
+ * process (the CLI only ever sees a URL). Signed out, a call answers one plain
+ * sentence instead of failing obscurely.
+ *
+ * Transport-neutral: the host feeds it the parsed JSON body of each HTTP POST
+ * (MCP "streamable HTTP") and writes back what it returns. Pure: no Node, no
+ * React, no I/O at import.
+ */
+
+/** The MCP protocol revisions this handler speaks, newest first. */
+declare const AGENT_TOOLS_MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+/** The server name the CLIs see (`mcp__matrx-agent__<tool>` in Claude Code). */
+declare const AGENT_TOOLS_MCP_SERVER_NAME = "matrx-agent";
+/** What a signed-out tool call answers. */
+declare const SIGNED_OUT_TOOL_MESSAGE = "Sign in to AI Matrx to use this tool.";
+/** What a call with no organization answers. */
+declare const NO_ORGANIZATION_TOOL_MESSAGE = "Pick an organization in AI Matrx to use this tool.";
+interface AgentToolsMcpOptions {
+    /** The bundle the session loaded — its `tools`, agent/version identity and `surface`. */
+    bundle: Pick<PortableAgentBundle, "agent_id" | "version_id" | "name" | "tools" | "surface">;
+    /** The credential source, read fresh per call. `null`/absent = signed out. */
+    credentials?: CredentialsPort | null;
+    /** The organization every call runs in (value or per-call getter). */
+    organizationId?: string | null | (() => string | null | undefined);
+    /** AI Matrx server base URL, no trailing slash. */
+    baseUrl: string;
+    /**
+     * One conversation id for the whole coding session, so its tool calls group
+     * under one `cx_conversation`. Default: a fresh id per handler.
+     */
+    conversationId?: string;
+    /** Test seam: replaces the transport built from the options above. */
+    transport?: MatrxTransport;
+    /** Every tool call's outcome, for the host's transcript or logs. */
+    onToolCall?: (event: {
+        name: string;
+        ok: boolean;
+        callId: string;
+    }) => void;
+}
+/** A JSON-RPC message, structurally. */
+interface McpJsonRpcMessage {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+/** What the host writes back: HTTP status, plus a JSON body when there is one. */
+interface McpHttpReply {
+    status: number;
+    body?: unknown;
+}
+interface AgentToolsMcpHandler {
+    /** Handle one parsed HTTP POST body (a message or a batch). */
+    handle(body: unknown): Promise<McpHttpReply>;
+    /** The tools `tools/list` returns, in MCP shape. */
+    listTools(): McpToolDescriptor[];
+}
+interface McpToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: Record<string, JsonValue>;
+}
+declare function createAgentToolsMcpHandler(options: AgentToolsMcpOptions): AgentToolsMcpHandler;
+
+export { AGENT_TOOLS_MCP_PROTOCOL_VERSIONS, AGENT_TOOLS_MCP_SERVER_NAME, type AgentToolsMcpHandler, type AgentToolsMcpOptions, type McpHttpReply, type McpJsonRpcMessage, type McpToolDescriptor, NO_ORGANIZATION_TOOL_MESSAGE, SIGNED_OUT_TOOL_MESSAGE, createAgentToolsMcpHandler };

package/dist/portable/mcp.js

@@ -0,0 +1,492 @@
+// matrx/client.ts
+import { isNetError as isNetError2 } from "@ai-matrx/data";
+import { credentialToHeaders } from "@ai-matrx/data";
+
+// matrx/org-context.ts
+import { isUuidShape } from "@ai-matrx/kit/uuid";
+var OrganizationContextError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OrganizationContextError";
+    this.code = code;
+  }
+};
+function requireOrganizationContext(selectedOrganizationId, overrideOrganizationId) {
+  const candidate = overrideOrganizationId ?? selectedOrganizationId;
+  if (typeof candidate !== "string" || candidate.trim().length === 0) {
+    throw new OrganizationContextError(
+      "organization_context_required",
+      "Select an organization before sending this request."
+    );
+  }
+  const normalized = candidate.trim();
+  if (!isUuidShape(normalized)) {
+    throw new OrganizationContextError(
+      "organization_context_invalid",
+      "The selected organization ID is invalid."
+    );
+  }
+  return normalized.toLowerCase();
+}
+function applyOrganizationContextHeader(headers, organizationId) {
+  const normalizedOrganizationId = requireOrganizationContext(organizationId);
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === "x-organization-id" && value.trim().toLowerCase() !== normalizedOrganizationId) {
+      throw new OrganizationContextError(
+        "organization_context_mismatch",
+        "X-Organization-Id must match the request context organization."
+      );
+    }
+  }
+  const withoutOrganizationHeader = Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "x-organization-id"
+    )
+  );
+  return {
+    ...withoutOrganizationHeader,
+    "X-Organization-Id": normalizedOrganizationId
+  };
+}
+
+// matrx/protocol.ts
+import {
+  isNetError,
+  resilientFetch
+} from "@ai-matrx/data/net";
+var MATRX_AI_API_VERSION_DEFAULT = "v2";
+function toV2Path(path) {
+  const withLead = path.startsWith("/") ? path : `/${path}`;
+  if (withLead.startsWith("/api/")) {
+    const rest = withLead.slice("/api".length);
+    return rest.startsWith("/v2/") ? withLead : `/api/v2${rest}`;
+  }
+  return withLead.startsWith("/v2/") ? withLead : `/v2${withLead}`;
+}
+var COVERED_INTERPOLATED_PATH = [
+  /^(?:\/api)?\/ai\/manual$/,
+  /^(?:\/api)?\/ai\/chat$/,
+  /^(?:\/api)?\/ai\/agents\/[^/]+$/,
+  /^(?:\/api)?\/ai\/agent\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversations\/[^/]+$/,
+  /^(?:\/api)?\/ai\/conversation\/[^/]+$/,
+  /^(?:\/api)?\/ai\/prompts\/[^/]+$/,
+  // `/warm` etc. deliberately don't match
+  /^(?:\/api)?\/ai\/mandates\/[^/]+$/
+  // the mandate door
+];
+function isCoveredAiPath(path) {
+  return COVERED_INTERPOLATED_PATH.some((re) => re.test(path));
+}
+function isV2Path(pathOrUrl) {
+  return /\/v2\/ai\//.test(pathOrUrl);
+}
+function toV1FallbackUrl(url) {
+  return url.replace(/\/v2\/ai\//, "/ai/");
+}
+function applyAiApiVersion(path, version) {
+  if (version !== "v2") return path;
+  return isCoveredAiPath(path) ? toV2Path(path) : path;
+}
+async function fetchWithMatrxProtocolFallback(url, init, opts = {}) {
+  const { onDowngrade, ...fetchOpts } = opts;
+  const logDowngrade = (reason, status2) => {
+    console.warn(
+      `[matrx] ai_v2_downgrade \u2192 retrying on v1. v2=${url} reason=${reason}`
+    );
+    onDowngrade?.({ url, reason, ...status2 !== void 0 ? { status: status2 } : {} });
+  };
+  if (!isV2Path(url)) return resilientFetch(url, init, fetchOpts);
+  let result;
+  try {
+    result = await resilientFetch(url, init, fetchOpts);
+  } catch (err) {
+    const isAbort = isNetError(err) && err.code === "aborted" || err instanceof Error && err.name === "AbortError";
+    if (isAbort) throw err;
+    logDowngrade(String(err));
+    return resilientFetch(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  const status = result.response.status;
+  if (status === 404 || status === 405 || status >= 500) {
+    logDowngrade(`HTTP ${status}`, status);
+    return resilientFetch(toV1FallbackUrl(url), init, fetchOpts);
+  }
+  return result;
+}
+
+// matrx/transport.ts
+var MatrxApiError = class extends Error {
+  name = "MatrxApiError";
+  /** HTTP status of the failed response. */
+  status;
+  /** Machine code from the server body (`code`, or `detail.code`), when present. */
+  code;
+  /** The parsed server error body, verbatim (undefined when unparsable). */
+  serverDetail;
+  /** The request path the failure came from (server-relative). */
+  path;
+  constructor(args) {
+    super(
+      args.message ?? extractMatrxErrorMessage(args.serverDetail) ?? `HTTP ${args.status}`
+    );
+    this.status = args.status;
+    this.path = args.path;
+    this.serverDetail = args.serverDetail;
+    this.code = extractMatrxErrorCode(args.serverDetail);
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function extractMatrxErrorMessage(serverDetail) {
+  if (!isRecord(serverDetail)) return void 0;
+  const userMessage = nonBlankString(serverDetail.user_message);
+  if (userMessage) return userMessage;
+  const message = nonBlankString(serverDetail.message);
+  if (message) return message;
+  if (Array.isArray(serverDetail.details)) {
+    const messages = serverDetail.details.map((entry) => {
+      if (!isRecord(entry)) return void 0;
+      const detailMessage = nonBlankString(entry.message);
+      if (!detailMessage) return void 0;
+      const field = nonBlankString(entry.field);
+      return field ? `${field}: ${detailMessage}` : detailMessage;
+    }).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const detailMessage = nonBlankString(detail.message) ?? nonBlankString(detail.user_message);
+    if (detailMessage) return detailMessage;
+  }
+  if (typeof detail === "string" && detail.trim()) return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail.map(
+      (entry) => isRecord(entry) ? nonBlankString(entry.msg) : void 0
+    ).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  return void 0;
+}
+function extractMatrxErrorCode(serverDetail) {
+  if (!isRecord(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/client.ts
+function classifyStatus(status) {
+  return status >= 400 && status < 500 ? "validation_error" : "http_error";
+}
+function normalizeMatrxError(err) {
+  if (err instanceof MatrxApiError) {
+    return {
+      type: classifyStatus(err.status),
+      message: err.message,
+      status: err.status,
+      serverDetail: err.serverDetail,
+      ...err.code ? { code: err.code } : {},
+      name: err.name
+    };
+  }
+  if (err instanceof OrganizationContextError) {
+    return {
+      type: "validation_error",
+      message: err.message,
+      code: err.code,
+      name: err.name,
+      ...err.stack !== void 0 ? { stack: err.stack } : {}
+    };
+  }
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return { type: "abort_error", message: "Request was cancelled." };
+  }
+  if (isNetError2(err)) {
+    if (err.code === "aborted") {
+      return { type: "abort_error", message: err.message };
+    }
+    if (err.code === "http") {
+      const status = err.status ?? 0;
+      return { type: classifyStatus(status), message: err.message, status };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  if (err instanceof Error) {
+    const httpMatch = err.message.match(/HTTP (\d+):\s*(.*)/);
+    if (httpMatch) {
+      const status = parseInt(httpMatch[1], 10);
+      return {
+        type: classifyStatus(status),
+        message: httpMatch[2] ?? err.message,
+        status
+      };
+    }
+    return { type: "network_error", message: err.message };
+  }
+  return { type: "unknown", message: String(err ?? "Unknown error") };
+}
+var PRODUCTION_CONNECT_TIMEOUT_MS = 15e3;
+function stripContentType(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).filter(
+      ([name]) => name.toLowerCase() !== "content-type"
+    )
+  );
+}
+function createMatrxTransport(options) {
+  const {
+    baseUrl,
+    resolveTarget,
+    credentials,
+    organizationId,
+    aiApiVersion,
+    connectTimeoutMs = PRODUCTION_CONNECT_TIMEOUT_MS,
+    totalTimeoutMs = null,
+    expectedErrorStatuses,
+    diagnostics,
+    source = "matrxTransport"
+  } = options;
+  if (baseUrl === void 0 === (resolveTarget === void 0)) {
+    throw new Error(
+      "createMatrxTransport: provide exactly one of `baseUrl` or `resolveTarget`."
+    );
+  }
+  const resolve = resolveTarget ?? (() => ({ baseUrl }));
+  const resolveVersion = () => {
+    if (aiApiVersion === void 0) return MATRX_AI_API_VERSION_DEFAULT;
+    return typeof aiApiVersion === "function" ? aiApiVersion() : aiApiVersion;
+  };
+  const resolveOrganizationId = () => {
+    if (organizationId === void 0) return null;
+    const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
+    return requireOrganizationContext(candidate);
+  };
+  return {
+    async fetch(path, init) {
+      const target = resolve();
+      const versionedPath = applyAiApiVersion(path, resolveVersion());
+      const url = `${target.baseUrl}${versionedPath}`;
+      const credentialHeaders = credentials ? credentialToHeaders(await credentials.get()) : {};
+      let headers = {
+        ...init.headers,
+        ...stripContentType(credentialHeaders),
+        ...stripContentType(target.policyHeaders ?? {})
+      };
+      const orgId = resolveOrganizationId();
+      if (orgId !== null) {
+        headers = applyOrganizationContextHeader(headers, orgId);
+      }
+      const info = {
+        url,
+        method: init.method,
+        path,
+        channel: target.channel ?? "default",
+        source
+      };
+      diagnostics?.onRequest?.(info);
+      let response;
+      try {
+        ({ response } = await fetchWithMatrxProtocolFallback(
+          url,
+          {
+            method: init.method,
+            headers,
+            ...init.body !== void 0 ? { body: init.body } : {}
+          },
+          {
+            ...init.signal ? { signal: init.signal } : {},
+            connectTimeoutMs,
+            totalTimeoutMs,
+            throwOnHttpError: false,
+            ...diagnostics?.onProtocolDowngrade ? { onDowngrade: diagnostics.onProtocolDowngrade } : {}
+          }
+        ));
+      } catch (err) {
+        diagnostics?.onError?.(normalizeMatrxError(err), info);
+        throw err;
+      }
+      if (!response.ok && !expectedErrorStatuses?.includes(response.status)) {
+        const serverDetail = await response.clone().json().catch(() => void 0);
+        const code = extractMatrxErrorCode(serverDetail);
+        diagnostics?.onError?.(
+          {
+            type: classifyStatus(response.status),
+            message: extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
+            status: response.status,
+            serverDetail,
+            ...code ? { code } : {}
+          },
+          info
+        );
+      }
+      return response;
+    }
+  };
+}
+
+// matrx/internal.ts
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+
+// portable/mcp.ts
+var AGENT_TOOLS_MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var AGENT_TOOLS_MCP_SERVER_NAME = "matrx-agent";
+var SIGNED_OUT_TOOL_MESSAGE = "Sign in to AI Matrx to use this tool.";
+var NO_ORGANIZATION_TOOL_MESSAGE = "Pick an organization in AI Matrx to use this tool.";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function newId() {
+  return globalThis.crypto.randomUUID();
+}
+function toDescriptor(tool) {
+  const schema = isRecord2(tool.parameters) && tool.parameters.type === "object" ? tool.parameters : { type: "object", properties: {} };
+  return { name: tool.name, description: tool.description || tool.canonical_name, inputSchema: schema };
+}
+function rpcResult(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function rpcError(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+function textResult(text, isError) {
+  return { content: [{ type: "text", text }], isError };
+}
+function createAgentToolsMcpHandler(options) {
+  const { bundle } = options;
+  const conversationId = options.conversationId ?? newId();
+  const descriptors = bundle.tools.map(toDescriptor);
+  const known = new Set(bundle.tools.map((tool) => tool.name));
+  const resolveOrganization = () => {
+    const raw = typeof options.organizationId === "function" ? options.organizationId() : options.organizationId;
+    return raw && raw.trim() ? raw.trim() : null;
+  };
+  const transportFor = (organizationId) => options.transport ?? createMatrxTransport({
+    baseUrl: options.baseUrl,
+    ...options.credentials ? { credentials: options.credentials } : {},
+    organizationId,
+    source: "agentToolsMcp"
+  });
+  async function callTool(id, params) {
+    if (!isRecord2(params) || typeof params.name !== "string") {
+      return rpcError(id, -32602, "tools/call needs a tool name.");
+    }
+    const name = params.name;
+    if (!known.has(name)) return rpcError(id, -32602, `Unknown tool: ${name}`);
+    const args = isRecord2(params.arguments) ? params.arguments : {};
+    const credential = options.credentials ? await options.credentials.get() : null;
+    if (!credential) return rpcResult(id, textResult(SIGNED_OUT_TOOL_MESSAGE, true));
+    const organizationId = resolveOrganization();
+    if (!organizationId) return rpcResult(id, textResult(NO_ORGANIZATION_TOOL_MESSAGE, true));
+    const callId = newId();
+    const pinned = typeof bundle.version_id === "string" && bundle.version_id.length > 0;
+    try {
+      const response = await requestJson(
+        transportFor(organizationId),
+        "/ai/tools/execute",
+        {
+          method: "POST",
+          body: {
+            agent_id: pinned ? bundle.version_id : bundle.agent_id,
+            is_version: pinned,
+            conversation_id: conversationId,
+            tool_name: name,
+            arguments: args,
+            call_id: callId,
+            surface: bundle.surface
+          }
+        }
+      );
+      options.onToolCall?.({ name, ok: response.ok, callId });
+      return rpcResult(id, textResult(response.output, !response.ok));
+    } catch (error) {
+      options.onToolCall?.({ name, ok: false, callId });
+      if (error instanceof MatrxApiError && error.status === 401) {
+        return rpcResult(id, textResult(SIGNED_OUT_TOOL_MESSAGE, true));
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      return rpcResult(id, textResult(`AI Matrx could not run ${name}: ${message}`, true));
+    }
+  }
+  async function handleOne(message) {
+    if (!isRecord2(message) || typeof message.method !== "string") {
+      return rpcError(null, -32600, "Invalid request.");
+    }
+    const { id, params } = message;
+    const method = message.method;
+    const isNotification = id === void 0;
+    switch (method) {
+      case "initialize": {
+        const requested = isRecord2(params) ? params.protocolVersion : void 0;
+        const protocolVersion = typeof requested === "string" && AGENT_TOOLS_MCP_PROTOCOL_VERSIONS.includes(requested) ? requested : AGENT_TOOLS_MCP_PROTOCOL_VERSIONS[0];
+        return rpcResult(id, {
+          protocolVersion,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: AGENT_TOOLS_MCP_SERVER_NAME, version: "1" },
+          instructions: `Tools of the AI Matrx agent "${bundle.name}". They run on AI Matrx as the signed-in person.`
+        });
+      }
+      case "ping":
+        return isNotification ? null : rpcResult(id, {});
+      case "tools/list":
+        return rpcResult(id, { tools: descriptors });
+      case "tools/call":
+        return callTool(id, params);
+      default:
+        if (isNotification) return null;
+        return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+  return {
+    listTools: () => descriptors,
+    async handle(body) {
+      if (Array.isArray(body)) {
+        const replies = (await Promise.all(body.map(handleOne))).filter((r) => r !== null);
+        return replies.length ? { status: 200, body: replies } : { status: 202 };
+      }
+      const reply = await handleOne(body);
+      return reply === null ? { status: 202 } : { status: 200, body: reply };
+    }
+  };
+}
+export {
+  AGENT_TOOLS_MCP_PROTOCOL_VERSIONS,
+  AGENT_TOOLS_MCP_SERVER_NAME,
+  NO_ORGANIZATION_TOOL_MESSAGE,
+  SIGNED_OUT_TOOL_MESSAGE,
+  createAgentToolsMcpHandler
+};
+//# sourceMappingURL=mcp.js.map