okengine 0.13.0 → 0.14.1

package/src/elements/ai/mcp-http.ts

@@ -0,0 +1,159 @@
+/**
+ * Streamable HTTP MCP transport — POST JSON-RPC, optional SSE response.
+ *
+ * Cancel = abort `fetch` / close the SSE stream. Never POST
+ * `notifications/cancelled` on HTTP.
+ */
+
+import { abortError } from "../../kernel/abort-scope.ts";
+import { parseJsonRpcResponse } from "./mcp-protocol.ts";
+import {
+  McpTransportError,
+  type McpTransport,
+  type McpTransportRequest,
+  type McpWireResult,
+} from "./mcp-transport.ts";
+
+/** Options for {@link createMcpHttpTransport}. */
+export interface CreateMcpHttpTransportOptions {
+  readonly url: string;
+  readonly bearer?: string;
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Create a Streamable HTTP transport for one MCP origin.
+ *
+ * @param options - URL + optional bearer
+ */
+export function createMcpHttpTransport(options: CreateMcpHttpTransportOptions): McpTransport {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  return {
+    kind: "http",
+    async request(request: McpTransportRequest): Promise<McpWireResult> {
+      if (request.signal?.aborted) throw abortError(request.signal.reason);
+      const headers: Record<string, string> = {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        ...request.headers,
+      };
+      if (options.bearer) headers.authorization = `Bearer ${options.bearer}`;
+      const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: request.id,
+        method: request.method,
+        ...(request.params !== undefined ? { params: request.params } : {}),
+      });
+      let response: Response;
+      try {
+        response = await fetchImpl(options.url, {
+          method: "POST",
+          headers,
+          body,
+          signal: request.signal,
+        });
+      } catch (err) {
+        if (request.signal?.aborted || (err instanceof Error && err.name === "AbortError")) {
+          throw abortError(request.signal?.reason ?? err);
+        }
+        throw new McpTransportError(
+          err instanceof Error ? err.message : "ai.mcp: HTTP request failed",
+          { network: true },
+        );
+      }
+
+      const sessionId = response.headers.get("mcp-session-id") ?? undefined;
+      const ctype = response.headers.get("content-type") ?? "";
+      const rawBody = ctype.includes("text/event-stream")
+        ? await readSseJsonRpc(response, request.id, request.signal)
+        : await readJsonBody(response);
+
+      const parsed = parseJsonRpcResponse(rawBody);
+      if (parsed?.ok) {
+        return {
+          ok: true,
+          result: parsed.result,
+          httpStatus: response.status,
+          ...(sessionId !== undefined ? { sessionId } : {}),
+          rawBody,
+        };
+      }
+      if (parsed && !parsed.ok) {
+        return {
+          ok: false,
+          error: parsed.error,
+          httpStatus: response.status,
+          ...(sessionId !== undefined ? { sessionId } : {}),
+          rawBody,
+        };
+      }
+      return {
+        ok: false,
+        httpStatus: response.status,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        rawBody,
+      };
+    },
+    async close() {
+      /* HTTP is per-request */
+    },
+  };
+}
+
+async function readJsonBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (text.length === 0) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+async function readSseJsonRpc(
+  response: Response,
+  id: string | number,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  let buf = "";
+  let last: unknown;
+  for await (const piece of responseTextStream(response)) {
+    if (signal?.aborted) throw abortError(signal.reason);
+    buf += piece;
+    const parts = buf.split("\n\n");
+    buf = parts.pop() ?? "";
+    for (const part of parts) {
+      const data = part
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n");
+      if (!data || data === "[DONE]") continue;
+      try {
+        const json: unknown = JSON.parse(data);
+        if (
+          json !== null &&
+          typeof json === "object" &&
+          !Array.isArray(json) &&
+          (json as { id?: unknown }).id === id
+        ) {
+          last = json;
+        }
+      } catch {
+        /* skip malformed frames */
+      }
+    }
+  }
+  if (last === undefined) {
+    throw new Error("ai.mcp: SSE stream ended without a matching response");
+  }
+  return last;
+}
+
+function responseTextStream(res: Response): AsyncIterable<string> {
+  const stream = (res as Response & { textStream?: () => AsyncIterable<string> }).textStream;
+  if (typeof stream !== "function") {
+    throw new Error("ai.mcp: Response.textStream is required (Bun >= 1.4.0)");
+  }
+  return stream.call(res);
+}

package/src/elements/ai/mcp-mock.ts

@@ -0,0 +1,134 @@
+/**
+ * In-process MCP transport for tests — no child process, no network.
+ */
+
+import { abortError, abortableSleep } from "../../kernel/abort-scope.ts";
+import type { McpListedTool, McpRpcError } from "./mcp-protocol.ts";
+import {
+  type McpTransport,
+  type McpTransportRequest,
+  type McpWireResult,
+} from "./mcp-transport.ts";
+
+/** One tool the mock server exposes. */
+export interface MockMcpTool extends McpListedTool {}
+
+/** Options for {@link createMockMcpTransport}. */
+export interface CreateMockMcpTransportOptions {
+  readonly era?: "modern" | "legacy";
+  readonly tools?: readonly MockMcpTool[];
+  /** HTTP status of the first request (default 200). */
+  readonly httpStatusOnFirst?: number;
+  /** JSON-RPC error on the first request. */
+  readonly firstError?: McpRpcError;
+  /** Unrecognized first-request body (400 without a modern error object). */
+  readonly firstBody?: unknown;
+  readonly onCall?: (name: string, args: unknown, signal?: AbortSignal) => unknown;
+  readonly delayMs?: number;
+  /** `server/discover` hangs until abort / never resolves. */
+  readonly discoverHang?: boolean;
+  readonly extraTools?: readonly MockMcpTool[];
+}
+
+/**
+ * Create a mock MCP transport.
+ *
+ * @param options - Era / tools / first-request fault
+ */
+export function createMockMcpTransport(options: CreateMockMcpTransportOptions = {}): McpTransport {
+  let requestCount = 0;
+  const era = options.era ?? "modern";
+  const tools = [...(options.tools ?? []), ...(options.extraTools ?? [])];
+
+  return {
+    kind: "mock",
+    async request(request: McpTransportRequest): Promise<McpWireResult> {
+      if (request.signal?.aborted) throw abortError(request.signal.reason);
+      requestCount += 1;
+      if (options.delayMs) {
+        await abortableSleep(options.delayMs, request.signal);
+      }
+      if (options.discoverHang && request.method === "server/discover") {
+        await hangUntilAbort(request.signal);
+      }
+
+      if (requestCount === 1 && options.httpStatusOnFirst !== undefined) {
+        if (options.firstError) {
+          return {
+            ok: false,
+            error: options.firstError,
+            httpStatus: options.httpStatusOnFirst,
+            rawBody: { jsonrpc: "2.0", id: request.id, error: options.firstError },
+          };
+        }
+        return {
+          ok: false,
+          httpStatus: options.httpStatusOnFirst,
+          rawBody: options.firstBody,
+        };
+      }
+
+      if (request.method === "initialize") {
+        if (era === "modern") {
+          return {
+            ok: false,
+            error: { code: -32022, message: "UnsupportedProtocolVersion" },
+            httpStatus: 400,
+          };
+        }
+        return {
+          ok: true,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            serverInfo: { name: "mock", version: "0" },
+          },
+          httpStatus: 200,
+          sessionId: "mock-session",
+        };
+      }
+
+      if (request.method === "server/discover" || request.method === "tools/list") {
+        return {
+          ok: true,
+          result: { tools },
+          httpStatus: 200,
+        };
+      }
+
+      if (request.method === "tools/call") {
+        const params = request.params as { name?: unknown; arguments?: unknown } | undefined;
+        const name = typeof params?.name === "string" ? params.name : "";
+        const output = options.onCall
+          ? await Promise.resolve(options.onCall(name, params?.arguments ?? {}, request.signal))
+          : { content: [{ type: "text", text: `ok:${name}` }] };
+        return { ok: true, result: output, httpStatus: 200 };
+      }
+
+      return {
+        ok: false,
+        error: { code: -32601, message: `method not found: ${request.method}` },
+        httpStatus: 200,
+      };
+    },
+    async close() {
+      /* mock */
+    },
+  };
+}
+
+function hangUntilAbort(signal?: AbortSignal): Promise<never> {
+  return new Promise((_, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal.reason));
+      return;
+    }
+    signal?.addEventListener(
+      "abort",
+      () => {
+        reject(abortError(signal.reason));
+      },
+      { once: true },
+    );
+  });
+}

package/src/elements/ai/mcp-protocol.ts

@@ -0,0 +1,234 @@
+/**
+ * MCP client protocol — 2026-07-28 happy path + dual-era fallback types.
+ *
+ * Reuses only the JSON-RPC envelope. Does not import the app MCP *server*
+ * dialect (`2024-11-05` initialize) as the client version.
+ */
+
+/** Current MCP protocol version (stateless core). */
+export const MCP_CLIENT_PROTOCOL_VERSION = "2026-07-28";
+
+/** Legacy initialize dialect still in production. */
+export const MCP_LEGACY_PROTOCOL_VERSION = "2024-11-05";
+
+/** JSON-RPC request id. */
+export type JsonRpcId = string | number;
+
+/** Modern protocol era vs initialize handshake. */
+export type McpProtocolEra = "modern" | "legacy";
+
+/** JSON-RPC error object. */
+export interface McpRpcError {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+/** Modern MCP error codes that are *not* a cue to `initialize`. */
+export const McpModernErrorCode = {
+  headerMismatch: -32020,
+  missingRequiredClientCapability: -32021,
+  unsupportedProtocolVersion: -32022,
+  /** Resource not found — remapped to invalid params; not version negotiation. */
+  resourceNotFound: -32002,
+} as const;
+
+/** Per-request `_meta` for the 2026-07-28 stateless core. */
+export interface McpClientMeta {
+  readonly "io.modelcontextprotocol/protocolVersion": typeof MCP_CLIENT_PROTOCOL_VERSION;
+  readonly clientCapabilities: {
+    readonly extensions: Readonly<Record<string, never>>;
+  };
+  readonly clientInfo: {
+    readonly name: string;
+    readonly version: string;
+  };
+}
+
+/** Tool listed by `tools/list`. */
+export interface McpListedTool {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly outputSchema?: unknown;
+}
+
+/** Parsed JSON-RPC success or error. */
+export type ParsedJsonRpcResponse =
+  | { readonly ok: true; readonly id: JsonRpcId | null; readonly result: unknown }
+  | { readonly ok: false; readonly id: JsonRpcId | null; readonly error: McpRpcError };
+
+/**
+ * Build the required per-request `_meta` bag.
+ *
+ * @param version - Client package version
+ */
+export function mcpClientMeta(version: string): McpClientMeta {
+  return {
+    "io.modelcontextprotocol/protocolVersion": MCP_CLIENT_PROTOCOL_VERSION,
+    clientCapabilities: { extensions: {} },
+    clientInfo: { name: "okengine", version },
+  };
+}
+
+/**
+ * True when a 400 JSON-RPC error is a modern protocol reject (do not initialize).
+ *
+ * @param code - JSON-RPC error code
+ */
+export function isModernProtocolReject(code: number): boolean {
+  return (
+    code === McpModernErrorCode.unsupportedProtocolVersion ||
+    code === McpModernErrorCode.headerMismatch ||
+    code === McpModernErrorCode.missingRequiredClientCapability
+  );
+}
+
+/**
+ * Parse a JSON-RPC 2.0 response object.
+ *
+ * @param body - Decoded JSON
+ */
+export function parseJsonRpcResponse(body: unknown): ParsedJsonRpcResponse | null {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+  const o = body as Record<string, unknown>;
+  if (o.jsonrpc !== "2.0") return null;
+  const id = o.id;
+  if (id !== null && id !== undefined && typeof id !== "string" && typeof id !== "number") {
+    return null;
+  }
+  const rid = (id ?? null) as JsonRpcId | null;
+  if ("error" in o) {
+    const err = o.error;
+    if (err === null || typeof err !== "object" || Array.isArray(err)) return null;
+    const e = err as Record<string, unknown>;
+    if (typeof e.code !== "number" || typeof e.message !== "string") return null;
+    return {
+      ok: false,
+      id: rid,
+      error: {
+        code: e.code,
+        message: e.message,
+        ...(e.data !== undefined ? { data: e.data } : {}),
+      },
+    };
+  }
+  if (!("result" in o)) return null;
+  return { ok: true, id: rid, result: o.result };
+}
+
+/**
+ * Parse `tools/list` result.tools.
+ *
+ * @param result - RPC result
+ */
+export function parseToolsListResult(result: unknown): McpListedTool[] {
+  if (result === null || typeof result !== "object" || Array.isArray(result)) return [];
+  const tools = (result as Record<string, unknown>).tools;
+  if (!Array.isArray(tools)) return [];
+  const out: McpListedTool[] = [];
+  for (const raw of tools) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const t = raw as Record<string, unknown>;
+    if (typeof t.name !== "string" || t.name.length === 0) continue;
+    out.push({
+      name: t.name,
+      ...(typeof t.description === "string" ? { description: t.description } : {}),
+      ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
+      ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Interpret `tools/call` result. Missing `resultType` means `"complete"`.
+ *
+ * @param result - RPC result
+ */
+export function interpretToolsCallResult(result: unknown): unknown {
+  if (result === null || typeof result !== "object" || Array.isArray(result)) {
+    return result;
+  }
+  const o = result as Record<string, unknown>;
+  const resultType = o.resultType;
+  if (resultType === undefined || resultType === "complete") return result;
+  if (resultType === "input_required") {
+    throw new Error("ai.mcp: tool returned input_required (HITL is not supported)");
+  }
+  const label = typeof resultType === "string" ? resultType : JSON.stringify(resultType);
+  throw new Error(`ai.mcp: unrecognized resultType "${label}"`);
+}
+
+/**
+ * Valid HTTP header token (RFC 9110).
+ *
+ * @param name - Candidate header name
+ */
+export function isHttpHeaderToken(name: string): boolean {
+  return name.length > 0 && /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/.test(name);
+}
+
+/**
+ * Collect `x-mcp-header` params → `Mcp-Param-*` headers.
+ * Returns null when a declared header name is invalid (caller drops the tool).
+ *
+ * @param inputSchema - Tool JSON schema
+ * @param args - Call arguments
+ */
+export function mcpParamHeaders(
+  inputSchema: unknown,
+  args: Record<string, unknown>,
+): { readonly headers: Record<string, string>; readonly body: Record<string, unknown> } | null {
+  const props = schemaProperties(inputSchema);
+  if (!props) return { headers: {}, body: { ...args } };
+  const headers: Record<string, string> = {};
+  const body: Record<string, unknown> = { ...args };
+  for (const [key, schema] of Object.entries(props)) {
+    const header = headerNameFromSchema(key, schema);
+    if (header === undefined) continue;
+    if (header === null) return null;
+    const value = args[key];
+    if (value === undefined) continue;
+    headers[header] = typeof value === "string" ? value : JSON.stringify(value);
+    delete body[key];
+  }
+  return { headers, body };
+}
+
+/**
+ * True when the tool's `x-mcp-header` annotations are all valid.
+ *
+ * @param inputSchema - Tool JSON schema
+ */
+export function mcpHeaderAnnotationsValid(inputSchema: unknown): boolean {
+  return mcpParamHeaders(inputSchema, {}) !== null;
+}
+
+function schemaProperties(inputSchema: unknown): Record<string, unknown> | undefined {
+  if (inputSchema === null || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+    return undefined;
+  }
+  const props = (inputSchema as Record<string, unknown>).properties;
+  if (props === null || typeof props !== "object" || Array.isArray(props)) return undefined;
+  return props as Record<string, unknown>;
+}
+
+function headerNameFromSchema(key: string, schema: unknown): string | null | undefined {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return undefined;
+  const raw = (schema as Record<string, unknown>)["x-mcp-header"];
+  if (raw === undefined || raw === false) return undefined;
+  const name =
+    raw === true
+      ? `Mcp-Param-${key
+          .split(/[-_]/)
+          .map((part) => (part[0] ? part[0].toUpperCase() + part.slice(1) : ""))
+          .join("")}`
+      : typeof raw === "string"
+        ? raw
+        : null;
+  if (name === null || !isHttpHeaderToken(name) || !name.toLowerCase().startsWith("mcp-param-")) {
+    return null;
+  }
+  return name;
+}

package/src/elements/ai/mcp-stdio.test.ts

@@ -0,0 +1,50 @@
+/**
+ * stdio MCP transport — cancel writes notifications/cancelled then kills.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createMcpStdioTransport, type StdioChild } from "./mcp-stdio.ts";
+
+describe("mcp stdio cancel", () => {
+  test("abort sends notifications/cancelled then kills the process", async () => {
+    const writes: string[] = [];
+    let killed = false;
+    const stdin = new TransformStream<Uint8Array, Uint8Array>();
+    const stdout = new TransformStream<Uint8Array, Uint8Array>();
+    const reader = stdin.readable.getReader();
+    const decoder = new TextDecoder();
+    void (async () => {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        writes.push(decoder.decode(value));
+      }
+    })();
+
+    const child: StdioChild = {
+      stdin: stdin.writable,
+      stdout: stdout.readable,
+      kill() {
+        killed = true;
+      },
+    };
+    const transport = createMcpStdioTransport({
+      command: "mcp-server",
+      spawn: () => child,
+    });
+    const ctrl = new AbortController();
+    const pending = transport.request({
+      id: 1,
+      method: "tools/call",
+      params: { name: "create_issue" },
+      headers: {},
+      signal: ctrl.signal,
+      cancelMode: "stdio",
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    ctrl.abort();
+    await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+    expect(killed).toBe(true);
+    expect(writes.some((w) => w.includes("notifications/cancelled"))).toBe(true);
+  });
+});