ai-runtime-engine 1.2.0 → 2.7.0

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,216 @@
+/**
+ * MCP wire protocol (Phase 3.2) - JSON-RPC 2.0 shapes plus TOLERANT zod validators for the small
+ * client-side subset we speak: `initialize`, `tools/list`, `tools/call`, `ping`. Result objects are
+ * validated only on the fields we consume (`.passthrough()`), so a server that adds fields or drifts
+ * ahead of our pinned protocol version degrades gracefully instead of breaking the run.
+ *
+ * SECURITY - MCP metadata (tool names, descriptions, schemas) is attacker-controlled text that reaches
+ * model prompts (the planner catalog, the `mcp: true` declaration path). `normalizeToolDecl` is the
+ * DISCOVERY-TIME gate: it validates the name charset, strips control characters, and clamps length, so a
+ * server can neither forge catalog rows nor smuggle instructions through its own metadata.
+ */
+import { z } from 'zod';
+/** The protocol version this client speaks. A server may counter-propose; see `McpClient.initialize`. */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * What we tell a server we are (the spec's `Implementation`). Versioned for THIS client implementation,
+ * deliberately NOT the product version: a third-party server has no business fingerprinting the host,
+ * and it keeps the release version to its three canonical sites.
+ */
+export declare const MCP_CLIENT_INFO: {
+    readonly name: "ai-runtime";
+    readonly version: "1.0.0";
+};
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type JsonRpcMessage = JsonRpcResponse | JsonRpcNotification;
+/**
+ * Application error codes (-32000..-32099) are implementation-defined by JSON-RPC and NOT standardized
+ * by MCP, so they are deliberately NOT read as an auth signal: several SDKs use -32002 for "resource not
+ * found" and -32001 for a server-side timeout, and mapping those to AUTHENTICATION would park a healthy
+ * server in `auth_failed` for the whole session (which is never silently retried). Authentication is
+ * detected where it is unambiguous: the transport's HTTP 401/403.
+ */
+export declare const JSONRPC_AUTH_CODES: ReadonlySet<number>;
+export declare const initializeResult: z.ZodObject<{
+    protocolVersion: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    protocolVersion: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    protocolVersion: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const mcpToolDecl: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">>>;
+    annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">>>;
+    annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodLiteral<"object">;
+    }, z.ZodTypeAny, "passthrough">>>;
+    annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type McpToolDecl = z.infer<typeof mcpToolDecl>;
+export declare const listToolsResult: z.ZodObject<{
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const callToolResult: z.ZodObject<{
+    content: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    content: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    content: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+    isError: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+/** What a tool call returned, already flattened to text + optional structured payload. */
+export interface McpCallResult {
+    text: string;
+    structured?: unknown;
+    isError: boolean;
+}
+/** Tool names must be a safe, addressable identifier - this also becomes the Tool id suffix. */
+export declare const MCP_TOOL_NAME_RE: RegExp;
+/** Descriptions reach model prompts; clamp hard. */
+export declare const MCP_DESCRIPTION_MAX = 300;
+/** A schema's own strings (property descriptions, titles, enum values) reach model prompts too. */
+export declare const MCP_SCHEMA_STRING_MAX = 200;
+/** Bounds on a single tool's schema: an unbounded one inflates EVERY planning call that declares it. */
+export declare const MCP_SCHEMA_MAX_DEPTH = 12;
+export declare const MCP_SCHEMA_MAX_NODES = 400;
+/** Flatten and clamp server-controlled text: no control chars, no newlines, bounded length. */
+export declare function clampText(raw: unknown, max: number): string;
+/**
+ * Deep-sanitize a server-supplied JSON Schema. A schema is not inert data: it is handed to the model as
+ * part of the tool definition, so every string inside it (`description`, `title`, `enum`, `$comment`, …)
+ * is untrusted prompt text and gets the same flatten-and-clamp treatment as the tool description.
+ * Structure is bounded too — depth, node count, and key count — because a 500-tool server with
+ * multi-megabyte schemas would otherwise inflate every request that declares them. Returns `undefined`
+ * when the schema is unusable, in which case the tool registers with NO parameters (honest: the model is
+ * told nothing rather than something forged).
+ */
+export declare function sanitizeSchema(raw: unknown, budget?: {
+    nodes: number;
+}, depth?: number): unknown;
+export interface NormalizedTool {
+    name: string;
+    description: string;
+    inputSchema?: unknown;
+    /** From `annotations.readOnlyHint === true` ONLY; anything else is write-like (fail-closed). */
+    readOnly: boolean;
+    /** `annotations.destructiveHint === true` implies always-confirm, even when granted `full`. */
+    destructive: boolean;
+}
+/**
+ * Validate + normalize one declaration. Returns `undefined` when the declaration is unusable (bad shape
+ * or an unsafe name) - the caller counts it as rejected and NEVER registers it. Annotations are the
+ * server's own claims: honored only in the safe direction (`readOnlyHint` narrows what we allow,
+ * `destructiveHint` adds friction), never to widen permission.
+ */
+export declare function normalizeToolDecl(raw: unknown): NormalizedTool | undefined;
+/** Flatten a `tools/call` result into text + structured payload (text blocks only; other kinds dropped). */
+export declare function flattenCallResult(raw: unknown): McpCallResult;

package/dist/mcp/protocol.js

@@ -0,0 +1,149 @@
+/**
+ * MCP wire protocol (Phase 3.2) - JSON-RPC 2.0 shapes plus TOLERANT zod validators for the small
+ * client-side subset we speak: `initialize`, `tools/list`, `tools/call`, `ping`. Result objects are
+ * validated only on the fields we consume (`.passthrough()`), so a server that adds fields or drifts
+ * ahead of our pinned protocol version degrades gracefully instead of breaking the run.
+ *
+ * SECURITY - MCP metadata (tool names, descriptions, schemas) is attacker-controlled text that reaches
+ * model prompts (the planner catalog, the `mcp: true` declaration path). `normalizeToolDecl` is the
+ * DISCOVERY-TIME gate: it validates the name charset, strips control characters, and clamps length, so a
+ * server can neither forge catalog rows nor smuggle instructions through its own metadata.
+ */
+import { z } from 'zod';
+/** Control characters and DEL - stripped before any server text is rendered or prompted. */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]+/g;
+/** The protocol version this client speaks. A server may counter-propose; see `McpClient.initialize`. */
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+/**
+ * What we tell a server we are (the spec's `Implementation`). Versioned for THIS client implementation,
+ * deliberately NOT the product version: a third-party server has no business fingerprinting the host,
+ * and it keeps the release version to its three canonical sites.
+ */
+export const MCP_CLIENT_INFO = { name: 'ai-runtime', version: '1.0.0' };
+/**
+ * Application error codes (-32000..-32099) are implementation-defined by JSON-RPC and NOT standardized
+ * by MCP, so they are deliberately NOT read as an auth signal: several SDKs use -32002 for "resource not
+ * found" and -32001 for a server-side timeout, and mapping those to AUTHENTICATION would park a healthy
+ * server in `auth_failed` for the whole session (which is never silently retried). Authentication is
+ * detected where it is unambiguous: the transport's HTTP 401/403.
+ */
+export const JSONRPC_AUTH_CODES = new Set();
+// -- result validators (tolerant on purpose) ---------------------------------
+export const initializeResult = z
+    .object({
+    protocolVersion: z.string().optional(),
+    serverInfo: z.object({ name: z.string().optional(), version: z.string().optional() }).passthrough().optional(),
+    capabilities: z.record(z.unknown()).optional(),
+})
+    .passthrough();
+export const mcpToolDecl = z
+    .object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    inputSchema: z.object({ type: z.literal('object') }).passthrough().optional(),
+    // Deliberately untyped: a server sending `readOnlyHint: 'yes'` must not invalidate an otherwise
+    // usable tool — the claim is simply not `true`, so the tool stays write-like.
+    annotations: z.record(z.unknown()).optional(),
+})
+    .passthrough();
+export const listToolsResult = z.object({ tools: z.array(z.unknown()).optional(), nextCursor: z.string().optional() }).passthrough();
+export const callToolResult = z
+    .object({
+    content: z.array(z.object({ type: z.string() }).passthrough()).optional(),
+    structuredContent: z.unknown().optional(),
+    isError: z.boolean().optional(),
+})
+    .passthrough();
+// -- discovery-time normalization (the second untrusted-content choke point) --
+/** Tool names must be a safe, addressable identifier - this also becomes the Tool id suffix. */
+export const MCP_TOOL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/** Descriptions reach model prompts; clamp hard. */
+export const MCP_DESCRIPTION_MAX = 300;
+/** A schema's own strings (property descriptions, titles, enum values) reach model prompts too. */
+export const MCP_SCHEMA_STRING_MAX = 200;
+/** Bounds on a single tool's schema: an unbounded one inflates EVERY planning call that declares it. */
+export const MCP_SCHEMA_MAX_DEPTH = 12;
+export const MCP_SCHEMA_MAX_NODES = 400;
+/** Flatten and clamp server-controlled text: no control chars, no newlines, bounded length. */
+export function clampText(raw, max) {
+    const flat = String(raw ?? '')
+        .replace(CONTROL_CHARS, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > max ? `${flat.slice(0, max)}...` : flat;
+}
+/**
+ * Deep-sanitize a server-supplied JSON Schema. A schema is not inert data: it is handed to the model as
+ * part of the tool definition, so every string inside it (`description`, `title`, `enum`, `$comment`, …)
+ * is untrusted prompt text and gets the same flatten-and-clamp treatment as the tool description.
+ * Structure is bounded too — depth, node count, and key count — because a 500-tool server with
+ * multi-megabyte schemas would otherwise inflate every request that declares them. Returns `undefined`
+ * when the schema is unusable, in which case the tool registers with NO parameters (honest: the model is
+ * told nothing rather than something forged).
+ */
+export function sanitizeSchema(raw, budget = { nodes: MCP_SCHEMA_MAX_NODES }, depth = 0) {
+    if (depth > MCP_SCHEMA_MAX_DEPTH || budget.nodes <= 0)
+        return undefined;
+    budget.nodes -= 1;
+    if (typeof raw === 'string')
+        return clampText(raw, MCP_SCHEMA_STRING_MAX);
+    if (typeof raw === 'number' || typeof raw === 'boolean' || raw === null)
+        return raw;
+    if (Array.isArray(raw)) {
+        const out = [];
+        for (const v of raw.slice(0, 64)) {
+            const s = sanitizeSchema(v, budget, depth + 1);
+            if (s !== undefined)
+                out.push(s);
+        }
+        return out;
+    }
+    if (typeof raw !== 'object')
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(raw).slice(0, 64)) {
+        const key = clampText(k, 64);
+        if (!key)
+            continue;
+        const s = sanitizeSchema(v, budget, depth + 1);
+        if (s !== undefined)
+            out[key] = s;
+    }
+    return out;
+}
+/**
+ * Validate + normalize one declaration. Returns `undefined` when the declaration is unusable (bad shape
+ * or an unsafe name) - the caller counts it as rejected and NEVER registers it. Annotations are the
+ * server's own claims: honored only in the safe direction (`readOnlyHint` narrows what we allow,
+ * `destructiveHint` adds friction), never to widen permission.
+ */
+export function normalizeToolDecl(raw) {
+    const parsed = mcpToolDecl.safeParse(raw);
+    if (!parsed.success)
+        return undefined;
+    const decl = parsed.data;
+    const name = clampText(decl.name, 64);
+    if (!MCP_TOOL_NAME_RE.test(name))
+        return undefined;
+    const schema = decl.inputSchema ? sanitizeSchema(decl.inputSchema) : undefined;
+    return {
+        name,
+        description: clampText(decl.description ?? name, MCP_DESCRIPTION_MAX),
+        // The schema is prompt text too — sanitized and bounded, never passed through (see sanitizeSchema).
+        ...(schema !== undefined ? { inputSchema: schema } : {}),
+        readOnly: decl.annotations?.readOnlyHint === true,
+        destructive: decl.annotations?.destructiveHint === true,
+    };
+}
+/** Flatten a `tools/call` result into text + structured payload (text blocks only; other kinds dropped). */
+export function flattenCallResult(raw) {
+    const parsed = callToolResult.safeParse(raw);
+    if (!parsed.success)
+        return { text: '', isError: true };
+    const r = parsed.data;
+    const text = (r.content ?? [])
+        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('\n');
+    return { text, ...(r.structuredContent !== undefined ? { structured: r.structuredContent } : {}), isError: r.isError === true };
+}

package/dist/mcp/toolAdapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP → Runtime Tool adapter (Phase 3.2). Every discovered MCP tool is wrapped as an ORDINARY `Tool` and
+ * registered in the Runtime `ToolRegistry`, so `Runtime.runTool`'s existing machinery applies unchanged:
+ * resolved `ExecutionPolicy` permissions, host approval via `authorize()`, the abort signal, structured
+ * denials, and output redaction. There is deliberately NO parallel execution path for MCP.
+ *
+ * The four rules this file enforces:
+ *  1. PERMISSION — deny-by-default per server (`off` | `read` | `full`); a write-like tool needs `full`.
+ *  2. APPROVAL — routed through `authorize()`; a `destructiveHint` tool always confirms, even at `full`.
+ *  3. UNTRUSTED — the call's text output is `wrapUntrusted`-fenced and redacted before it can reach a
+ *     prompt; a server-controlled ERROR message is mapped to a fixed taxonomy, never interpolated raw.
+ *  4. EFFECTS come from the LIVE handshake's annotations, never from a cached tool list — a cached
+ *     `readOnlyHint` must not be able to lower the gate for a server that has since changed.
+ */
+import type { Tool } from '../tools/tool.js';
+import type { NormalizedTool } from './protocol.js';
+/** What the adapter needs from the manager — kept narrow so the manager stays swappable in tests. */
+export interface McpCallable {
+    call(serverId: string, tool: string, args: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        structured?: unknown;
+        isError: boolean;
+    }>;
+    /** Whether the server is usable right now; false ⇒ a structured UNAVAILABLE denial (never a crash). */
+    usable(serverId: string): boolean;
+    /**
+     * The annotations from the CURRENT handshake, or undefined when there is no live connection. The gates
+     * below read this and never the registration-time snapshot: the snapshot may have come from a cache
+     * written before the server changed its annotations.
+     */
+    liveTool(serverId: string, tool: string): {
+        readOnly: boolean;
+        destructive: boolean;
+    } | undefined;
+}
+/** The Tool id for an MCP tool: `<serverId>.<toolName>` (matches the shipped namespacing convention). */
+export declare function mcpToolId(serverId: string, toolName: string): string;
+/**
+ * Build the `Tool` for one discovered MCP tool. `readOnly`/`destructive` are the LIVE annotation values
+ * captured at handshake time by the caller.
+ */
+export declare function mcpTool(manager: McpCallable, serverId: string, decl: NormalizedTool): Tool;

package/dist/mcp/toolAdapter.js

@@ -0,0 +1,94 @@
+/**
+ * MCP → Runtime Tool adapter (Phase 3.2). Every discovered MCP tool is wrapped as an ORDINARY `Tool` and
+ * registered in the Runtime `ToolRegistry`, so `Runtime.runTool`'s existing machinery applies unchanged:
+ * resolved `ExecutionPolicy` permissions, host approval via `authorize()`, the abort signal, structured
+ * denials, and output redaction. There is deliberately NO parallel execution path for MCP.
+ *
+ * The four rules this file enforces:
+ *  1. PERMISSION — deny-by-default per server (`off` | `read` | `full`); a write-like tool needs `full`.
+ *  2. APPROVAL — routed through `authorize()`; a `destructiveHint` tool always confirms, even at `full`.
+ *  3. UNTRUSTED — the call's text output is `wrapUntrusted`-fenced and redacted before it can reach a
+ *     prompt; a server-controlled ERROR message is mapped to a fixed taxonomy, never interpolated raw.
+ *  4. EFFECTS come from the LIVE handshake's annotations, never from a cached tool list — a cached
+ *     `readOnlyHint` must not be able to lower the gate for a server that has since changed.
+ */
+import { authorize, denied } from '../tools/tool.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { redactString } from '../security/redact.js';
+import { AIError } from '../core/fallback/errors.js';
+import { namespacedId } from '../capabilities/capability.js';
+/** The Tool id for an MCP tool: `<serverId>.<toolName>` (matches the shipped namespacing convention). */
+export function mcpToolId(serverId, toolName) {
+    return `${serverId}.${toolName}`;
+}
+/**
+ * Build the `Tool` for one discovered MCP tool. `readOnly`/`destructive` are the LIVE annotation values
+ * captured at handshake time by the caller.
+ */
+export function mcpTool(manager, serverId, decl) {
+    const capabilityId = namespacedId('mcp', mcpToolId(serverId, decl.name));
+    return {
+        id: mcpToolId(serverId, decl.name),
+        description: `${decl.description} (MCP server: ${serverId})`,
+        ...(decl.inputSchema ? { parameters: decl.inputSchema } : {}),
+        // Action capability: namespaced to its server so it can never claim a curated id (Phase 3.1 rule).
+        // Built with the SAME helper the registry uses, so the declared id is exactly the one it resolves to.
+        provides: [{ id: capabilityId, effects: decl.readOnly ? ['read'] : ['write'], description: decl.description }],
+        async execute(input, ctx) {
+            // (0) Annotations come from the LIVE handshake. With no live connection the registration-time
+            // snapshot is not trusted for GATING (it may be a cache written before the server changed), so
+            // both gates fail closed: write-like AND destructive.
+            const live = manager.liveTool(serverId, decl.name);
+            const writeLike = live ? !live.readOnly : true;
+            const destructive = live ? live.destructive : true;
+            // (1) permission — deny-by-default, per server, read/full split. `hasOwnProperty` because an
+            // unconfigured server must answer "no grant", never inherit something from a prototype.
+            const servers = ctx.permissions.mcp.servers;
+            const grant = Object.prototype.hasOwnProperty.call(servers, serverId) ? servers[serverId] : 'off';
+            if (grant !== 'read' && grant !== 'full') {
+                return denied('PERMISSION', `MCP server '${serverId}' is not permitted — grant permissions.mcp.servers.${serverId}: read (or full)`);
+            }
+            if (writeLike && grant !== 'full') {
+                return denied('PERMISSION', `'${decl.name}' is not declared read-only${live ? '' : ' by a live connection'}; server '${serverId}' is granted '${grant}' (needs full)`);
+            }
+            // (2) approval — the grant checked above IS the standing permission (the house convention:
+            // `authorize(ctx, <standing permission>, …)`), so a granted call proceeds headlessly. Passing
+            // `false` here would make `full` useless without an interactive host AND would let a host widen
+            // past a grant the server was never given.
+            const ok = await authorize(ctx, true, {
+                action: `mcp:${serverId}.${decl.name}`,
+                risk: writeLike ? 'high' : 'low',
+                ...(destructive ? { alwaysConfirm: true } : {}),
+            });
+            if (!ok)
+                return denied('PERMISSION', `approval denied for mcp:${serverId}.${decl.name}`);
+            // Availability — honest at call time (a cached tool whose server is unreachable says so).
+            if (!manager.usable(serverId)) {
+                return denied('NOT_FOUND', `MCP server '${serverId}' is not connected — run 'ai-runtime mcp ${serverId} test' or re-enable it`);
+            }
+            let res;
+            try {
+                res = await manager.call(serverId, decl.name, input ?? {}, { ...(ctx.signal ? { signal: ctx.signal } : {}) });
+            }
+            catch (e) {
+                // (3b) a transport/protocol failure maps to a taxonomy — never the server's raw text.
+                const category = e instanceof AIError ? e.category : 'UNKNOWN';
+                return denied('EXEC_FAILED', `MCP call failed (${category}) on '${serverId}.${decl.name}'`);
+            }
+            // (3a) a tool-level error: fixed taxonomy + the server's text only as fenced diagnostics
+            if (res.isError) {
+                return {
+                    ok: false,
+                    error: { code: 'EXEC_FAILED', message: `MCP tool '${serverId}.${decl.name}' returned an error` },
+                    data: { diagnostic: wrapUntrusted(`mcp:${serverId}.${decl.name}`, redactString(res.text).slice(0, 500)) },
+                };
+            }
+            // Success: the text output is UNTRUSTED data — fenced + redacted at this single boundary.
+            return {
+                ok: true,
+                output: wrapUntrusted(`mcp:${serverId}.${decl.name}`, redactString(res.text)),
+                ...(res.structured !== undefined ? { data: res.structured } : {}),
+            };
+        },
+    };
+}

package/dist/mcp/transport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * MCP transports (Phase 3.2) — zero-dependency, injectable, offline-testable.
+ *
+ * `StdioTransport` spawns a server process and frames JSON-RPC as newline-delimited JSON over stdin/
+ * stdout (stderr is captured, redacted, and ring-buffered for diagnostics). `HttpTransport` speaks
+ * streamable HTTP: it POSTs JSON-RPC and accepts either a single JSON response or an SSE stream, reusing
+ * the `data:`-line parsing approach already proven in `providers/httpClient.callHttpStream`, and carries
+ * the `Mcp-Session-Id` handed out at initialize. `InProcessTransport` is the test seam.
+ *
+ * SECURITY: a request URL or spawn command NEVER appears in a thrown error (undici embeds the URL in its
+ * message, and a URL can carry a token) — only the error NAME. Credentials arrive already resolved from
+ * an env-var NAME via `Credential`, are used solely to build a header (or a single env var for stdio),
+ * and are never stored on the transport, logged, or serialized.
+ */
+import type { FetchLike } from '../providers/httpClient.js';
+import type { JsonRpcMessage, JsonRpcNotification, JsonRpcRequest } from './protocol.js';
+export interface McpTransport {
+    /** Establish the connection (spawn / probe). Throws an AIError with a redacted message on failure. */
+    start(): Promise<void>;
+    send(msg: JsonRpcRequest | JsonRpcNotification): Promise<void>;
+    onMessage(cb: (msg: JsonRpcMessage) => void): void;
+    close(): Promise<void>;
+    /** Recent stderr / diagnostic lines (redacted, bounded) for `mcp <id>`. */
+    diagnostics(): string[];
+    /**
+     * True when the peer invalidated our session and the ONLY recovery is a fresh handshake (HTTP 404 on a
+     * session-bearing request). The manager reads this to force a reconnect from any state — a retry that
+     * reuses the dropped session would fail forever.
+     */
+    sessionExpired?: boolean;
+}
+export interface StdioTransportOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    /** Resolved credential value, injected as a single env var by NAME (never logged, never stored). */
+    tokenEnvName?: string;
+    tokenValue?: string;
+    /** Extra env passthrough by NAME only (values come from the parent env). */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class StdioTransport implements McpTransport {
+    private readonly opts;
+    private child?;
+    private handler?;
+    private buffer;
+    private readonly diag;
+    private closed;
+    constructor(opts: StdioTransportOptions);
+    start(): Promise<void>;
+    private onChunk;
+    send(msg: JsonRpcRequest | JsonRpcNotification): Promise<void>;
+    onMessage(cb: (msg: JsonRpcMessage) => void): void;
+    /** SIGTERM, then a process-group SIGKILL — the same escalation the shell runner uses. */
+    close(): Promise<void>;
+    diagnostics(): string[];
+}
+export interface HttpTransportOptions {
+    url: string;
+    /** Resolved credential value → `authorization: Bearer …`. Never stored beyond this closure. */
+    token?: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+export declare class HttpTransport implements McpTransport {
+    private readonly opts;
+    private handler?;
+    private sessionId?;
+    /** Set once the handshake settles; the spec requires it on every subsequent request. */
+    private negotiatedVersion?;
+    private readonly diag;
+    private readonly fetchImpl;
+    constructor(opts: HttpTransportOptions);
+    start(): Promise<void>;
+    onMessage(cb: (msg: JsonRpcMessage) => void): void;
+    /**
+     * Whether the session was invalidated (HTTP 404 on a session-bearing request). The manager reads this
+     * to force a full reconnect instead of retrying against a session the server has forgotten.
+     */
+    sessionExpired: boolean;
+    /** Record the version the handshake settled on so later requests can carry the required header. */
+    setProtocolVersion(version: string): void;
+    send(msg: JsonRpcRequest | JsonRpcNotification): Promise<void>;
+    private readJson;
+    /**
+     * Consume an SSE body. Events are separated by a BLANK line and a single event may carry several
+     * `data:` lines that concatenate with newlines — parsing each line on its own loses any multi-line
+     * event, and treating a lone CR as no separator makes a CR-only stream unparseable. Both are handled
+     * here. We stop once the frame we are waiting for arrives: a RESPONSE (an id plus result/error and no
+     * method), not merely anything carrying an id — a server-initiated request would otherwise abandon the
+     * stream before our own reply showed up.
+     */
+    private readSse;
+    /** Parse one SSE event block; returns true when it carried a JSON-RPC RESPONSE to one of our requests. */
+    private dispatchSseEvent;
+    close(): Promise<void>;
+    diagnostics(): string[];
+}
+/** A scripted server for offline tests: a plain function from request to response. */
+export declare class InProcessTransport implements McpTransport {
+    private readonly server;
+    private handler?;
+    constructor(server: (req: JsonRpcRequest) => JsonRpcMessage | undefined | Promise<JsonRpcMessage | undefined>);
+    start(): Promise<void>;
+    onMessage(cb: (msg: JsonRpcMessage) => void): void;
+    send(msg: JsonRpcRequest | JsonRpcNotification): Promise<void>;
+    close(): Promise<void>;
+    diagnostics(): string[];
+}