okengine 0.22.0 → 0.23.0

package/src/kernel/http-frame.ts

@@ -0,0 +1,203 @@
+/**
+ * HTTP wire frame stored on a wide event — query, headers, status.
+ *
+ * Credential headers are replaced before the row is written. The body stays
+ * on `input` / `output`; this frame is the rest of the message.
+ */
+
+import type { RunHttpFrame } from "../runs/types.ts";
+
+/** Replacement for credential header and query values. */
+export const HTTP_FRAME_REDACTED = "[redacted]";
+
+const EXACT_HEADERS = new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "dpop",
+]);
+
+/**
+ * Build the Request a Console invoke would have sent for an HTTP flow.
+ *
+ * Call API runs `execute` directly, so there is no socket request. The frame
+ * still needs a method, path, query, and the headers the invoke actually
+ * uses (`accept`, `x-oke-client: console`, and `content-type` when there is a body).
+ * The operator's browser user-agent is not copied onto the flow.
+ *
+ * @param trigger - HTTP method and path template
+ * @param options - Path params and the assembled flow input
+ */
+export function requestForHttpInvoke(
+  trigger: { readonly method: string; readonly path: string },
+  options: {
+    readonly pathParams?: Readonly<Record<string, string>>;
+    readonly input?: unknown;
+  } = {},
+): Request {
+  let path = trigger.path;
+  const params = options.pathParams ?? {};
+  for (const [key, value] of Object.entries(params)) {
+    path = path.replaceAll(`:${key}`, encodeURIComponent(value));
+  }
+  const url = new URL(path, "http://127.0.0.1");
+  const method = trigger.method.toUpperCase();
+  const headers = new Headers({ accept: "application/json", "x-oke-client": "console" });
+  if (!methodCarriesBody(method)) {
+    appendScalarQuery(url, options.input, new Set(Object.keys(params)));
+    return new Request(url.href, { method, headers });
+  }
+  headers.set("content-type", "application/json");
+  const body = options.input === undefined ? undefined : JSON.stringify(options.input);
+  return new Request(url.href, {
+    method,
+    headers,
+    ...(body !== undefined ? { body } : {}),
+  });
+}
+
+/**
+ * Build the wire frame for an HTTP run.
+ *
+ * Does not read the body. Safe to call after the handler has consumed it,
+ * including streamed responses.
+ *
+ * @param request - Incoming request
+ * @param response - Final response after `onResponse`, when one exists
+ */
+export function captureHttpFrame(request: Request, response: Response | undefined): RunHttpFrame {
+  const url = new URL(request.url);
+  const query: Record<string, string> = {};
+  for (const [key, value] of url.searchParams) {
+    query[key] = sensitiveQuery(key) ? HTTP_FRAME_REDACTED : value;
+  }
+  return redactHttpFrame({
+    request: {
+      method: request.method,
+      path: url.pathname,
+      query,
+      headers: headerMap(request.headers),
+    },
+    ...(response !== undefined
+      ? { response: { status: response.status, headers: headerMap(response.headers) } }
+      : {}),
+  });
+}
+
+/**
+ * Mask credential headers and query values on a stored frame.
+ *
+ * Applied again at Console projection so a row that skipped capture still
+ * does not show secrets.
+ *
+ * @param frame - Stored HTTP frame
+ */
+export function redactHttpFrame(frame: RunHttpFrame): RunHttpFrame {
+  return {
+    request: {
+      method: frame.request.method,
+      path: frame.request.path,
+      query: redactQuery(frame.request.query),
+      headers: redactHeaders(frame.request.headers),
+    },
+    ...(frame.response !== undefined
+      ? {
+          response: {
+            status: frame.response.status,
+            headers: redactHeaders(frame.response.headers),
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * True when a header name carries a credential.
+ *
+ * @param name - Lower-case header name
+ */
+export function sensitiveHeader(name: string): boolean {
+  const key = name.toLowerCase();
+  if (EXACT_HEADERS.has(key)) return true;
+  if (key === "idempotency-key") return false;
+  return (
+    key.includes("token") ||
+    key.includes("secret") ||
+    key.includes("api-key") ||
+    key.endsWith("-key") ||
+    key.endsWith("_key")
+  );
+}
+
+function methodCarriesBody(method: string): boolean {
+  switch (method) {
+    case "GET":
+    case "HEAD":
+    case "DELETE":
+      return false;
+    default:
+      return true;
+  }
+}
+
+function appendScalarQuery(url: URL, input: unknown, skip: ReadonlySet<string>): void {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return;
+  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+    if (skip.has(key)) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      url.searchParams.set(key, String(value));
+    }
+  }
+}
+
+function sensitiveQuery(name: string): boolean {
+  const key = name.toLowerCase();
+  return (
+    key === "token" ||
+    key.endsWith("_token") ||
+    key.endsWith("-token") ||
+    key === "api_key" ||
+    key === "apikey" ||
+    key === "api-key" ||
+    key === "secret" ||
+    key === "password" ||
+    key === "access_token" ||
+    key === "refresh_token"
+  );
+}
+
+function headerMap(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    const name = key.toLowerCase();
+    if (sensitiveHeader(name)) {
+      out[name] = HTTP_FRAME_REDACTED;
+      return;
+    }
+    const prev = out[name];
+    out[name] = prev === undefined ? value : `${prev}, ${value}`;
+  });
+  return sortRecord(out);
+}
+
+function redactHeaders(headers: Readonly<Record<string, string>>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key.toLowerCase()] = sensitiveHeader(key) ? HTTP_FRAME_REDACTED : value;
+  }
+  return sortRecord(out);
+}
+
+function redactQuery(query: Readonly<Record<string, string>>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(query)) {
+    out[key] = sensitiveQuery(key) ? HTTP_FRAME_REDACTED : value;
+  }
+  return sortRecord(out);
+}
+
+function sortRecord(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}

package/src/kernel/journal.ts

@@ -10,6 +10,7 @@
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { okid } from "../okid.ts";
+import type { DecisionLabelStore } from "./decision-label-store.ts";
 import type { IdempotencyStore } from "./idempotency-store.ts";
 import { JournalSuspend } from "./journal-suspend.ts";
 import { lazyRequire } from "./lazy-require.ts";
@@ -128,6 +129,24 @@ export interface JournalLeaseStore {
    * @param leaseMs - Lease duration
    */
   acquireLease(runId: string, instanceId: string, now: number, leaseMs: number): Promise<boolean>;
+  /**
+   * Take the lease and write `update(run)` in that same hold.
+   * `undefined` from `update` keeps the previous entries and still holds the lease.
+   * `"lease"` means another holder won. `"missing"` means no run.
+   *
+   * @param runId - Run id
+   * @param instanceId - Claimant instance
+   * @param now - Epoch-ms
+   * @param leaseMs - Lease duration
+   * @param update - Next snapshot, or undefined to leave entries
+   */
+  cas(
+    runId: string,
+    instanceId: string,
+    now: number,
+    leaseMs: number,
+    update: (run: JournalRun) => JournalRun | undefined,
+  ): Promise<"ok" | "missing" | { readonly lease: true; readonly leaseExpiresAt?: number }>;
   /**
    * Release a lease held by `instanceId` (no-op for other holders).
    *
@@ -161,6 +180,20 @@ function loadIdempotencyStore(): typeof import("./idempotency-store.ts") {
   return lazyRequire(import.meta.dir, ["idempotency", "store"].join("-"));
 }
 
+/**
+ * Load the decision-label table without a static import.
+ */
+function loadDecisionLabelStore(): typeof import("./decision-label-store.ts") {
+  return lazyRequire(import.meta.dir, ["decision", "label", "store"].join("-"));
+}
+
+/**
+ * Load the agent-event table without a static import.
+ */
+function loadAgentEventStore(): typeof import("./agent-event-store.ts") {
+  return lazyRequire(import.meta.dir, ["agent", "event", "store"].join("-"));
+}
+
 /** Persistence backend for journal runs. */
 export interface JournalStore extends Partial<JournalLeaseStore> {
   /**
@@ -168,6 +201,16 @@ export interface JournalStore extends Partial<JournalLeaseStore> {
    * only implements run `get` / `put`.
    */
   readonly idempotency?: IdempotencyStore;
+  /**
+   * Decision labels and the drift flag on this same driver. Opened only when
+   * the app declares decisions.
+   */
+  readonly decisions?: DecisionLabelStore;
+  /**
+   * Agent-run event log on this same driver. Followers resume from these rows
+   * after a restart and from another instance.
+   */
+  readonly agentEvents?: import("./agent-event-store.ts").AgentEventStore;
   /**
    * Load a run by id.
    *
@@ -234,6 +277,7 @@ function leaseMethods(
   load: () => Promise<Map<string, JournalRun>>,
   flush?: (map: Map<string, JournalRun>) => Promise<void>,
 ): JournalLeaseStore {
+  let gate: Promise<void> = Promise.resolve();
   return {
     async acquireLease(runId, instanceId, now, leaseMs) {
       const map = await load();
@@ -244,6 +288,31 @@ function leaseMethods(
       await flush?.(map);
       return true;
     },
+    async cas(runId, instanceId, now, leaseMs, update) {
+      let release!: () => void;
+      const slot = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const prev = gate;
+      gate = slot;
+      await prev;
+      try {
+        const map = await load();
+        const run = map.get(runId);
+        if (!run) return "missing";
+        if (!claimable(run, instanceId, now)) {
+          return { lease: true, leaseExpiresAt: run.leaseExpiresAt };
+        }
+        const next = update(cloneRun(run)) ?? run;
+        next.lockedBy = instanceId;
+        next.leaseExpiresAt = now + leaseMs;
+        map.set(runId, next);
+        await flush?.(map);
+        return "ok";
+      } finally {
+        release();
+      }
+    },
     async releaseLease(runId, instanceId) {
       const map = await load();
       const run = map.get(runId);
@@ -306,6 +375,16 @@ export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalS
       Object.defineProperty(this, "idempotency", { value: created });
       return created;
     },
+    get decisions(): DecisionLabelStore {
+      const created = loadDecisionLabelStore().createMemoryDecisionLabelStore();
+      Object.defineProperty(this, "decisions", { value: created });
+      return created;
+    },
+    get agentEvents(): import("./agent-event-store.ts").AgentEventStore {
+      const created = loadAgentEventStore().createMemoryAgentEventStore();
+      Object.defineProperty(this, "agentEvents", { value: created });
+      return created;
+    },
   };
 }
 
@@ -359,6 +438,20 @@ export function createFileJournalStore(path: string): JournalStore {
       Object.defineProperty(this, "idempotency", { value: created });
       return created;
     },
+    get decisions(): DecisionLabelStore {
+      const created = loadDecisionLabelStore().createFileDecisionLabelStore(
+        `${dirname(path)}/decision-labels.json`,
+      );
+      Object.defineProperty(this, "decisions", { value: created });
+      return created;
+    },
+    get agentEvents(): import("./agent-event-store.ts").AgentEventStore {
+      const created = loadAgentEventStore().createFileAgentEventStore(
+        `${dirname(path)}/agent-events`,
+      );
+      Object.defineProperty(this, "agentEvents", { value: created });
+      return created;
+    },
   };
 }
 
@@ -432,6 +525,11 @@ export interface JournalSession {
    * instead of treating the cursor as past them. Clears the in-memory undo stack
    * so frames re-bind on the next walk.
    */
+  /**
+   * Increments on {@link JournalSession.rewind}. Agent run ids key off this
+   * so `flow.retry` replays the same id.
+   */
+  readonly epoch: number;
   rewind(): void;
   /** Registered per-step undos in persist/replay order (LIFO compensate). */
   undoStack(): readonly JournalUndoFrame[];
@@ -471,6 +569,7 @@ export function createJournalSlot(): {
       const session = slot.session;
       if (!session) {
         if (prop === "runId") return "";
+        if (prop === "epoch") return 0;
         if (prop === "stampTenant") return async () => undefined;
         if (prop === "rewind") return () => undefined;
         return undefined;
@@ -516,6 +615,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
   function openSession(run: JournalRun, leased: boolean): JournalSession {
     /** Next entry index to consume on replay. */
     let cursor = 0;
+    let epoch = 0;
     let leaseHeld = leased;
     let registrationPass = false;
     let undoExecution = false;
@@ -665,9 +765,13 @@ export function createJournal(options: CreateJournalOptions): Journal {
         await persist();
         return value;
       },
+      get epoch() {
+        return epoch;
+      },
       rewind() {
         cursor = 0;
         undos.length = 0;
+        epoch += 1;
       },
       undoStack() {
         return undos;

package/src/kernel/json-result.ts

@@ -28,6 +28,16 @@ export interface JsonStreamResult {
   ready?: () => Promise<void>;
   /** Set by the kernel to commit journal / Runs after the stream settles. */
   finalize?: () => Promise<void>;
+  /**
+   * Agent result once a streamed `fx.run` settles.
+   * Absent for text and live streams.
+   */
+  result?: Promise<unknown>;
+  /**
+   * Set when iteration parked a durable run, after `[DONE]` is queued.
+   * Finalize commits the journal as sleeping from this.
+   */
+  parked?: { wakeAt: number; label: string };
 }
 
 /**

package/src/kernel/pipeline.test.ts

@@ -14,6 +14,7 @@ import { createClockRuntime } from "../elements/clock.ts";
 import { gate } from "../elements/gate.ts";
 import { createRunsRuntime, memoryRunsDriver } from "../runs/index.ts";
 import { oke } from "./app.ts";
+import { HTTP_FRAME_REDACTED } from "./http-frame.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
@@ -196,6 +197,50 @@ describe("pipeline — Unauthorized for anonymous", () => {
   });
 });
 
+describe("pipeline — HTTP wire frame", () => {
+  test("fetch stores query, headers, and status beside the body", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    on(
+      http.get("/tasks", { out: z.object({ ok: z.literal(true) }) }).public(),
+      flow("tasks.list", {
+        do: () => ({ ok: true as const }),
+      }),
+    );
+
+    const runs = createRunsRuntime({ driver: memoryRunsDriver });
+    await runs.open();
+    const app = oke({
+      name: "http-frame",
+      gate: { policies: [gate.public] },
+      runs,
+      env: "test",
+    });
+    await app.boot({ env: "test", gates: [gate.public], runs });
+
+    const res = await app.fetch(
+      new Request("http://localhost/tasks?limit=20", {
+        headers: { accept: "application/json", cookie: "sid=secret" },
+      }),
+    );
+    expect(res.status).toBe(200);
+
+    const event = (await runs.all()).find((row) => row.flow === "tasks.list");
+    expect(event?.input).toBeUndefined();
+    expect(event?.http).toMatchObject({
+      request: {
+        method: "GET",
+        path: "/tasks",
+        query: { limit: "20" },
+        headers: { cookie: HTTP_FRAME_REDACTED, accept: "application/json" },
+      },
+      response: { status: 200 },
+    });
+    await app.bootResult?.close();
+  });
+});
+
 describe("pipeline — evaluated gates on the run", () => {
   test("recorded run contains evaluated chain, not just declared names", async () => {
     resetBindings();

package/src/kernel/sse-id.ts

@@ -0,0 +1,32 @@
+/**
+ * SSE id carried on a live agent event without changing its JSON payload.
+ *
+ * The follow log stores a seq. The live `fx.run` frame for that row uses the
+ * same seq as `id:` so a client can resume with `Last-Event-ID`.
+ */
+
+const sseIdBrand: unique symbol = Symbol.for("oke.sse.id");
+
+/**
+ * Copy `value` and attach an SSE id the encoder writes as `id:`.
+ * The id is not enumerable, so it is not part of the JSON payload.
+ *
+ * @param value - Event object
+ * @param id - SSE id (the stored log seq)
+ */
+export function withSseId<T extends object>(value: T, id: string): T {
+  const copy: T = { ...value };
+  Object.defineProperty(copy, sseIdBrand, { value: id, enumerable: false });
+  return copy;
+}
+
+/**
+ * SSE id attached by {@link withSseId}, if any.
+ *
+ * @param value - Stream chunk
+ */
+export function readSseId(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const id = (value as { readonly [sseIdBrand]?: unknown })[sseIdBrand];
+  return typeof id === "string" ? id : undefined;
+}

package/src/manifest/diff.ts

@@ -52,6 +52,7 @@ const EFFECT_KEYS = [
   "secrets",
   "calls",
   "fetches",
+  "decides",
 ] as const;
 
 /** Isolation strength: higher = stronger tenant separation. */

package/src/manifest/types.ts

@@ -58,6 +58,12 @@ export type AuthApiKeysResourceRef = "auth:api-keys";
  */
 export type AuthTenantsResourceRef = "auth:tenants";
 
+/**
+ * Agent-run journal capability for approval routes.
+ * Not a store facet — the journal driver owns the rows.
+ */
+export type JournalRunsResourceRef = "journal:runs";
+
 /**
  * Dead-letter / live-stream read capability — not a store facet.
  * Declare on `effects.reads` (never `writes`).
@@ -101,8 +107,10 @@ export interface Effects {
     | AuthApiKeysResourceRef
     | AuthTenantsResourceRef
   >;
-  /** Store writes, plus `"auth:api-keys"` / `"auth:tenants"` for `fx.auth` mutations. */
-  writes?: Array<ResourceRef | AuthApiKeysResourceRef | AuthTenantsResourceRef>;
+  /** Store writes, plus `"auth:api-keys"` / `"auth:tenants"` and `"journal:runs"`. */
+  writes?: Array<
+    ResourceRef | AuthApiKeysResourceRef | AuthTenantsResourceRef | JournalRunsResourceRef
+  >;
   /** Emitted signals. */
   emits?: SignalRef[];
   /** Channel template sends (irreversible). */
@@ -123,6 +131,8 @@ export interface Effects {
    * Hostname only (e.g. `"api.stripe.com"`), never a full URL.
    */
   fetches?: FetchHostRef[];
+  /** Decision refs from `fx.decide` (irreversible, nondeterministic). */
+  decides?: string[];
 }
 
 /** Embedding model ref for `effects.embeds` / `fx.embed` (model name). */
@@ -475,6 +485,8 @@ export interface AiPrompt {
   version?: number;
   evals?: string;
   budget?: AiBudget;
+  /** `1` sends one schema-mismatch follow-up. Default `0`. */
+  repair?: 0 | 1;
   /** Ordered recovery chain of logical model names. */
   via?: string[];
   /** Per-command deadline (`"30s"` or milliseconds). */
@@ -487,7 +499,10 @@ export interface AiPrompt {
 /** Bounded agent whose tools are flows. */
 export interface AiAgent {
   tools?: FlowRef[];
+  /** Tools that park for human approval. The predicate stays in author code. */
+  approvals?: Record<string, true>;
   maxSteps?: number;
+  maxDepth?: number;
   model?: string;
   budget?: AiBudget;
 }
@@ -514,9 +529,21 @@ export interface Ai {
   models?: Record<string, AiModel>;
   prompts?: Record<string, AiPrompt>;
   agents?: Record<string, AiAgent>;
+  decisions?: Record<string, AiDecision>;
   mcpServers?: Record<string, AiMcpServer>;
 }
 
+/** A declared decision. The predicate and locale function stay in author code. */
+export interface AiDecision {
+  mode: "review" | "abstain";
+  review?: string;
+  model?: string;
+  driverId?: "openrouter" | "typesafe";
+  questions: string[];
+  evals?: string;
+  autonomy?: { maxError: number; audit: number; risk?: number };
+}
+
 /** Per-table metadata on a Manifest {@link Plugin}. */
 export interface PluginTable {
   plane?: string;