okengine 0.13.0 → 0.14.1

package/src/kernel/fx.test.ts

@@ -361,11 +361,17 @@ describe("fx — wholesale swap", () => {
       async emit(signal) {
         calls.push(`emit:${typeof signal === "string" ? signal : signal.name}`);
       },
+      async deadLetters() {
+        return [];
+      },
       async call() {
         return null;
       },
       clock: {
         now: () => 0,
+        ago: () => 0,
+        fromNow: () => 0,
+        duration: () => 0,
         sleep: async () => undefined,
       },
       vault: {
@@ -451,6 +457,9 @@ describe("fx — wholesale swap", () => {
         withQuery(rows) {
           return { [jsonResultBrand]: true, status: 200, value: [...rows], meta: {} };
         },
+        stream(chunks) {
+          return { [jsonResultBrand]: true, kind: "stream" as const, status: 200 as const, chunks };
+        },
       },
       async step(_name, fn) {
         return fn();
@@ -514,6 +523,19 @@ describe("fx.t — catalogs", () => {
   });
 });
 
+describe("fx.clock — relative instants", () => {
+  test("ago / fromNow / duration use the injected now and duration strings", () => {
+    const fx = createFx({ flow: "sessions.sweepExpired", effects: {}, now: () => 1_000_000 });
+    expect(fx.clock.now()).toBe(1_000_000);
+    expect(fx.clock.duration("30d")).toBe(30 * 86_400_000);
+    expect(fx.clock.ago("30d")).toBe(1_000_000 - 30 * 86_400_000);
+    expect(fx.clock.fromNow("14d")).toBe(1_000_000 + 14 * 86_400_000);
+    expect(fx.clock.duration("nope")).toBe(0);
+    expect(fx.clock.ago("nope")).toBe(1_000_000);
+    expect(fx.clock.fromNow("200ms")).toBe(1_000_200);
+  });
+});
+
 describe("fx.json", () => {
   test("with accepts a page or (data, meta)", () => {
     const fx = createFx({ flow: "x", effects: {} });

package/src/kernel/fx.ts

@@ -9,7 +9,8 @@
  * for deterministic tests (§7.6).
  */
 
-import type { Effects, ResourceRef } from "../manifest/types.ts";
+import type { Effects, ResourceRef, SignalResourceRef } from "../manifest/types.ts";
+import { isMcpToolRef } from "../manifest/mcp-ref.ts";
 import type { QueryPageSpec } from "./list-page.ts";
 import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type {
@@ -27,8 +28,8 @@ import type {
   SqlStoreHandle,
 } from "../elements/store.ts";
 import type { SqlRow } from "../drivers/types.ts";
-import type { SignalRuntime } from "../elements/signal.ts";
-import type { SignalEmitOptions } from "../drivers/signal-types.ts";
+import type { SignalDecl, SignalRuntime } from "../elements/signal.ts";
+import type { DeadLetter, SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
@@ -73,6 +74,15 @@ async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
 /** Resource ref Flows declare to read the Runs store via {@link Fx.runs}. */
 export const RUNS_RESOURCE = "runs";
 
+/**
+ * Capability ref for {@link Fx.deadLetters} — `signal:<name>`, never a store facet.
+ *
+ * @param name - Signal name
+ */
+export function signalReadRef(name: string): SignalResourceRef {
+  return `signal:${name}`;
+}
+
 export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 
 /** Named ref: plain string or `{ name }` element handle (optional pin). */
@@ -140,6 +150,27 @@ export interface FxTenant {
 export interface FxClock {
   /** Current epoch-ms (injectable via {@link CreateFxOptions.now}). */
   now(): number;
+  /**
+   * Instant `duration` before {@link FxClock.now} (`"30d"` → now − 30 days).
+   * Uses the same duration strings as {@link FxClock.sleep} / `every()`.
+   *
+   * @param duration - Duration string (e.g. `"30d"`, `"2h"`)
+   */
+  ago(duration: string): number;
+  /**
+   * Instant `duration` after {@link FxClock.now} (`"14d"` → now + 14 days).
+   * Uses the same duration strings as {@link FxClock.sleep} / `every()`.
+   *
+   * @param duration - Duration string (e.g. `"14d"`, `"15m"`)
+   */
+  fromNow(duration: string): number;
+  /**
+   * Span in milliseconds (`"30d"` → `2_592_000_000`). Compose with a stored
+   * instant: `createdAt + fx.clock.duration("7d")`. Unknown strings are `0`.
+   *
+   * @param duration - Duration string (e.g. `"30d"`, `"200ms"`)
+   */
+  duration(duration: string): number;
   /**
    * Durable sleep — when the flow is `durable`, journals the wake time and
    * survives restart / deploy. Without a journal, resolves immediately
@@ -323,12 +354,36 @@ export interface JsonResult<T = unknown> {
   readonly status: number;
   readonly value?: T;
   readonly meta?: Record<string, unknown>;
+  readonly kind?: undefined;
+}
+
+/** SSE carrier from {@link FxJson.stream}. */
+export interface JsonStreamResult {
+  readonly [jsonResultBrand]: true;
+  readonly kind: "stream";
+  readonly status: 200;
+  readonly chunks: AsyncIterable<string>;
+  /** Set by the kernel to commit journal / Runs after the stream settles. */
+  finalize?: () => Promise<void>;
 }
 
-/** True when `value` is an {@link FxJson} carrier. */
+/** True when `value` is an {@link FxJson} JSON-envelope carrier. */
 export function isJsonResult(value: unknown): value is JsonResult {
   return (
-    typeof value === "object" && value !== null && (value as JsonResult)[jsonResultBrand] === true
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind !== "stream"
+  );
+}
+
+/** True when `value` is an SSE stream carrier from {@link FxJson.stream}. */
+export function isJsonStreamResult(value: unknown): value is JsonStreamResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonStreamResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind === "stream"
   );
 }
 
@@ -363,6 +418,11 @@ export interface FxJson {
    * every string field; extra keys auto-eq except `id`.
    */
   withQuery<T>(rows: readonly T[], input: unknown, spec?: QueryPageSpec<T>): JsonResult<T[]>;
+  /**
+   * 200 — `text/event-stream` of JSON `data:` frames, then `data: [DONE]`.
+   * Pass {@link Fx.stream} or any async iterable of token strings.
+   */
+  stream(chunks: AsyncIterable<string>): JsonStreamResult;
 }
 
 /**
@@ -567,6 +627,15 @@ export interface Fx {
    * @param options - Optional emit options (`key` for per-key once ordering)
    */
   emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
+  /**
+   * Query dead-lettered messages for one signal (records `read` on `signal:<name>`).
+   *
+   * Requires a bound signal runtime and `effects.reads` including `signal:<name>`.
+   *
+   * @param signal - Signal name or handle
+   */
+  deadLetters<T>(signal: SignalDecl<T>): Promise<readonly DeadLetter<T>[]>;
+  deadLetters(signal: NamedRef): Promise<readonly DeadLetter[]>;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -651,7 +720,11 @@ export interface Fx {
    */
   stream(
     model: NamedRef,
-    opts?: { readonly prompt?: string; readonly data?: unknown },
+    opts?: {
+      readonly prompt?: string;
+      readonly data?: unknown;
+      readonly via?: readonly NamedRef[];
+    },
   ): AsyncIterable<string>;
   /** Logger. */
   readonly log: FxLog;
@@ -1336,6 +1409,15 @@ export function createFxContext(options: CreateFxOptions): FxContext {
 
   const clock: FxClock = {
     now,
+    ago(duration: string): number {
+      return now() - parseDurationMs(duration);
+    },
+    fromNow(duration: string): number {
+      return now() + parseDurationMs(duration);
+    },
+    duration(duration: string): number {
+      return parseDurationMs(duration);
+    },
     async sleep(label: string, duration: string): Promise<void> {
       if (journal) {
         await journal.sleep(label, duration, parseDurationMs);
@@ -1591,9 +1673,24 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         }
       });
     },
+    deadLetters(signal: NamedRef) {
+      const name = resolveName(signal);
+      return gated("read", signalReadRef(name), async () => {
+        if (!options.signalRuntime) {
+          throw new Error("fx.deadLetters requires a bound signal runtime");
+        }
+        return options.signalRuntime.deadLetters(name);
+      });
+    },
     call(flow, input) {
       const name = resolveName(flow);
       return gated("call", name, async () => {
+        if (isMcpToolRef(name)) {
+          if (!options.aiRuntime) {
+            throw new Error(`fx.call: AI runtime is not configured for MCP tool "${name}"`);
+          }
+          return options.aiRuntime.callMcp(name, input, currentAbortSignal());
+        }
         if (options.callHandler) {
           return options.callHandler(name, input);
         }
@@ -1785,6 +1882,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             prompt: opts?.prompt,
             data: opts?.data,
             signal: local.signal,
+            via: opts?.via?.map(resolveName),
           })) {
             if (local.signal.aborted) break;
             yield text;
@@ -1832,6 +1930,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       },
       with: jsonWith,
       withQuery: jsonWithQuery,
+      stream(chunks) {
+        return {
+          [jsonResultBrand]: true,
+          kind: "stream" as const,
+          status: 200 as const,
+          chunks,
+        };
+      },
     },
     async step<T>(name: string, fn: () => T | Promise<T>, opts?: StepOptions<T>): Promise<T> {
       if (journal) {

package/src/kernel/http-stream.test.ts

@@ -0,0 +1,174 @@
+/**
+ * HTTP SSE via `fx.json.stream` + client-disconnect abort of the provider fetch.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { ai } from "../elements/ai.ts";
+import type { AiDriver } from "../drivers/ai-types.ts";
+import { createRunsRuntime } from "../runs/runtime.ts";
+import { createBunRuntime } from "../runtime/bun.ts";
+import type { ServerHandle } from "../runtime/types.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function tokenDriver(chunks: readonly string[], delayMs = 0): AiDriver {
+  return {
+    id: "mock",
+    async open() {
+      return {
+        driverId: "mock" as const,
+        model: "smart",
+        async complete() {
+          return { text: "", model: "smart", driverId: "mock" as const };
+        },
+        async *stream() {
+          for (const text of chunks) {
+            if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+            yield { text };
+          }
+        },
+      };
+    },
+  };
+}
+
+function hangingDriver(onAbort: () => void): AiDriver {
+  return {
+    id: "mock",
+    async open() {
+      return {
+        driverId: "mock" as const,
+        model: "smart",
+        async complete() {
+          return { text: "", model: "smart", driverId: "mock" as const };
+        },
+        async *stream(opts) {
+          yield { text: "start" };
+          await new Promise<void>((resolve, reject) => {
+            const t = setTimeout(resolve, 8_000);
+            opts.signal?.addEventListener(
+              "abort",
+              () => {
+                onAbort();
+                clearTimeout(t);
+                const err = new Error("aborted");
+                err.name = "AbortError";
+                reject(err);
+              },
+              { once: true },
+            );
+          });
+          yield { text: "never" };
+        },
+      };
+    },
+  };
+}
+
+describe("fx.json.stream HTTP SSE", () => {
+  let handle: ServerHandle | undefined;
+
+  afterEach(() => {
+    handle?.stop(true);
+    handle = undefined;
+  });
+
+  test("encodes token chunks as SSE and leaves JSON flows buffered", async () => {
+    const smart = ai.model("smart");
+    on(
+      http.get("/chat").gate.public,
+      flow("chat.stream", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
+      }),
+    );
+    on(http.get("/ping").gate.public, flow("ping", { do: () => ({ ok: true as const }) }));
+
+    const app = oke({
+      name: "http-stream",
+      ai: { models: [smart], defaultDriver: tokenDriver(["Hel", "lo"]) },
+    });
+
+    const streamed = await app.fetch(new Request("http://localhost/chat"));
+    expect(streamed.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const body = await streamed.text();
+    expect(body).toContain('data: "Hel"');
+    expect(body).toContain('data: "lo"');
+    expect(body).toContain("data: [DONE]");
+
+    const json = await app.fetch(new Request("http://localhost/ping"));
+    expect(json.headers.get("content-type")).toMatch(/application\/json/);
+    expect(await json.json()).toEqual({ data: { ok: true }, error: null });
+  });
+
+  test("client abort mid-stream aborts the upstream provider fetch", async () => {
+    let providerAborted = false;
+    const smart = ai.model("smart");
+    on(
+      http.get("/slow").gate.public,
+      flow("chat.slow", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "long" })),
+      }),
+    );
+
+    const app = oke({
+      name: "http-stream-abort",
+      ai: { models: [smart], defaultDriver: hangingDriver(() => (providerAborted = true)) },
+    });
+
+    handle = createBunRuntime().serve(app, { port: 0, hostname: "127.0.0.1" });
+    const ac = new AbortController();
+    const res = await fetch(`http://127.0.0.1:${handle.port}/slow`, { signal: ac.signal });
+    expect(res.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const reader = res.body!.getReader();
+    const first = await reader.read();
+    expect(first.done).toBe(false);
+    ac.abort();
+    await new Promise((r) => setTimeout(r, 80));
+    expect(providerAborted).toBe(true);
+  });
+
+  test("Traces stay empty until stream close; duration covers the open stream", async () => {
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+    const smart = ai.model("smart");
+    on(
+      http.get("/chat").gate.public,
+      flow("chat.stream", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
+      }),
+    );
+
+    const app = oke({
+      name: "http-stream-traces",
+      ai: { models: [smart], defaultDriver: tokenDriver(["Hel", "lo"], 25) },
+      runs,
+      env: "test",
+    });
+    await app.boot({ env: "test", runs, startScheduler: false });
+
+    const streamed = await app.fetch(new Request("http://localhost/chat"));
+    expect(streamed.headers.get("content-type")).toMatch(/text\/event-stream/);
+    await runs.flush();
+    expect(await runs.all()).toHaveLength(0);
+
+    const body = await streamed.text();
+    expect(body).toContain("data: [DONE]");
+
+    await runs.flush();
+    const events = await runs.all();
+    expect(events).toHaveLength(1);
+    expect(events[0]!.error ?? null).toBeNull();
+    expect(events[0]!.output).toEqual({ streamed: true });
+    expect(events[0]!.durationMs).toBeGreaterThanOrEqual(40);
+
+    await app.stop();
+    await runs.close();
+  });
+});

package/src/kernel/index.ts

@@ -137,6 +137,7 @@ export {
   createFxContext,
   freezePrincipal,
   isJsonResult,
+  isJsonStreamResult,
   jsonResultBrand,
   resolveName,
   resolveStoreRef,
@@ -160,6 +161,7 @@ export {
   type FxThunk,
   type JsonPage,
   type JsonResult,
+  type JsonStreamResult,
   type NamedRef,
   type StepOptions,
 } from "./fx.ts";

package/src/manifest/mcp-ref.ts

@@ -0,0 +1,88 @@
+/**
+ * MCP tool resource refs — `mcp:<server>/<tool>` (capability / Manifest)
+ * and `<server>__<tool>` (provider-safe model tool name).
+ */
+
+/** Capability / Manifest ref for one declared MCP tool. */
+export type McpToolRef = `mcp:${string}/${string}`;
+
+/** Parsed `mcp:<server>/<tool>` ref. */
+export interface ParsedMcpToolRef {
+  readonly server: string;
+  readonly tool: string;
+}
+
+/**
+ * Build a capability ref.
+ *
+ * @param server - Declared MCP server name
+ * @param tool - Allowlisted tool name on that server
+ */
+export function mcpToolRef(server: string, tool: string): McpToolRef {
+  return `mcp:${server}/${tool}`;
+}
+
+/**
+ * Parse `mcp:<server>/<tool>`. Null when the prefix or parts are missing.
+ *
+ * @param ref - Effect / tool resource string
+ */
+export function parseMcpToolRef(ref: string): ParsedMcpToolRef | null {
+  if (!ref.startsWith("mcp:")) return null;
+  const rest = ref.slice(4);
+  const slash = rest.indexOf("/");
+  if (slash <= 0 || slash === rest.length - 1) return null;
+  return { server: rest.slice(0, slash), tool: rest.slice(slash + 1) };
+}
+
+/**
+ * True when `ref` is a well-formed MCP capability ref.
+ *
+ * @param ref - Candidate
+ */
+export function isMcpToolRef(ref: string): boolean {
+  return parseMcpToolRef(ref) !== null;
+}
+
+/**
+ * Graph node id for one MCP server (`mcp:github`).
+ *
+ * @param server - Declared server name
+ */
+export function mcpServerNodeId(server: string): string {
+  return `mcp:${server}`;
+}
+
+/**
+ * Provider-safe function name (`github__create_issue`).
+ *
+ * @param server - Declared server name
+ * @param tool - MCP tool name
+ */
+export function mcpModelToolName(server: string, tool: string): string {
+  return `${server}__${tool}`;
+}
+
+/**
+ * Inverse of {@link mcpModelToolName}.
+ *
+ * @param name - Model-facing tool name
+ */
+export function parseMcpModelToolName(name: string): ParsedMcpToolRef | null {
+  const sep = name.indexOf("__");
+  if (sep <= 0 || sep === name.length - 2) return null;
+  return { server: name.slice(0, sep), tool: name.slice(sep + 2) };
+}
+
+/**
+ * Capability ref from either `mcp:server/tool` or `server__tool`.
+ *
+ * @param name - Model-facing or capability name
+ */
+export function mcpCapabilityRefFromName(name: string): McpToolRef | null {
+  const fromRef = parseMcpToolRef(name);
+  if (fromRef) return mcpToolRef(fromRef.server, fromRef.tool);
+  const fromModel = parseMcpModelToolName(name);
+  if (fromModel) return mcpToolRef(fromModel.server, fromModel.tool);
+  return null;
+}

package/src/manifest/types.ts

@@ -46,6 +46,12 @@ export type ResourceRef = `${StoreFacet}:${string}`;
  */
 export type RunsResourceRef = "runs";
 
+/**
+ * Dead-letter read capability for `fx.deadLetters` — not a store facet.
+ * Declare on `effects.reads` (never `writes`).
+ */
+export type SignalResourceRef = `signal:${string}`;
+
 /** Signal name reference. */
 export type SignalRef = string;
 
@@ -74,8 +80,8 @@ export type JsonSchema = string | Record<string, unknown>;
  * `sends` / `asks` are irreversible (asks also nondeterministic + cost).
  */
 export interface Effects {
-  /** Store reads, plus optional `"runs"` for `fx.runs`. */
-  reads?: Array<ResourceRef | RunsResourceRef>;
+  /** Store reads, plus `"runs"` for `fx.runs` and `signal:name` for `fx.deadLetters`. */
+  reads?: Array<ResourceRef | RunsResourceRef | SignalResourceRef>;
   /** Store writes. */
   writes?: ResourceRef[];
   /** Emitted signals. */
@@ -297,6 +303,8 @@ export interface AiModel {
   provider?: string;
   tier?: string;
   model?: string;
+  /** Protocol driver override for this logical binding. */
+  driverId?: string;
 }
 
 /** Prompt / agent budget. */
@@ -327,11 +335,29 @@ export interface AiAgent {
   budget?: AiBudget;
 }
 
+/**
+ * External MCP server the app consumes — tools join the existing `fx.call`
+ * / `toolLoop` path as `mcp:<server>/<tool>` capability refs.
+ */
+export interface AiMcpServer {
+  /** Streamable HTTP endpoint. */
+  url?: string;
+  /** stdio executable (no shell string). */
+  command?: string;
+  /** Arguments for {@link command}. */
+  args?: string[];
+  /** Bearer secret contract name (never the value). */
+  auth?: SecretRef;
+  /** Required allowlist — never trust whatever `tools/list` exposes. */
+  tools: string[];
+}
+
 /** AI element catalogue. */
 export interface Ai {
   models?: Record<string, AiModel>;
   prompts?: Record<string, AiPrompt>;
   agents?: Record<string, AiAgent>;
+  mcpServers?: Record<string, AiMcpServer>;
 }
 
 /** Per-table metadata on a Manifest {@link Plugin}. */

package/src/manifest/validate.test.ts

@@ -75,6 +75,26 @@ describe("validateManifest", () => {
     expect(result.ok).toBe(false);
   });
 
+  test("accepts signal resource refs on reads only", async () => {
+    const reads = await validateManifest({
+      oke: "1.0",
+      app: "x",
+      flows: {
+        f: { effects: { reads: ["signal:notify"] } },
+      },
+    });
+    expect(reads.ok).toBe(true);
+
+    const writes = await validateManifest({
+      oke: "1.0",
+      app: "x",
+      flows: {
+        f: { effects: { writes: ["signal:notify"] } },
+      },
+    });
+    expect(writes.ok).toBe(false);
+  });
+
   test("parseManifest throws ManifestValidationError on invalid JSON", async () => {
     expect(parseManifest("{")).rejects.toBeInstanceOf(ManifestValidationError);
   });

package/src/mcp/docs-server.ts

@@ -197,7 +197,7 @@ export async function serveDocsMcp(
     hostname: boundHost,
     fetch: mcp.fetch,
     stop(closeActive = false) {
-      server.stop(closeActive);
+      return server.stop(closeActive);
     },
   };
 }

package/src/mcp/server.ts

@@ -268,7 +268,7 @@ export async function serveMcp(options: ServeMcpOptions): Promise<McpServerHandl
     hostname: boundHost,
     fetch: mcp.fetch,
     stop(closeActive = false) {
-      server.stop(closeActive);
+      return server.stop(closeActive);
     },
   };
 }

package/src/plugins/compression.test.ts

@@ -122,4 +122,25 @@ describe("compression plugin", () => {
     );
     expect(nt.headers.get("content-encoding")).toBeNull();
   });
+
+  test("skips text/event-stream even when Accept-Encoding is gzip", async () => {
+    on(
+      http.get("/sse"),
+      flow("sse.get", {
+        do: (_input, fx) =>
+          fx.json.stream(
+            (async function* () {
+              yield "hello";
+            })(),
+          ),
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "zip-sse" }).plug(compression({ minSize: 0 }));
+    const res = await app.fetch(
+      new Request("http://localhost/sse", { headers: { "accept-encoding": "gzip" } }),
+    );
+    expect(res.headers.get("content-type")).toMatch(/text\/event-stream/);
+    expect(res.headers.get("content-encoding")).toBeNull();
+    expect(await res.text()).toContain('data: "hello"');
+  });
 });

package/src/plugins/compression.ts

@@ -73,6 +73,7 @@ export function compression(
     if (cacheControl !== null && /\bno-transform\b/i.test(cacheControl)) return;
 
     const contentType = headers.get("content-type") ?? "";
+    if (/^text\/event-stream\b/i.test(contentType.split(";")[0]?.trim() ?? "")) return;
     if (!match.test(contentType)) return;
 
     const body = await ctx.response.arrayBuffer();