okengine 0.13.0 → 0.15.2

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);
+  });
+});

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

@@ -0,0 +1,212 @@
+/**
+ * stdio MCP transport — newline-delimited JSON-RPC over a child process.
+ *
+ * Cancel = `notifications/cancelled` then kill the process.
+ */
+
+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";
+
+/** Byte writer used by {@link StdioChild.stdin}. */
+export interface StdioWriter {
+  write(data: Uint8Array): Promise<void> | void;
+  close(): Promise<void> | void;
+}
+
+/** Options for {@link createMcpStdioTransport}. */
+export interface CreateMcpStdioTransportOptions {
+  readonly command: string;
+  readonly args?: readonly string[];
+  readonly spawn?: (cmd: string, args: readonly string[]) => StdioChild;
+}
+
+/** Minimal child-process handle (Bun.spawn-compatible). */
+export interface StdioChild {
+  readonly stdin: StdioWriter | WritableStream<Uint8Array> | null;
+  readonly stdout: ReadableStream<Uint8Array> | null;
+  readonly killed?: boolean;
+  kill(): void;
+}
+
+interface Pending {
+  readonly resolve: (value: McpWireResult) => void;
+  readonly reject: (reason: unknown) => void;
+}
+
+/**
+ * Create a stdio transport. The process is spawned on first request.
+ *
+ * @param options - Command + args (never a shell string)
+ */
+export function createMcpStdioTransport(options: CreateMcpStdioTransportOptions): McpTransport {
+  let child: StdioChild | undefined;
+  let writer: StdioWriter | undefined;
+  const pending = new Map<string, Pending>();
+  let readLoop: Promise<void> | undefined;
+  const encoder = new TextEncoder();
+
+  async function ensureChild(): Promise<void> {
+    if (child) return;
+    const spawn = options.spawn ?? defaultSpawn;
+    child = spawn(options.command, options.args ?? []);
+    if (!child.stdin || !child.stdout) {
+      throw new Error("ai.mcp: stdio process is missing stdin/stdout");
+    }
+    writer = asWriter(child.stdin);
+    readLoop = consumeStdout(child.stdout, pending);
+  }
+
+  return {
+    kind: "stdio",
+    async request(request: McpTransportRequest): Promise<McpWireResult> {
+      if (request.signal?.aborted) throw abortError(request.signal.reason);
+      await ensureChild();
+      if (!writer) throw new Error("ai.mcp: stdio stdin is not writable");
+      const key = String(request.id);
+      const envelope = JSON.stringify({
+        jsonrpc: "2.0",
+        id: request.id,
+        method: request.method,
+        ...(request.params !== undefined ? { params: request.params } : {}),
+      });
+      const result = new Promise<McpWireResult>((resolve, reject) => {
+        pending.set(key, { resolve, reject });
+      });
+      const onAbort = (): void => {
+        void writeLine(
+          writer!,
+          encoder,
+          JSON.stringify({
+            jsonrpc: "2.0",
+            method: "notifications/cancelled",
+            params: { requestId: request.id },
+          }),
+        ).finally(() => {
+          child?.kill();
+          child = undefined;
+          writer = undefined;
+          rejectAll(pending, abortError(request.signal?.reason));
+        });
+      };
+      request.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        await writeLine(writer, encoder, envelope);
+        return await result;
+      } finally {
+        request.signal?.removeEventListener("abort", onAbort);
+        pending.delete(key);
+      }
+    },
+    async close() {
+      child?.kill();
+      child = undefined;
+      try {
+        await writer?.close();
+      } catch {
+        /* already closed */
+      }
+      writer = undefined;
+      rejectAll(pending, new Error("ai.mcp: stdio transport closed"));
+      await readLoop?.catch(() => undefined);
+    },
+  };
+}
+
+function defaultSpawn(command: string, args: readonly string[]): StdioChild {
+  const proc = Bun.spawn([command, ...args], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    stdin: {
+      write(data) {
+        proc.stdin.write(data);
+      },
+      close() {
+        proc.stdin.end();
+      },
+    },
+    stdout: proc.stdout,
+    kill() {
+      proc.kill();
+    },
+  };
+}
+
+function asWriter(stdin: StdioWriter | WritableStream<Uint8Array>): StdioWriter {
+  if (isWritableStream(stdin)) {
+    const streamWriter = stdin.getWriter();
+    return {
+      write: (data) => streamWriter.write(data),
+      close: () => streamWriter.close(),
+    };
+  }
+  return stdin;
+}
+
+function isWritableStream(
+  value: StdioWriter | WritableStream<Uint8Array>,
+): value is WritableStream<Uint8Array> {
+  return "getWriter" in value && typeof value.getWriter === "function";
+}
+
+async function writeLine(writer: StdioWriter, encoder: TextEncoder, line: string): Promise<void> {
+  await writer.write(encoder.encode(`${line}\n`));
+}
+
+async function consumeStdout(
+  stdout: ReadableStream<Uint8Array>,
+  pending: Map<string, Pending>,
+): Promise<void> {
+  const decoder = new TextDecoder();
+  const reader = stdout.getReader();
+  let buf = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let json: unknown;
+        try {
+          json = JSON.parse(trimmed) as unknown;
+        } catch {
+          continue;
+        }
+        const parsed = parseJsonRpcResponse(json);
+        if (!parsed) continue;
+        const key = parsed.id === null ? undefined : String(parsed.id);
+        if (key === undefined) continue;
+        const waiter = pending.get(key);
+        if (!waiter) continue;
+        pending.delete(key);
+        if (parsed.ok) {
+          waiter.resolve({ ok: true, result: parsed.result, rawBody: json });
+        } else {
+          waiter.resolve({ ok: false, error: parsed.error, rawBody: json });
+        }
+      }
+    }
+  } catch (err) {
+    rejectAll(pending, err);
+  } finally {
+    reader.releaseLock();
+    rejectAll(pending, new McpTransportError("ai.mcp: stdio process ended", { network: true }));
+  }
+}
+
+function rejectAll(pending: Map<string, Pending>, reason: unknown): void {
+  for (const waiter of pending.values()) waiter.reject(reason);
+  pending.clear();
+}

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

@@ -0,0 +1,70 @@
+/**
+ * MCP client transport contract — HTTP, stdio, and test mock.
+ */
+
+import type { McpRpcError } from "./mcp-protocol.ts";
+
+/** Outbound JSON-RPC request. */
+export interface McpTransportRequest {
+  readonly id: string | number;
+  readonly method: string;
+  readonly params?: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly signal?: AbortSignal;
+  /** HTTP clients MUST abort fetch / SSE. stdio writes `notifications/cancelled` then kills. */
+  readonly cancelMode: "http" | "stdio";
+}
+
+/** Wire result (HTTP status present only for Streamable HTTP). */
+export interface McpWireResult {
+  readonly ok: boolean;
+  readonly result?: unknown;
+  readonly error?: McpRpcError;
+  readonly httpStatus?: number;
+  readonly sessionId?: string;
+  readonly rawBody?: unknown;
+}
+
+/** Bidirectional MCP transport. */
+export interface McpTransport {
+  readonly kind: "http" | "stdio" | "mock";
+  /**
+   * Send one JSON-RPC request and wait for the matching response.
+   *
+   * @param request - Envelope + headers + abort
+   */
+  request(request: McpTransportRequest): Promise<McpWireResult>;
+  /** Release the process / connection. */
+  close(): Promise<void>;
+}
+
+/**
+ * Transport / protocol failure with enough shape for era fallback.
+ */
+export class McpTransportError extends Error {
+  readonly httpStatus?: number;
+  readonly rpc?: McpRpcError;
+  readonly network?: boolean;
+  readonly timeout?: boolean;
+
+  /**
+   * @param message - Diagnostic
+   * @param extras - HTTP / RPC / network flags
+   */
+  constructor(
+    message: string,
+    extras: {
+      readonly httpStatus?: number;
+      readonly rpc?: McpRpcError;
+      readonly network?: boolean;
+      readonly timeout?: boolean;
+    } = {},
+  ) {
+    super(message);
+    this.name = "McpTransportError";
+    if (extras.httpStatus !== undefined) this.httpStatus = extras.httpStatus;
+    if (extras.rpc !== undefined) this.rpc = extras.rpc;
+    if (extras.network !== undefined) this.network = extras.network;
+    if (extras.timeout !== undefined) this.timeout = extras.timeout;
+  }
+}