okengine 0.13.0 → 0.15.2

package/src/drivers/types.ts

@@ -62,6 +62,16 @@ export interface SqlConnection {
    * @param params - Bound parameters
    */
   exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+  /**
+   * Pin `fn` to one backend connection for a single transaction.
+   *
+   * Required for `SET LOCAL` RLS stamps on pooled `postgres` (Bun.SQL /
+   * PgDog transaction mode). A standalone `BEGIN` via {@link exec} returns
+   * the connection to the pool still in a transaction and exhausts checkout.
+   *
+   * @param fn - Work that must share the reserved connection
+   */
+  transaction?<T>(fn: (tx: SqlConnection) => Promise<T>): Promise<T>;
   /** Close the connection. */
   close(): Promise<void>;
 }

package/src/elements/ai/declare.ts

@@ -7,9 +7,12 @@
 import {
   aiAgentRegistry,
   aiEmbedRegistry,
+  aiMcpServerRegistry,
   aiModelRegistry,
   aiPromptRegistry,
 } from "../../kernel/element-registries.ts";
+import { mcpToolRef, type McpToolRef } from "../../manifest/mcp-ref.ts";
+import type { VaultSecretDecl } from "../vault/declare.ts";
 
 /** Budget for a prompt or agent. */
 export interface AiBudgetDecl {
@@ -30,6 +33,11 @@ export interface AiModelOptions {
   readonly baseUrl?: string;
   /** Optional API key override for this binding (cloud providers). */
   readonly apiKey?: string;
+  /**
+   * Protocol driver for this binding (`anthropic`, `ollama`, …).
+   * When omitted, the app-level default driver is used.
+   */
+  readonly driverId?: string;
 }
 
 /**
@@ -77,6 +85,7 @@ export interface AiModelDecl {
   readonly model?: string;
   readonly baseUrl?: string;
   readonly apiKey?: string;
+  readonly driverId?: string;
   /**
    * Declare a versioned prompt artifact on this model.
    *
@@ -118,6 +127,54 @@ export interface AiAgentDecl {
   readonly budget?: AiBudgetDecl;
 }
 
+/** Bearer auth for {@link ai.mcpServer} — secret contract, never a token literal. */
+export interface AiMcpServerAuthOptions {
+  readonly bearer: VaultSecretDecl | string;
+}
+
+/** Options for {@link ai.mcpServer}. */
+export interface AiMcpServerOptions {
+  /** Streamable HTTP endpoint. */
+  readonly url?: string;
+  /** stdio executable (no shell string). */
+  readonly command?: string;
+  /** Arguments for {@link command}. */
+  readonly args?: readonly string[];
+  /** Bearer secret contract (`vault.secret` handle or name). */
+  readonly auth?: AiMcpServerAuthOptions;
+  /**
+   * Required allowlist of tool names on this server.
+   * The runtime never offers whatever `tools/list` happens to expose.
+   */
+  readonly tools: readonly string[];
+}
+
+/** Named capability ref returned by {@link AiMcpServerDecl.tool}. */
+export interface AiMcpToolRef {
+  readonly name: McpToolRef;
+}
+
+/**
+ * Declared external MCP server — tools join `fx.call` / `toolLoop` as
+ * `mcp:<server>/<tool>`.
+ */
+export interface AiMcpServerDecl {
+  readonly kind: "mcp-server";
+  readonly name: string;
+  readonly url?: string;
+  readonly command?: string;
+  readonly args?: readonly string[];
+  /** Secret contract name when bearer auth is declared. */
+  readonly auth?: string;
+  readonly tools: readonly string[];
+  /**
+   * Capability ref for one allowlisted tool (`mcp:<server>/<tool>`).
+   *
+   * @param tool - Tool name on this server
+   */
+  tool(tool: string): AiMcpToolRef;
+}
+
 /**
  * Resolve a tool ref to a flow name.
  *
@@ -152,6 +209,13 @@ export interface AiNamespace {
    * @param options - Tools / maxSteps / model / budget
    */
   agent(name: string, options?: AiAgentOptions): AiAgentDecl;
+  /**
+   * Declare an external MCP server whose allowlisted tools join `fx.call`.
+   *
+   * @param name - Server id (`github`, `linear`, …)
+   * @param options - Transport + required tool allowlist
+   */
+  mcpServer(name: string, options: AiMcpServerOptions): AiMcpServerDecl;
 }
 
 /**
@@ -162,12 +226,14 @@ export function listAiDecls(): {
   readonly prompts: readonly AiPromptDecl[];
   readonly embeds: readonly AiEmbedDecl[];
   readonly agents: readonly AiAgentDecl[];
+  readonly mcpServers: readonly AiMcpServerDecl[];
 } {
   return {
     models: aiModelRegistry.slice(),
     prompts: aiPromptRegistry.slice(),
     embeds: aiEmbedRegistry.slice(),
     agents: aiAgentRegistry.slice(),
+    mcpServers: aiMcpServerRegistry.slice(),
   };
 }
 
@@ -179,6 +245,7 @@ export function resetAiDecls(): void {
   aiPromptRegistry.length = 0;
   aiEmbedRegistry.length = 0;
   aiAgentRegistry.length = 0;
+  aiMcpServerRegistry.length = 0;
 }
 
 /**
@@ -201,6 +268,7 @@ export const ai: AiNamespace = {
       ...(options.model !== undefined ? { model: options.model } : {}),
       ...(options.baseUrl !== undefined ? { baseUrl: options.baseUrl } : {}),
       ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+      ...(options.driverId !== undefined ? { driverId: options.driverId } : {}),
       prompt(promptName, promptOpts = {}) {
         const promptDecl: AiPromptDecl = {
           kind: "prompt",
@@ -263,4 +331,45 @@ export const ai: AiNamespace = {
     aiAgentRegistry.push(decl);
     return decl;
   },
+
+  /**
+   * Declare an external MCP server whose allowlisted tools join `fx.call`.
+   *
+   * @param name - Server id
+   * @param options - Transport + required tool allowlist
+   */
+  mcpServer(name: string, options: AiMcpServerOptions): AiMcpServerDecl {
+    if (!name) throw new TypeError("ai.mcpServer: name is required");
+    if (name.includes("/") || name.includes("__")) {
+      throw new TypeError(`ai.mcpServer: name "${name}" must not contain "/" or "__"`);
+    }
+    if (!options.tools || !Array.isArray(options.tools)) {
+      throw new TypeError("ai.mcpServer: tools allowlist is required");
+    }
+    const hasUrl = typeof options.url === "string" && options.url.length > 0;
+    const hasCommand = typeof options.command === "string" && options.command.length > 0;
+    if (hasUrl === hasCommand) {
+      throw new TypeError("ai.mcpServer: declare exactly one of url or command");
+    }
+    const allow = new Set(options.tools);
+    const authName =
+      typeof options.auth?.bearer === "string" ? options.auth.bearer : options.auth?.bearer?.name;
+    const decl: AiMcpServerDecl = {
+      kind: "mcp-server",
+      name,
+      ...(hasUrl ? { url: options.url } : {}),
+      ...(hasCommand ? { command: options.command } : {}),
+      ...(options.args !== undefined ? { args: options.args } : {}),
+      ...(authName !== undefined ? { auth: authName } : {}),
+      tools: options.tools,
+      tool(tool: string): AiMcpToolRef {
+        if (!allow.has(tool)) {
+          throw new TypeError(`ai.mcpServer("${name}"): tool "${tool}" is not in the allowlist`);
+        }
+        return { name: mcpToolRef(name, tool) };
+      },
+    };
+    aiMcpServerRegistry.push(decl);
+    return decl;
+  },
 };

package/src/elements/ai/errors.test.ts

@@ -22,7 +22,11 @@ describe("isRetryableAiError", () => {
     expect(isRetryableAiError(new Error("openai-compatible HTTP 401"))).toBe(false);
     const abort = new Error("aborted");
     abort.name = "AbortError";
-    expect(isRetryableAiError(abort)).toBe(true);
+    expect(isRetryableAiError(abort)).toBe(false);
+    const timeout = new Error("deadline");
+    timeout.name = "TimeoutError";
+    expect(isRetryableAiError(timeout)).toBe(true);
+    expect(isRetryableAiError(new Error("request timeout"))).toBe(true);
   });
 });
 

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