okengine 0.22.0 → 0.23.0

package/src/kernel/fx.test.ts

@@ -483,9 +483,7 @@ describe("fx — wholesale swap", () => {
       async deliverOtp(opts) {
         return { ok: true as const, channel: opts.only ?? opts.channels[0] ?? "email" };
       },
-      async ask() {
-        return {};
-      },
+      ask: (async () => ({})) as unknown as Fx["ask"],
       async embed() {
         return [];
       },
@@ -495,9 +493,18 @@ describe("fx — wholesale swap", () => {
       async fetch() {
         return new Response(null, { status: 204 });
       },
-      async run() {
-        return {};
+      async decide<T>(): Promise<T> {
+        return {} as T;
+      },
+      agent: {
+        async approve() {
+          return { ok: true as const };
+        },
+        async deny() {
+          return { ok: true as const };
+        },
       },
+      run: (async () => ({})) as unknown as Fx["run"],
       async *stream() {
         /* empty */
       },

package/src/kernel/fx.ts

@@ -38,7 +38,10 @@ 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 { AgentApprovalResolveResult } from "../elements/ai/approval.ts";
 import type { AiRuntime } from "../elements/ai.ts";
+import type { AgUiEvent } from "../elements/ai/events.ts";
+import type { AiMessage } from "../drivers/ai-types.ts";
 import { parseDurationMs } from "../elements/clock/duration.ts";
 import type { ApiKeyStore } from "../auth/api-keys.ts";
 import type { FxAuthIdentity, FxAuthKeyMethods } from "./fx-auth-keys.ts";
@@ -62,14 +65,14 @@ import {
   touchDryRunStore,
 } from "./dry-run.ts";
 import type { FailFn } from "./errors.ts";
-import { abortError, currentAbortSignal, linkAbort } from "./abort-scope.ts";
+import { abortError, currentAbortSignal, linkAbort, withAbortSignal } from "./abort-scope.ts";
 import type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession, JournalStepOptions } from "./journal.ts";
 
 /** Options for {@link Fx.step} — see {@link JournalStepOptions}. */
 export type StepOptions<T> = JournalStepOptions<T>;
-import type { RunTelemetry } from "./run-telemetry.ts";
+import { type RunTelemetry } from "./run-telemetry.ts";
 import type { RunsRuntime } from "../runs/runtime.ts";
 import type { RunsRow, WideEvent } from "../runs/types.ts";
 import type { RunWindowStats, SloBreach } from "../runs/window.ts";
@@ -114,7 +117,33 @@ function loadFxLiveStream(): typeof import("./fx-live-stream.ts") {
   return lazyRequire(import.meta.dir, ["fx", "live", "stream"].join("-"));
 }
 
+/**
+ * Split `fx.run` input into one message or a history.
+ *
+ * @param input - String, `{ message }`, or `{ messages }`
+ */
+function agentTurn(input: unknown): { message?: string; messages?: readonly AiMessage[] } {
+  if (typeof input === "string") return { message: input };
+  if (input && typeof input === "object") {
+    const record = input as { message?: unknown; messages?: unknown };
+    const hasMessage = "message" in record && record.message !== undefined;
+    const hasMessages = "messages" in record && record.messages !== undefined;
+    if (hasMessage && hasMessages) {
+      throw new TypeError("fx.run: pass message or messages, not both");
+    }
+    if (hasMessages && Array.isArray(record.messages)) {
+      return { messages: record.messages as readonly AiMessage[] };
+    }
+    if (hasMessage) return { message: String(record.message) };
+  }
+  return { message: JSON.stringify(input ?? {}) };
+}
+
 /** `fx.fetch` — keep host parsing + dry-run stub off cold edge / Store-only graphs. */
+function loadFxDecide(): typeof import("./fx-decide.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "decide"].join("-"));
+}
+
 function loadFxFetch(): typeof import("./fx-fetch.ts") {
   return lazyRequire(import.meta.dir, ["fx", "fetch"].join("-"));
 }
@@ -394,6 +423,8 @@ export interface FxAskOptions {
   readonly tools?: readonly NamedRef[];
   /** Bound on tool invocations (default 6). */
   readonly maxSteps?: number;
+  /** Yield AG-UI events instead of resolving to the validated object. */
+  readonly stream?: boolean;
 }
 
 /** Options for {@link Fx.search}. */
@@ -406,11 +437,13 @@ export type { JsonResult, JsonStreamResult };
 
 const sseFrameBrand: unique symbol = Symbol.for("oke.sse.frame");
 
-/** One SSE frame — optional `id:` plus JSON `data:`. */
+/** One SSE frame — optional `id:` plus JSON `data:`, or a comment line. */
 export interface SseFrame {
   readonly [sseFrameBrand]: true;
   readonly data: unknown;
   readonly id?: string;
+  /** Comment body. When set and `data` is undefined, the encoder emits `: comment`. */
+  readonly comment?: string;
 }
 
 /**
@@ -423,6 +456,15 @@ export function sseFrame(data: unknown, id?: string): SseFrame {
   return id !== undefined ? { [sseFrameBrand]: true, data, id } : { [sseFrameBrand]: true, data };
 }
 
+/**
+ * SSE comment (`: keepalive`). Keeps a followed run from being idle-closed.
+ *
+ * @param text - Comment text
+ */
+export function sseComment(text: string): SseFrame {
+  return { [sseFrameBrand]: true, data: undefined, comment: text };
+}
+
 /**
  * True when `value` is a branded SSE frame.
  *
@@ -781,6 +823,11 @@ export interface Fx {
    * @param opts - Model routing opts
    */
   ask(prompt: NamedRef, input?: unknown, opts?: FxAskOptions): Promise<Record<string, unknown>>;
+  ask(
+    prompt: NamedRef,
+    input: unknown,
+    opts: FxAskOptions & { readonly stream: true },
+  ): AsyncIterable<AgUiEvent>;
   /**
    * Embed text via a named model (records `embed` — distinct from `ask`).
    * Returns the vector; does not write an index.
@@ -808,13 +855,40 @@ export interface Fx {
    * @param init - Standard `RequestInit`
    */
   fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+  /**
+   * Run one declared decision. `$` carries `how` and `audited`.
+   * Abstain mode makes each question value `T | null`.
+   */
+  decide<T>(decision: { name: string }, input: unknown): Promise<T>;
+  /**
+   * Resolve a pending agent tool approval (records nothing until the tool runs).
+   *
+   * First resolution wins. A later call returns a conflict failure.
+   */
+  readonly agent: {
+    /**
+     * @param id - Approval id from the interrupt
+     * @param opts - Optional replacement args
+     */
+    approve(id: string, opts?: { readonly args?: unknown }): Promise<AgentApprovalResolveResult>;
+    /**
+     * @param id - Approval id from the interrupt
+     * @param opts - Denial reason fed back to the model
+     */
+    deny(id: string, opts?: { readonly reason?: string }): Promise<AgentApprovalResolveResult>;
+  };
   /**
    * Run a bounded AI agent (records `ask`).
    *
    * @param agent - Agent name or handle
-   * @param input - Agent input (`{ message }` or string)
+   * @param input - Agent input (`{ message }`, `{ messages }`, or string)
    */
   run(agent: NamedRef, input?: unknown): Promise<unknown>;
+  run(
+    agent: NamedRef,
+    input: unknown,
+    opts: { readonly stream: true; readonly threadId?: string },
+  ): AsyncIterable<AgUiEvent>;
   /**
    * Stream model tokens (records `ask`). Returns an async iterable of chunks.
    *
@@ -844,6 +918,8 @@ export interface Fx {
   t(key: AppMessageKey, values?: MessageValues): string;
   /** Active locale for {@link Fx.t} and default channel sends. */
   readonly locale: string;
+  /** HTTP `Last-Event-ID` on this request, when the client sent one. */
+  readonly lastEventId?: string;
   /** Generate a unique id (OKID). */
   id(): string;
   /** User-plane auth principal. */
@@ -1200,11 +1276,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     externalOf?:
       | EffectExternal
       | ((result: T | undefined, error: unknown) => EffectExternal | undefined),
+    stamp?: (result: T | undefined) => { readonly agentRunId?: string } | undefined,
   ): Promise<T> {
     const signal = currentAbortSignal();
     if (signal.aborted) throw abortError(signal.reason);
     capability.assert(kind, resource);
-    const execute = () => recordEffect(ledger, kind, resource, now, body, externalOf);
+    const execute = () => recordEffect(ledger, kind, resource, now, body, externalOf, stamp);
     if (journal) {
       return journal.effect(kind, resource, execute);
     }
@@ -1422,6 +1499,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
 
   const aiDisablesCache = options.aiRuntime?.autoCacheDisabled === true;
   const telemetry = options.runTelemetry;
+  if (telemetry) {
+    lazyRequire<{ bindDecisionLabelTelemetry(telemetry: RunTelemetry): void }>(
+      `${import.meta.dir}/../elements/ai/decisions`,
+      ["lab", "els"].join(""),
+    ).bindDecisionLabelTelemetry(telemetry);
+  }
 
   const cache: FxCache = {
     async get<T = unknown>(key: string): Promise<T | undefined> {
@@ -1663,6 +1746,37 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
   };
 
+  async function resolveAgentDecision(
+    id: string,
+    decision: {
+      readonly decision: "approve" | "deny";
+      readonly args?: unknown;
+      readonly reason?: string;
+    },
+  ): Promise<AgentApprovalResolveResult> {
+    const runtime = options.aiRuntime;
+    if (!runtime?.resolveApproval) return { ok: false, status: 404 };
+    const approver = auth.userId ?? operator.id;
+    return runtime.resolveApproval(
+      id,
+      {
+        decision: decision.decision,
+        tenant: tenant.id,
+        ...(decision.args !== undefined ? { args: decision.args } : {}),
+        ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+        ...(approver ? { approver } : {}),
+      },
+      {
+        auth: {
+          userId: auth.userId,
+          scopes: auth.scopes,
+          verified: auth.verified,
+        },
+        operator: { id: operator.id },
+      },
+    );
+  }
+
   const fx: Fx = {
     store: storeHandle,
     runs: runsSurface,
@@ -1815,8 +1929,37 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return { ok: true as const, channel: result.channel };
       });
     },
-    ask(prompt, input, opts) {
+    ask: function (prompt, input, opts) {
       const name = resolveName(prompt);
+      if (opts?.stream) {
+        return (async function* () {
+          await gated("ask", name, async () => undefined);
+          if (isDryRun()) {
+            recordWouldHaveFired("ask", name);
+            return;
+          }
+          if (!options.aiRuntime) {
+            throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
+          }
+          const local = new AbortController();
+          const unlink = linkAbort(currentAbortSignal(), local);
+          try {
+            const events = await withAbortSignal(local.signal, () =>
+              options.aiRuntime!.streamAsk(name, input, {
+                via: opts.via?.map(resolveName),
+                ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+                tools: opts.tools?.map(resolveName),
+                maxSteps: opts.maxSteps,
+                callTool: (tool, toolInput) => fx.call(tool, toolInput),
+              }),
+            );
+            yield* events;
+          } finally {
+            unlink();
+            if (!local.signal.aborted) local.abort();
+          }
+        })();
+      }
       return gated(
         "ask",
         name,
@@ -1844,7 +1987,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         },
         () => options.aiRuntime?.lastExternal,
       );
-    },
+    } as Fx["ask"],
     embed(model, text) {
       const name = resolveName(model);
       return gated(
@@ -1890,29 +2033,158 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     fetch(url, init) {
       return loadFxFetch().runFxFetch(gated, url, init);
     },
-    run(agent, input) {
+    decide<T>(decision: { name: string }, input: unknown) {
+      return loadFxDecide().runFxDecide({
+        gated,
+        journal: options.journal,
+        signal: currentAbortSignal(),
+        now,
+        runId: options.runId,
+        tenantId: tenant.id,
+        getSecret: async (secretName) => {
+          const value = await gatedSecret(secretName, async () => secrets[secretName]);
+          return typeof value === "string" && value.length > 0 ? value : undefined;
+        },
+        decision,
+        input,
+      }) as Promise<T>;
+    },
+    agent: {
+      approve(id, opts) {
+        return resolveAgentDecision(id, { decision: "approve", args: opts?.args });
+      },
+      deny(id, opts) {
+        return resolveAgentDecision(id, { decision: "deny", reason: opts?.reason });
+      },
+    },
+    run: function (agent, input, opts?: { readonly stream?: boolean; readonly threadId?: string }) {
       const name = resolveName(agent);
-      return gated("ask", name, async () => {
-        if (options.aiRuntime) {
-          const message =
-            typeof input === "string"
-              ? input
-              : input && typeof input === "object" && "message" in input
-                ? String((input as { message: unknown }).message)
-                : JSON.stringify(input ?? {});
-          return options.aiRuntime.runAgent(name, {
-            message,
-            auth: {
+      const turn = agentTurn(input);
+      if (opts?.stream) {
+        let inner: (AsyncIterable<AgUiEvent> & { readonly result?: Promise<unknown> }) | undefined;
+        let heldRunId: string | undefined;
+        let markRun: () => void = () => undefined;
+        const heldReady = new Promise<void>((resolve) => {
+          markRun = resolve;
+        });
+        const gen = (async function* () {
+          if (!options.aiRuntime) {
+            await gated("ask", name, async () => {
+              throw new Error(`fx.run: AI runtime is not configured for agent "${name}"`);
+            });
+            return;
+          }
+          const local = new AbortController();
+          const unlink = linkAbort(currentAbortSignal(), local);
+          try {
+            await withAbortSignal(local.signal, async () => {
+              // The inner tool loop journals each step. Recording the whole
+              // stream as one ask effect would replay the run id and skip
+              // the parked tool.
+              capability.assert("ask", name);
+              const events = await options.aiRuntime!.streamAgent(name, {
+                ...turn,
+                ...(opts.threadId !== undefined ? { threadId: opts.threadId } : {}),
+                gates: (options.rlsGateNames ?? []).filter((gate) => gate !== "public"),
+                userId: auth.userId,
+                operatorId: operator.id,
+                ...(options.journal ? { journal: options.journal } : {}),
+                ...(options.flow !== undefined ? { flow: options.flow } : {}),
+                tenantId: tenant.id,
+                auth: {
+                  userId: auth.userId,
+                  scopes: auth.scopes,
+                  verified: auth.verified,
+                },
+                callTool: (tool, toolInput) => fx.call(tool, toolInput),
+                recordCall: (tool, runId) => {
+                  void gated(
+                    "call",
+                    tool,
+                    async () => runId,
+                    undefined,
+                    (id) =>
+                      typeof id === "string" && id.length > 0 ? { agentRunId: id } : undefined,
+                  );
+                },
+                onRunId(id) {
+                  heldRunId = id;
+                  markRun();
+                },
+              });
+              inner = events as AsyncIterable<AgUiEvent> & {
+                readonly result?: Promise<unknown>;
+              };
+              const settled = inner.result?.then(
+                () => undefined,
+                () => undefined,
+              );
+              await Promise.race([heldReady, settled ?? Promise.resolve()]);
+              await recordEffect(
+                ledger,
+                "ask",
+                name,
+                now,
+                async () => heldRunId,
+                undefined,
+                (id) => (typeof id === "string" && id.length > 0 ? { agentRunId: id } : undefined),
+              );
+            });
+            if (inner) yield* inner;
+          } finally {
+            unlink();
+            if (!local.signal.aborted) local.abort();
+          }
+        })();
+        Object.defineProperty(gen, "result", {
+          enumerable: true,
+          get() {
+            return inner?.result;
+          },
+        });
+        return gen;
+      }
+      return gated(
+        "ask",
+        name,
+        async () => {
+          if (options.aiRuntime) {
+            return options.aiRuntime.runAgent(name, {
+              ...turn,
+              gates: (options.rlsGateNames ?? []).filter((gate) => gate !== "public"),
               userId: auth.userId,
-              scopes: auth.scopes,
-              verified: auth.verified,
-            },
-            callTool: (tool, toolInput) => fx.call(tool, toolInput),
-          });
-        }
-        return { ok: true, steps: 0, denials: [], output: input };
-      });
-    },
+              operatorId: operator.id,
+              ...(options.journal ? { journal: options.journal } : {}),
+              ...(options.flow !== undefined ? { flow: options.flow } : {}),
+              tenantId: tenant.id,
+              auth: {
+                userId: auth.userId,
+                scopes: auth.scopes,
+                verified: auth.verified,
+              },
+              callTool: (tool, toolInput) => fx.call(tool, toolInput),
+              recordCall: (tool, runId) => {
+                void gated(
+                  "call",
+                  tool,
+                  async () => runId,
+                  undefined,
+                  (id) =>
+                    typeof id === "string" && id.length > 0 ? { agentRunId: id } : undefined,
+                );
+              },
+            });
+          }
+          return { ok: true, steps: 0, denials: [], output: input };
+        },
+        undefined,
+        (result) => {
+          if (!result || typeof result !== "object" || !("runId" in result)) return undefined;
+          const id = (result as { runId?: unknown }).runId;
+          return typeof id === "string" && id.length > 0 ? { agentRunId: id } : undefined;
+        },
+      );
+    } as Fx["run"],
     stream(model, opts) {
       const name = resolveName(model);
       const chunks = (async function* () {
@@ -1957,6 +2229,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       });
     },
     locale,
+    lastEventId: options.lastEventId,
     id() {
       return okid();
     },
@@ -1983,12 +2256,22 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       with: jsonWith,
       withQuery: jsonWithQuery,
       stream(chunks) {
-        return {
+        const carrier = {
           [jsonResultBrand]: true,
           kind: "stream" as const,
           status: 200 as const,
           chunks,
         };
+        Object.defineProperty(carrier, "result", {
+          enumerable: true,
+          get() {
+            if (chunks && typeof chunks === "object" && "result" in chunks) {
+              return (chunks as { readonly result?: Promise<unknown> }).result;
+            }
+            return undefined;
+          },
+        });
+        return carrier as JsonStreamResult;
       },
     },
     async step<T>(name: string, fn: () => T | Promise<T>, opts?: StepOptions<T>): Promise<T> {

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

@@ -0,0 +1,94 @@
+/**
+ * HTTP wire-frame capture redacts credentials and keeps the rest.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  HTTP_FRAME_REDACTED,
+  captureHttpFrame,
+  redactHttpFrame,
+  requestForHttpInvoke,
+} from "./http-frame.ts";
+
+describe("requestForHttpInvoke", () => {
+  test("GET puts scalar input on the query string and keeps accept", () => {
+    const request = requestForHttpInvoke(
+      { method: "GET", path: "/tasks/:id" },
+      { pathParams: { id: "tsk_1" }, input: { id: "tsk_1", limit: 20 } },
+    );
+    expect(request.method).toBe("GET");
+    expect(new URL(request.url).pathname).toBe("/tasks/tsk_1");
+    expect(new URL(request.url).searchParams.get("limit")).toBe("20");
+    expect(new URL(request.url).searchParams.has("id")).toBe(false);
+    expect(request.headers.get("accept")).toBe("application/json");
+    expect(request.headers.get("x-oke-client")).toBe("console");
+    expect(request.headers.get("content-type")).toBeNull();
+  });
+});
+
+describe("captureHttpFrame", () => {
+  test("keeps method, path, query, and headers and redacts credentials", () => {
+    const request = new Request("http://localhost/tasks?limit=20&token=sekrit", {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        authorization: "Bearer super-secret",
+        cookie: "oke_session=abc",
+        "x-request-id": "req_1",
+      },
+    });
+    const response = new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "set-cookie": "oke_session=next; HttpOnly",
+      },
+    });
+
+    expect(captureHttpFrame(request, response)).toEqual({
+      request: {
+        method: "GET",
+        path: "/tasks",
+        query: { limit: "20", token: HTTP_FRAME_REDACTED },
+        headers: {
+          accept: "application/json",
+          authorization: HTTP_FRAME_REDACTED,
+          cookie: HTTP_FRAME_REDACTED,
+          "x-request-id": "req_1",
+        },
+      },
+      response: {
+        status: 200,
+        headers: {
+          "content-type": "application/json",
+          "set-cookie": HTTP_FRAME_REDACTED,
+        },
+      },
+    });
+  });
+
+  test("redactHttpFrame masks a frame that skipped capture", () => {
+    expect(
+      redactHttpFrame({
+        request: {
+          method: "POST",
+          path: "/tasks",
+          query: {},
+          headers: { authorization: "Bearer leak", host: "localhost" },
+        },
+        response: { status: 201, headers: { "x-api-key": "leak" } },
+      }),
+    ).toEqual({
+      request: {
+        method: "POST",
+        path: "/tasks",
+        query: {},
+        headers: { authorization: HTTP_FRAME_REDACTED, host: "localhost" },
+      },
+      response: {
+        status: 201,
+        headers: { "x-api-key": HTTP_FRAME_REDACTED },
+      },
+    });
+  });
+});