okengine 0.13.0 → 0.14.1

package/src/elements/ai/errors.ts

@@ -74,8 +74,10 @@ export function isRetryableAiError(err: unknown): boolean {
     if (code >= 400 && code <= 499) return false;
   }
 
-  if (name === "AbortError" || name === "TimeoutError") return true;
-  if (lower.includes("aborterror") || lower.includes("timeout")) return true;
+  if (name === "TimeoutError" || isTimeoutAbort(err)) return true;
+  // Client disconnect / explicit cancel must not retry or advance `via`.
+  if (name === "AbortError") return false;
+  if (name === "AiBudgetExceededError") return false;
   if (
     lower.includes("econnreset") ||
     lower.includes("econnrefused") ||
@@ -103,6 +105,32 @@ export function aiHttpError(message: string, status: number): Error {
   return err;
 }
 
+/**
+ * True when an abort came from a deadline (`AbortSignal.timeout`), not a
+ * client disconnect / explicit cancel.
+ *
+ * @param err - Thrown value
+ */
+function isTimeoutAbort(err: unknown): boolean {
+  if (err == null || typeof err !== "object") return false;
+  const name = err instanceof Error ? err.name : "";
+  const message = err instanceof Error ? err.message.toLowerCase() : "";
+  if (name === "TimeoutError") return true;
+  if (message.includes("timeout")) return true;
+  const cause = "cause" in err ? (err as { cause: unknown }).cause : undefined;
+  if (cause instanceof Error && (cause.name === "TimeoutError" || /timeout/i.test(cause.message))) {
+    return true;
+  }
+  const reason = "reason" in err ? (err as { reason: unknown }).reason : undefined;
+  if (
+    reason instanceof Error &&
+    (reason.name === "TimeoutError" || /timeout/i.test(reason.message))
+  ) {
+    return true;
+  }
+  return false;
+}
+
 function readStatus(err: unknown): number | undefined {
   if (typeof err !== "object" || err === null) return undefined;
   const status = (err as AiErrorFields).status;

package/src/elements/ai/eval.ts

@@ -124,11 +124,9 @@ export async function runPromptEvals(options: RunPromptEvalsOptions): Promise<Ev
  * @param text - File text
  */
 export function parseEvalJsonl(text: string): EvalCase[] {
-  const cases: EvalCase[] = [];
-  for (const line of text.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    cases.push(JSON.parse(trimmed) as EvalCase);
+  const jsonl = (Bun as typeof Bun & { JSONL?: { parse: (t: string) => unknown[] } }).JSONL;
+  if (!jsonl) {
+    throw new Error("ai.eval: Bun.JSONL is required (Bun >= 1.4.0)");
   }
-  return cases;
+  return jsonl.parse(text) as EvalCase[];
 }

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

@@ -0,0 +1,206 @@
+/**
+ * MCP client — allowlist, era fallback, abort, capability.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createMockAiDriver } from "../../drivers/ai-mock.ts";
+import { createFx } from "../../kernel/fx.ts";
+import {
+  mcpCapabilityRefFromName,
+  mcpModelToolName,
+  parseMcpToolRef,
+} from "../../manifest/mcp-ref.ts";
+import { ai } from "./declare.ts";
+import { createMcpClient } from "./mcp-client.ts";
+import { createMockMcpTransport } from "./mcp-mock.ts";
+import { createAiRuntime } from "./runtime.ts";
+
+describe("mcp refs", () => {
+  test("parses capability and model names", () => {
+    expect(parseMcpToolRef("mcp:github/create_issue")).toEqual({
+      server: "github",
+      tool: "create_issue",
+    });
+    expect(mcpModelToolName("github", "create_issue")).toBe("github__create_issue");
+    expect(mcpCapabilityRefFromName("github__create_issue")).toBe("mcp:github/create_issue");
+    expect(parseMcpToolRef("github/create_issue")).toBeNull();
+  });
+});
+
+describe("mcp client allowlist", () => {
+  test("drops extras from tools/list and calls only allowlisted tools", async () => {
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const called: string[] = [];
+    const transport = createMockMcpTransport({
+      tools: [
+        { name: "create_issue", description: "Open an issue" },
+        { name: "delete_repo", description: "should be dropped" },
+      ],
+      extraTools: [{ name: "admin_wipe" }],
+      onCall: (name) => {
+        called.push(name);
+        return { content: [{ type: "text", text: "opened" }] };
+      },
+    });
+    const client = createMcpClient({
+      servers: [github],
+      transports: { github: transport },
+    });
+    const listed = await client.listedTool({ server: "github", tool: "create_issue" });
+    expect(listed?.name).toBe("create_issue");
+    expect(await client.listedTool({ server: "github", tool: "delete_repo" })).toBeUndefined();
+    await client.call("mcp:github/create_issue", { title: "bug" });
+    expect(called).toEqual(["create_issue"]);
+    await expect(client.call("mcp:github/delete_repo", {})).rejects.toThrow(/not allowlisted/);
+  });
+});
+
+describe("mcp era fallback", () => {
+  test("400 + UnsupportedProtocolVersion stays modern (no initialize)", async () => {
+    const methods: string[] = [];
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const transport = createMockMcpTransport({
+      tools: [{ name: "create_issue" }],
+      httpStatusOnFirst: 400,
+      firstError: { code: -32022, message: "UnsupportedProtocolVersion" },
+    });
+    const wrapped = {
+      kind: "mock" as const,
+      async request(req: Parameters<typeof transport.request>[0]) {
+        methods.push(req.method);
+        return transport.request(req);
+      },
+      close: () => transport.close(),
+    };
+    const client = createMcpClient({
+      servers: [github],
+      transports: { github: wrapped },
+    });
+    await expect(client.listedTool({ server: "github", tool: "create_issue" })).rejects.toThrow(
+      /UnsupportedProtocolVersion/,
+    );
+    expect(methods).toEqual(["tools/list"]);
+  });
+
+  test("400 without a modern body falls back to initialize", async () => {
+    const methods: string[] = [];
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const transport = createMockMcpTransport({
+      era: "legacy",
+      tools: [{ name: "create_issue" }],
+      httpStatusOnFirst: 400,
+      firstBody: "bad request",
+    });
+    const wrapped = {
+      kind: "mock" as const,
+      async request(req: Parameters<typeof transport.request>[0]) {
+        methods.push(req.method);
+        return transport.request(req);
+      },
+      close: () => transport.close(),
+    };
+    const client = createMcpClient({
+      servers: [github],
+      transports: { github: wrapped },
+    });
+    const listed = await client.listedTool({ server: "github", tool: "create_issue" });
+    expect(listed?.name).toBe("create_issue");
+    expect(methods).toEqual(["tools/list", "initialize", "tools/list"]);
+  });
+});
+
+describe("mcp abort", () => {
+  test("HTTP cancel aborts an in-flight mock request", async () => {
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const transport = createMockMcpTransport({
+      tools: [{ name: "create_issue" }],
+      delayMs: 5_000,
+    });
+    const client = createMcpClient({
+      servers: [github],
+      transports: { github: transport },
+    });
+    const ctrl = new AbortController();
+    const pending = client.call("mcp:github/create_issue", {}, ctrl.signal);
+    ctrl.abort();
+    await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+  });
+});
+
+describe("mcp capability + toolLoop", () => {
+  test("undeclared MCP tool throws OKE1007", async () => {
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const runtime = createAiRuntime({
+      mcpServers: [github],
+      mcpTransports: { github: createMockMcpTransport({ tools: [{ name: "create_issue" }] }) },
+    });
+    const fx = createFx({
+      flow: "support.triage",
+      effects: { asks: ["triage"] },
+      aiRuntime: runtime,
+    });
+    try {
+      await fx.call(github.tool("create_issue"), { title: "x" });
+      throw new Error("expected OKE1007");
+    } catch (err) {
+      expect(err).toMatchObject({ code: 1007 });
+    }
+  });
+
+  test("model-facing server__tool dispatches through fx.call as mcp: ref", async () => {
+    const github = ai.mcpServer("github", {
+      url: "https://mcp.example/github",
+      tools: ["create_issue"],
+    });
+    const called: string[] = [];
+    const runtime = createAiRuntime({
+      models: [ai.model("smart")],
+      prompts: [ai.model("smart").prompt("triage")],
+      mcpServers: [github],
+      mcpTransports: {
+        github: createMockMcpTransport({
+          tools: [{ name: "create_issue", description: "Open an issue" }],
+          onCall: (name) => {
+            called.push(name);
+            return { content: [{ type: "text", text: "ok" }] };
+          },
+        }),
+      },
+      defaultDriver: createMockAiDriver({
+        "*": {
+          __toolCalls: [{ id: "c1", name: "github__create_issue", arguments: { title: "bug" } }],
+        },
+      }),
+    });
+    const fx = createFx({
+      flow: "support.triage",
+      effects: { asks: ["triage"], calls: ["mcp:github/create_issue"] },
+      aiRuntime: runtime,
+    });
+    await runtime.ask(
+      "triage",
+      { q: "open" },
+      {
+        tools: ["mcp:github/create_issue"],
+        maxSteps: 1,
+        callTool: (name, input) => fx.call(name, input),
+      },
+    );
+    expect(called).toEqual(["create_issue"]);
+  });
+});

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

@@ -0,0 +1,362 @@
+/**
+ * MCP client session — modern `_meta` first, dual-era fallback, allowlist filter.
+ */
+
+import type { AiMcpServerDecl } from "./declare.ts";
+import { parseMcpToolRef, type ParsedMcpToolRef } from "../../manifest/mcp-ref.ts";
+import { createMcpHttpTransport } from "./mcp-http.ts";
+import { createMcpStdioTransport } from "./mcp-stdio.ts";
+import {
+  interpretToolsCallResult,
+  isModernProtocolReject,
+  MCP_CLIENT_PROTOCOL_VERSION,
+  MCP_LEGACY_PROTOCOL_VERSION,
+  mcpClientMeta,
+  mcpHeaderAnnotationsValid,
+  mcpParamHeaders,
+  parseToolsListResult,
+  type McpClientMeta,
+  type McpListedTool,
+  type McpProtocolEra,
+} from "./mcp-protocol.ts";
+import { McpTransportError, type McpTransport, type McpWireResult } from "./mcp-transport.ts";
+
+/** Options for {@link createMcpClient}. */
+export interface CreateMcpClientOptions {
+  readonly servers?: readonly AiMcpServerDecl[];
+  readonly resolveSecret?: (name: string) => string | Promise<string>;
+  readonly transports?: Readonly<Record<string, McpTransport>>;
+  readonly clientVersion?: string;
+}
+
+/** Allowlisted tool + cached schema. */
+export interface McpResolvedTool {
+  readonly server: string;
+  readonly tool: string;
+  readonly ref: string;
+  readonly listed?: McpListedTool;
+}
+
+/** MCP client used by the AI runtime. */
+export interface McpClient {
+  readonly servers: ReadonlyMap<string, AiMcpServerDecl>;
+  listedTool(ref: ParsedMcpToolRef, signal?: AbortSignal): Promise<McpListedTool | undefined>;
+  call(ref: string, input: unknown, signal?: AbortSignal): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+interface ServerSession {
+  readonly decl: AiMcpServerDecl;
+  readonly transport: McpTransport;
+  readonly eraKey: string;
+  readonly cancelMode: "http" | "stdio";
+  era?: McpProtocolEra;
+  sessionId?: string;
+  listed?: readonly McpListedTool[];
+}
+
+/**
+ * Create an MCP client for declared servers.
+ *
+ * @param options - Decls + optional injected transports (tests)
+ */
+export function createMcpClient(options: CreateMcpClientOptions = {}): McpClient {
+  const meta = mcpClientMeta(options.clientVersion ?? process.env.npm_package_version ?? "0.0.0");
+  const servers = new Map<string, AiMcpServerDecl>();
+  for (const decl of options.servers ?? []) servers.set(decl.name, decl);
+  const sessions = new Map<string, ServerSession>();
+  const eraByKey = new Map<string, McpProtocolEra>();
+  let nextId = 1;
+
+  function sessionFor(decl: AiMcpServerDecl): ServerSession {
+    const existing = sessions.get(decl.name);
+    if (existing) return existing;
+    const injected = options.transports?.[decl.name];
+    const transport = injected ?? transportFor(decl, options.resolveSecret);
+    const eraKey = decl.url
+      ? httpOrigin(decl.url)
+      : `stdio:${decl.command}:${(decl.args ?? []).join("\0")}`;
+    const session: ServerSession = {
+      decl,
+      transport,
+      eraKey,
+      cancelMode: decl.url ? "http" : "stdio",
+      era: eraByKey.get(eraKey),
+    };
+    sessions.set(decl.name, session);
+    return session;
+  }
+
+  async function rpc(
+    session: ServerSession,
+    method: string,
+    params: unknown,
+    signal: AbortSignal | undefined,
+    extra: { readonly toolName?: string; readonly extraHeaders?: Record<string, string> } = {},
+  ): Promise<unknown> {
+    const id = nextId++;
+    const era = session.era ?? "modern";
+    const headers = requestHeaders(
+      method,
+      era,
+      session.sessionId,
+      extra.toolName,
+      extra.extraHeaders,
+    );
+    const wireParams = era === "modern" ? withMeta(params, meta) : params;
+    const result = await session.transport.request({
+      id,
+      method,
+      ...(wireParams !== undefined ? { params: wireParams } : {}),
+      headers,
+      ...(signal !== undefined ? { signal } : {}),
+      cancelMode: session.cancelMode,
+    });
+    if (result.sessionId) session.sessionId = result.sessionId;
+    return result;
+  }
+
+  async function ensureEra(session: ServerSession, signal?: AbortSignal): Promise<void> {
+    if (session.era) return;
+    const cached = eraByKey.get(session.eraKey);
+    if (cached) {
+      session.era = cached;
+      if (cached === "legacy") await initializeLegacy(session, signal);
+      return;
+    }
+
+    const probeMethod = session.cancelMode === "stdio" ? "server/discover" : "tools/list";
+    const probeSignal = session.cancelMode === "stdio" ? withTimeout(signal, 2_000) : signal;
+    let first: McpWireResult;
+    try {
+      first = (await rpc(session, probeMethod, {}, probeSignal)) as McpWireResult;
+    } catch (err) {
+      if (session.cancelMode === "stdio") {
+        setEra(session, "legacy");
+        await initializeLegacy(session, signal);
+        return;
+      }
+      throw err;
+    }
+    if (first.ok) {
+      setEra(session, "modern");
+      if (probeMethod === "tools/list") {
+        session.listed = filterAllowlist(session.decl, parseToolsListResult(first.result));
+      }
+      return;
+    }
+
+    const decision = classifyFirstError(first, session.cancelMode);
+    if (decision === "modern") {
+      setEra(session, "modern");
+      throw rpcFailure(first, probeMethod);
+    }
+    if (decision === "fail") {
+      throw rpcFailure(first, probeMethod);
+    }
+
+    setEra(session, "legacy");
+    await initializeLegacy(session, signal);
+  }
+
+  async function initializeLegacy(session: ServerSession, signal?: AbortSignal): Promise<void> {
+    const result = (await rpc(
+      session,
+      "initialize",
+      {
+        protocolVersion: MCP_LEGACY_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: meta.clientInfo,
+      },
+      signal,
+    )) as McpWireResult;
+    if (!result.ok) throw rpcFailure(result, "initialize");
+    if (result.sessionId) session.sessionId = result.sessionId;
+    // `initialized` notification is optional; HTTP clients do not need it.
+  }
+
+  function setEra(session: ServerSession, era: McpProtocolEra): void {
+    session.era = era;
+    eraByKey.set(session.eraKey, era);
+  }
+
+  async function listTools(
+    session: ServerSession,
+    signal?: AbortSignal,
+  ): Promise<readonly McpListedTool[]> {
+    if (session.listed) return session.listed;
+    await ensureEra(session, signal);
+    if (session.listed) return session.listed;
+    const result = (await rpc(session, "tools/list", {}, signal)) as McpWireResult;
+    if (!result.ok) throw rpcFailure(result, "tools/list");
+    session.listed = filterAllowlist(session.decl, parseToolsListResult(result.result));
+    return session.listed;
+  }
+
+  return {
+    servers,
+    async listedTool(ref, signal) {
+      const decl = servers.get(ref.server);
+      if (!decl) return undefined;
+      const listed = await listTools(sessionFor(decl), signal);
+      return listed.find((t) => t.name === ref.tool);
+    },
+    async call(ref, input, signal) {
+      const parsed = parseMcpToolRef(ref);
+      if (!parsed) throw new Error(`ai.mcp: invalid tool ref "${ref}"`);
+      const decl = servers.get(parsed.server);
+      if (!decl) throw new Error(`ai.mcp: unknown server "${parsed.server}"`);
+      if (!decl.tools.includes(parsed.tool)) {
+        throw new Error(`ai.mcp: tool "${parsed.tool}" is not allowlisted on "${parsed.server}"`);
+      }
+      const session = sessionFor(decl);
+      await ensureEra(session, signal);
+      const listed = await listTools(session, signal);
+      const tool = listed.find((t) => t.name === parsed.tool);
+      const args =
+        input && typeof input === "object" && !Array.isArray(input)
+          ? (input as Record<string, unknown>)
+          : {};
+      const split = mcpParamHeaders(tool?.inputSchema, args);
+      if (split === null) {
+        throw new Error(`ai.mcp: tool "${parsed.tool}" has an invalid x-mcp-header annotation`);
+      }
+      const result = (await rpc(
+        session,
+        "tools/call",
+        {
+          name: parsed.tool,
+          arguments: split.body,
+        },
+        signal,
+        {
+          toolName: parsed.tool,
+          extraHeaders: split.headers,
+        },
+      )) as McpWireResult;
+      if (!result.ok) throw rpcFailure(result, "tools/call");
+      return interpretToolsCallResult(result.result);
+    },
+    async close() {
+      await Promise.all([...sessions.values()].map((s) => s.transport.close()));
+      sessions.clear();
+    },
+  };
+}
+
+function transportFor(
+  decl: AiMcpServerDecl,
+  resolveSecret?: (name: string) => string | Promise<string>,
+): McpTransport {
+  if (decl.url) {
+    return {
+      kind: "http",
+      async request(request) {
+        const bearer = decl.auth && resolveSecret ? await resolveSecret(decl.auth) : undefined;
+        const inner = createMcpHttpTransport({
+          url: decl.url!,
+          ...(bearer !== undefined ? { bearer } : {}),
+        });
+        return inner.request(request);
+      },
+      async close() {
+        /* per-request */
+      },
+    };
+  }
+  return createMcpStdioTransport({
+    command: decl.command!,
+    ...(decl.args !== undefined ? { args: decl.args } : {}),
+  });
+}
+
+function withMeta(params: unknown, meta: McpClientMeta): unknown {
+  const base =
+    params && typeof params === "object" && !Array.isArray(params)
+      ? (params as Record<string, unknown>)
+      : {};
+  return { ...base, _meta: meta };
+}
+
+function requestHeaders(
+  method: string,
+  era: McpProtocolEra,
+  sessionId: string | undefined,
+  toolName: string | undefined,
+  extra: Record<string, string> | undefined,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "MCP-Protocol-Version":
+      era === "modern" ? MCP_CLIENT_PROTOCOL_VERSION : MCP_LEGACY_PROTOCOL_VERSION,
+    "Mcp-Method": method,
+    ...extra,
+  };
+  if (method === "tools/call" && toolName) headers["Mcp-Name"] = toolName;
+  if (era === "legacy" && sessionId) headers["Mcp-Session-Id"] = sessionId;
+  return headers;
+}
+
+function filterAllowlist(decl: AiMcpServerDecl, listed: McpListedTool[]): McpListedTool[] {
+  const allow = new Set(decl.tools);
+  return listed.filter((t) => allow.has(t.name) && mcpHeaderAnnotationsValid(t.inputSchema));
+}
+
+function classifyFirstError(
+  result: McpWireResult,
+  mode: "http" | "stdio",
+): "modern" | "legacy" | "fail" {
+  const code = result.error?.code;
+  if (code !== undefined && isModernProtocolReject(code)) return "modern";
+  if (mode === "stdio") return "legacy";
+  const status = result.httpStatus;
+  if (status === 401 || status === 403) return "fail";
+  if (status !== undefined && status >= 500) return "fail";
+  if (status === 400) return "legacy";
+  return "fail";
+}
+
+function rpcFailure(result: McpWireResult, method: string): Error {
+  if (result.error) {
+    return new McpTransportError(`ai.mcp: ${method} failed: ${result.error.message}`, {
+      ...(result.httpStatus !== undefined ? { httpStatus: result.httpStatus } : {}),
+      rpc: result.error,
+    });
+  }
+  return new McpTransportError(`ai.mcp: ${method} failed`, {
+    ...(result.httpStatus !== undefined ? { httpStatus: result.httpStatus } : {}),
+    network: result.httpStatus === undefined,
+  });
+}
+
+function httpOrigin(url: string): string {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
+function withTimeout(parent: AbortSignal | undefined, ms: number): AbortSignal {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(new Error("ai.mcp: stdio discover timeout")), ms);
+  const unlink = (): void => {
+    clearTimeout(timer);
+  };
+  if (parent) {
+    if (parent.aborted) {
+      clearTimeout(timer);
+      ctrl.abort(parent.reason);
+    } else {
+      parent.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          ctrl.abort(parent.reason);
+        },
+        { once: true },
+      );
+    }
+  }
+  ctrl.signal.addEventListener("abort", unlink, { once: true });
+  return ctrl.signal;
+}