okengine 0.9.1 → 0.10.0

package/src/runs/export-otlp.ts

@@ -0,0 +1,64 @@
+/**
+ * Optional OTLP metrics export shape — additive sink for WideEvents.
+ *
+ * Not a prerequisite for native alerting (Runs + Clock + Channel).
+ * Protocol-named (`otlp`); vendor choice stays in config / images.
+ */
+
+import type { WideEvent } from "./types.ts";
+
+/** One OTLP-shaped metric datapoint derived from a wide event. */
+export interface OtlpRunMetric {
+  readonly name: "oke.runs" | "oke.run.duration_ms";
+  readonly kind: "counter" | "histogram";
+  readonly value: number;
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly timeUnixMs: number;
+}
+
+/**
+ * Map a WideEvent onto OTLP-friendly metric datapoints.
+ *
+ * @param event - Appended run
+ */
+export function wideEventToOtlpMetrics(event: WideEvent): readonly OtlpRunMetric[] {
+  const attributes = {
+    flow: event.flow,
+    trigger: event.trigger,
+    outcome: event.error ? "error" : "ok",
+    ...(event.error ? { error_code: event.error.code } : {}),
+  };
+  return [
+    {
+      name: "oke.runs",
+      kind: "counter",
+      value: 1,
+      attributes,
+      timeUnixMs: event.endedAt,
+    },
+    {
+      name: "oke.run.duration_ms",
+      kind: "histogram",
+      value: event.durationMs,
+      attributes: { flow: event.flow, trigger: event.trigger },
+      timeUnixMs: event.endedAt,
+    },
+  ];
+}
+
+/** Pluggable sink for teams with an existing Grafana / Datadog stack. */
+export type OtlpMetricsSink = (metrics: readonly OtlpRunMetric[]) => void | Promise<void>;
+
+/**
+ * Fan-out helper: call after `runs.record` when an OTLP sink is configured.
+ *
+ * @param event - Just-recorded wide event
+ * @param sink - Optional exporter
+ */
+export async function exportRunMetrics(
+  event: WideEvent,
+  sink: OtlpMetricsSink | undefined,
+): Promise<void> {
+  if (!sink) return;
+  await sink(wideEventToOtlpMetrics(event));
+}

package/src/runs/index.ts

@@ -68,5 +68,21 @@ export {
 
 export { privacyErase, type PrivacyEraseOptions, type PrivacyEraseResult } from "./privacy.ts";
 
+export {
+  evaluateSloBreaches,
+  parseLatencyMs,
+  percentile,
+  windowStatsForFlow,
+  type RunWindowStats,
+  type SloBreach,
+} from "./window.ts";
+
+export {
+  exportRunMetrics,
+  wideEventToOtlpMetrics,
+  type OtlpMetricsSink,
+  type OtlpRunMetric,
+} from "./export-otlp.ts";
+
 export { createRunsPostgresFake } from "./drivers/postgres.ts";
 export { createRunsClickHouseFake } from "./drivers/clickhouse.ts";

package/src/runs/parquet.ts

@@ -42,6 +42,7 @@ export function wideEventToRow(event: WideEvent): ParquetRow {
     build_version: event.buildVersion ?? null,
     error_code: event.error?.code ?? null,
     error_message: event.error?.message ?? null,
+    input: event.input === undefined ? null : JSON.stringify(event.input),
     effects: JSON.stringify(event.effects),
     logs: JSON.stringify(event.logs),
     duration_ms: event.durationMs,
@@ -103,6 +104,14 @@ export function rowToWideEvent(row: Record<string, unknown>): WideEvent {
             ...(row.error_message != null ? { message: String(row.error_message) } : {}),
           }
         : null,
+    ...(row.input != null && row.input !== ""
+      ? {
+          input:
+            typeof row.input === "string"
+              ? (JSON.parse(row.input) as unknown)
+              : (row.input as unknown),
+        }
+      : {}),
     effects: parseJsonArray(row.effects) as WideEvent["effects"],
     logs: parseJsonArray(row.logs) as WideEvent["logs"],
     durationMs: Number(row.duration_ms ?? 0),

package/src/runs/types.ts

@@ -69,6 +69,11 @@ export interface WideEvent {
   readonly buildVersion?: string;
   /** Typed error when the flow failed. */
   readonly error?: RunError | null;
+  /**
+   * Validated flow input snapshot for local replay (`oke replay`).
+   * Declared personal fields may be crypto-shredded into {@link archived}.
+   */
+  readonly input?: unknown;
   /** Effect ledger snapshot. */
   readonly effects: readonly EffectEntry[];
   /**

package/src/runs/window.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import type { WideEvent } from "./types.ts";
+import { evaluateSloBreaches, parseLatencyMs, windowStatsForFlow } from "./window.ts";
+
+function ev(
+  partial: Partial<WideEvent> & Pick<WideEvent, "id" | "durationMs" | "startedAt">,
+): WideEvent {
+  return {
+    flow: "checkout.create",
+    trigger: "http",
+    plane: "user",
+    gates: [],
+    cache: "none",
+    error: null,
+    effects: [],
+    logs: [],
+    endedAt: partial.startedAt + partial.durationMs,
+    dimensions: {},
+    ...partial,
+  };
+}
+
+describe("runs window stats", () => {
+  test("parseLatencyMs", () => {
+    expect(parseLatencyMs("200ms")).toBe(200);
+    expect(parseLatencyMs("1s")).toBe(1000);
+    expect(parseLatencyMs("bad")).toBeNull();
+  });
+
+  test("computes p95 and error rate", () => {
+    const now = 10_000;
+    const events = [
+      ev({ id: "1", durationMs: 10, startedAt: now - 1000 }),
+      ev({ id: "2", durationMs: 20, startedAt: now - 900 }),
+      ev({ id: "3", durationMs: 30, startedAt: now - 800 }),
+      ev({ id: "4", durationMs: 40, startedAt: now - 700 }),
+      ev({
+        id: "5",
+        durationMs: 200,
+        startedAt: now - 600,
+        error: { code: "Timeout" },
+      }),
+    ];
+    const stats = windowStatsForFlow(events, "checkout.create", now, 5 * 60_000);
+    expect(stats.total).toBe(5);
+    expect(stats.errors).toBe(1);
+    expect(stats.errorRate).toBeCloseTo(0.2);
+    expect(stats.p95Ms).toBe(200);
+  });
+
+  test("evaluateSloBreaches flags latency and availability", () => {
+    const stats = windowStatsForFlow(
+      [
+        ev({ id: "1", durationMs: 500, startedAt: 9000, error: { code: "X" } }),
+        ev({ id: "2", durationMs: 500, startedAt: 9100 }),
+      ],
+      "checkout.create",
+      10_000,
+      5_000,
+    );
+    const breaches = evaluateSloBreaches(stats, {
+      availability: "99.9%",
+      latency: { p95: "100ms" },
+    });
+    expect(breaches.some((b) => b.kind === "availability")).toBe(true);
+    expect(breaches.some((b) => b.kind === "latency_p95")).toBe(true);
+  });
+});

package/src/runs/window.ts

@@ -0,0 +1,148 @@
+/**
+ * Rolling window metrics over WideEvents — shared by Console Overview and
+ * Flow-facing `fx.runs` checkers (native alerting without `fx.metric`).
+ */
+
+import type { WideEvent } from "./types.ts";
+
+/** One flow's rolling stats over a time window. */
+export interface RunWindowStats {
+  readonly flow: string;
+  readonly total: number;
+  readonly errors: number;
+  readonly errorRate: number;
+  readonly p50Ms: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly from: number;
+  readonly to: number;
+}
+
+/**
+ * Percentile of a sorted numeric array.
+ *
+ * @param sorted - Ascending durations
+ * @param p - Percentile in (0, 1]
+ */
+export function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0]!;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  return sorted[idx]!;
+}
+
+/**
+ * Parse a Manifest latency string like `200ms` / `1s` into milliseconds.
+ *
+ * @param raw - Latency threshold
+ */
+export function parseLatencyMs(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m)?$/i.exec(raw.trim());
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n < 0) return null;
+  const unit = (match[2] ?? "ms").toLowerCase();
+  if (unit === "s") return Math.round(n * 1000);
+  if (unit === "m") return Math.round(n * 60_000);
+  return Math.round(n);
+}
+
+/**
+ * Compute rolling stats for one flow over `[to - windowMs, to]`.
+ *
+ * @param events - Wide events
+ * @param flow - Flow name filter
+ * @param to - Window end (epoch-ms)
+ * @param windowMs - Window length
+ */
+export function windowStatsForFlow(
+  events: readonly WideEvent[],
+  flow: string,
+  to: number,
+  windowMs: number,
+): RunWindowStats {
+  const from = to - Math.max(0, windowMs);
+  const mine = events.filter((e) => e.flow === flow && e.startedAt >= from && e.startedAt <= to);
+  const durations = mine.map((e) => e.durationMs).sort((a, b) => a - b);
+  const errors = mine.filter((e) => e.error != null).length;
+  const total = mine.length;
+  return {
+    flow,
+    total,
+    errors,
+    errorRate: total === 0 ? 0 : errors / total,
+    p50Ms: percentile(durations, 0.5),
+    p95Ms: percentile(durations, 0.95),
+    p99Ms: percentile(durations, 0.99),
+    from,
+    to,
+  };
+}
+
+/** Breach report for a declared latency / availability SLO. */
+export interface SloBreach {
+  readonly flow: string;
+  readonly kind: "availability" | "latency_p95" | "latency_p99";
+  readonly threshold: number;
+  readonly observed: number;
+  readonly sampleCount: number;
+}
+
+/**
+ * Evaluate Manifest-style SLO thresholds against window stats.
+ *
+ * @param stats - Window stats
+ * @param slo - Declared availability + latency
+ */
+export function evaluateSloBreaches(
+  stats: RunWindowStats,
+  slo: {
+    readonly availability?: string;
+    readonly latency?: { readonly p95?: string; readonly p99?: string };
+  },
+): SloBreach[] {
+  const out: SloBreach[] = [];
+  if (stats.total === 0) return out;
+
+  if (slo.availability) {
+    const match = /^(\d+(?:\.\d+)?)\s*%?$/.exec(slo.availability.trim());
+    if (match) {
+      const pct = Number(match[1]);
+      const tolerable = Math.max(0, 1 - pct / 100);
+      if (stats.errorRate > tolerable) {
+        out.push({
+          flow: stats.flow,
+          kind: "availability",
+          threshold: tolerable,
+          observed: stats.errorRate,
+          sampleCount: stats.total,
+        });
+      }
+    }
+  }
+
+  const p95 = parseLatencyMs(slo.latency?.p95);
+  if (p95 != null && stats.p95Ms > p95) {
+    out.push({
+      flow: stats.flow,
+      kind: "latency_p95",
+      threshold: p95,
+      observed: stats.p95Ms,
+      sampleCount: stats.total,
+    });
+  }
+
+  const p99 = parseLatencyMs(slo.latency?.p99);
+  if (p99 != null && stats.p99Ms > p99) {
+    out.push({
+      flow: stats.flow,
+      kind: "latency_p99",
+      threshold: p99,
+      observed: stats.p99Ms,
+      sampleCount: stats.total,
+    });
+  }
+
+  return out;
+}

package/src/runtime/boot-warn.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Boot honesty suppress flag for the `oke dev` Backend child.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { emitBootWarn } from "./boot-warn.ts";
+
+describe("emitBootWarn", () => {
+  const prev = process.env["OKE_SUPPRESS_BOOT_WARN"];
+
+  afterEach(() => {
+    if (prev === undefined) delete process.env["OKE_SUPPRESS_BOOT_WARN"];
+    else process.env["OKE_SUPPRESS_BOOT_WARN"] = prev;
+  });
+
+  test("forwards to console.warn by default", () => {
+    delete process.env["OKE_SUPPRESS_BOOT_WARN"];
+    const lines: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => {
+      lines.push(args.map(String).join(" "));
+    };
+    try {
+      emitBootWarn("oke boot: test notice");
+      expect(lines).toEqual(["oke boot: test notice"]);
+    } finally {
+      console.warn = original;
+    }
+  });
+
+  test("no-ops when OKE_SUPPRESS_BOOT_WARN=1", () => {
+    process.env["OKE_SUPPRESS_BOOT_WARN"] = "1";
+    const lines: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => {
+      lines.push(args.map(String).join(" "));
+    };
+    try {
+      emitBootWarn("oke boot: hidden");
+      expect(lines).toEqual([]);
+    } finally {
+      console.warn = original;
+    }
+  });
+});

package/src/runtime/boot-warn.ts

@@ -0,0 +1,17 @@
+/**
+ * Boot honesty lines (`oke boot: …`) — once per process, suppressible in
+ * the `oke dev` Backend child so the parent Console owns the notice.
+ */
+
+/**
+ * Emit a boot warning unless suppressed for this process.
+ *
+ * Set `OKE_SUPPRESS_BOOT_WARN=1` on the Backend child during `oke dev` so
+ * Signal / Channel / files process-local notices print once (parent only).
+ *
+ * @param message - Full warning text (usually prefixed `oke boot:`)
+ */
+export function emitBootWarn(message: string): void {
+  if (process.env["OKE_SUPPRESS_BOOT_WARN"] === "1") return;
+  console.warn(message);
+}

package/src/runtime/dev-request-log.ts

@@ -1,5 +1,5 @@
 /**
- * Dev-only request lines for `oke dev` (App / Console / MCP).
+ * Dev-only request lines for `oke dev` (Backend / Console / MCP).
  *
  * Gated by `OKE_DEV_REQUEST_LOG=1`. Surfaces share one TTY; label + color
  * keep streams readable without a multiplexer.
@@ -18,22 +18,22 @@ export function shouldLogDevRequests(): boolean {
 }
 
 /**
- * Active surface for this async context, or `OKE_DEV_SURFACE`, or `App`.
+ * Active surface for this async context, or `OKE_DEV_SURFACE`, or `Backend`.
  */
 export function currentDevSurface(): DevLogSurface {
   const fromAls = surfaceAls.getStore();
   if (fromAls) return fromAls;
   const fromEnv = process.env.OKE_DEV_SURFACE;
-  if (fromEnv === "App" || fromEnv === "Console" || fromEnv === "MCP") {
+  if (fromEnv === "Backend" || fromEnv === "Console" || fromEnv === "MCP") {
     return fromEnv;
   }
-  return "App";
+  return "Backend";
 }
 
 /**
  * Run a handler tagged with a surface (Console wrap around `app.fetch`).
  *
- * @param surface - App · Console · MCP
+ * @param surface - Backend · Console · MCP
  * @param fn - Async work
  */
 export function runWithDevSurface<T>(

package/src/term.test.ts

@@ -5,7 +5,9 @@
 import { describe, expect, test } from "bun:test";
 import {
   formatAppReadyLine,
+  formatBootWarn,
   formatClaimNote,
+  formatCliChrome,
   formatDevBanner,
   formatDevHero,
   formatDevLogSeparator,
@@ -13,6 +15,11 @@ import {
   formatServiceLine,
   formatRequestLine,
   formatStackSummary,
+  countTermLines,
+  createAnchoredBoard,
+  createBootProgress,
+  createRewritableBlock,
+  formatStatusDot,
   formatStatusLine,
   termStyle,
 } from "./term.ts";
@@ -38,9 +45,10 @@ describe("term", () => {
       runtimeEnv: "local",
       system: "darwin 25.4.0 · bun 1.3.14",
       elements: [
-        { element: "flow", detail: "●" },
-        { element: "store", detail: "sql postgres · kv redis" },
-        { element: "signal", detail: "memory" },
+        { element: "flow", detail: "", status: "ready" },
+        { element: "store", detail: "sql postgres · kv redis", status: "ready" },
+        { element: "signal", detail: "memory", status: "ready" },
+        { element: "ai", detail: "openai-compatible · smollm2", status: "pending" },
       ],
     });
     expect(out).toContain("oke dev  v0.2.4");
@@ -53,11 +61,65 @@ describe("term", () => {
     expect(out).toContain("elements");
     expect(out).toContain("store");
     expect(out).toContain("postgres");
+    expect(out).toContain("● flow");
+    expect(out).toContain("● ai");
     expect(out).not.toContain("on(Trigger)");
     expect(out).not.toContain("O·K·E");
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatStatusDot colors by status", () => {
+    const s = termStyle(true);
+    expect(formatStatusDot("ready", true)).toBe(`${s.green}●${s.reset}`);
+    expect(formatStatusDot("pending", true)).toBe(`${s.yellow}●${s.reset}`);
+    expect(formatStatusDot("error", true)).toBe(`${s.red}●${s.reset}`);
+    expect(formatStatusDot("idle", true)).toBe(`${s.dim}●${s.reset}`);
+    expect(formatStatusDot("ready", false)).toBe("●");
+  });
+
+  test("createRewritableBlock appends when disabled", () => {
+    let out = "";
+    const block = createRewritableBlock((t) => {
+      out += t;
+    }, false);
+    block.paint("a\nb\n");
+    block.paint("c\n");
+    expect(out).toBe("a\nb\nc\n");
+    expect(countTermLines("a\nb\n")).toBe(2);
+  });
+
+  test("createBootProgress replaces keyed rows then clears", () => {
+    let out = "";
+    const progress = createBootProgress((t) => {
+      out += t;
+    }, false);
+    progress.set("compose", "compose…\n");
+    progress.set("compose", "compose ok\n");
+    progress.set("vault", "vault ok\n");
+    // Non-TTY appends each set (including replacements).
+    expect(out).toContain("compose ok\n");
+    expect(out).toContain("vault ok\n");
+    progress.clear();
+    // clear is a no-op on the stream when rewrite is disabled
+    expect(out).toContain("vault ok\n");
+  });
+
+  test("createAnchoredBoard wrapWrite tracks below output", () => {
+    let out = "";
+    const board = createAnchoredBoard((t) => {
+      out += t;
+    }, false);
+    board.paint("board\n");
+    const w = board.wrapWrite((t) => {
+      out += t;
+    });
+    w("below\n");
+    board.paint("board2\n"); // non-TTY: no rewrite append
+    expect(out).toContain("board\n");
+    expect(out).toContain("below\n");
+    board.stop();
+  });
+
   test("formatServiceLine / formatAppReadyLine include URL", () => {
     expect(formatServiceLine("Console", "http://127.0.0.1:6533", false)).toContain(
       "http://127.0.0.1:6533",
@@ -65,7 +127,7 @@ describe("term", () => {
     expect(formatAppReadyLine("http://127.0.0.1:6530", false)).toContain("http://127.0.0.1:6530");
   });
 
-  test("formatDevHero keeps App Console MCP URLs", () => {
+  test("formatDevHero keeps Backend Console MCP URLs", () => {
     const out = formatDevHero({
       appUrl: "http://127.0.0.1:6530",
       consoleUrl: "http://127.0.0.1:6533",
@@ -73,12 +135,12 @@ describe("term", () => {
       profile: "local",
       runtimeEnv: "local",
       system: "darwin 25.4.0 · bun 1.3.14",
-      elements: [{ element: "flow", detail: "●" }],
+      elements: [{ element: "flow", detail: "", status: "ready" }],
       color: false,
     });
     expect(out).toContain("oke dev");
     expect(out).toContain("██");
-    expect(out).toContain("App");
+    expect(out).toContain("Backend");
     expect(out).toContain("Console");
     expect(out).toContain("MCP");
     expect(out).toContain("http://127.0.0.1:6530");
@@ -106,10 +168,27 @@ describe("term", () => {
     expect(formatStatusLine("stack up (sql)", false)).toContain("stack up");
   });
 
+  test("formatBootWarn wraps under Notice chrome", () => {
+    const out = formatBootWarn(
+      "oke boot: Channel suppression defaults to process-local memory for multi-instance",
+      false,
+    );
+    expect(out).toContain("Notice");
+    expect(out).toContain("process-local");
+    expect(out).not.toContain("oke boot:");
+  });
+
+  test("formatCliChrome routes boot and status lines", () => {
+    const out = formatCliChrome("oke db seed: ok\noke boot: hello world\n", false);
+    expect(out).toContain("oke db seed: ok");
+    expect(out).toContain("Notice");
+    expect(out).toContain("hello world");
+  });
+
   test("formatRequestLine shows date, time, surface, flow, ms, status", () => {
     const at = new Date(2026, 6, 26, 3, 11, 42);
     const out = formatRequestLine({
-      surface: "App",
+      surface: "Backend",
       method: "GET",
       path: "/health",
       flow: "main.health",
@@ -120,7 +199,7 @@ describe("term", () => {
     });
     expect(out).toContain("2026-07-26");
     expect(out).toContain("03:11:42");
-    expect(out).toContain("App");
+    expect(out).toContain("Backend");
     expect(out).toContain("200");
     expect(out).not.toMatch(/\u001b\[/);
   });
@@ -144,14 +223,20 @@ describe("term", () => {
     const out = formatStackSummary({
       project: "oke-dev-a3f791",
       services: [
-        { label: "postgres", hostPort: 15975 },
-        { label: "redis", hostPort: 16975 },
+        { label: "postgres", hostPort: 15975, status: "ready" },
+        { label: "redis", hostPort: 16975, status: "ready" },
+        { label: "ai", hostPort: 23975, detail: "gemma4:e4b-q4_K_M", status: "pending" },
       ],
       appDrivers: ["postgres", "redis"],
       color: false,
     });
     expect(out).toContain("Docker");
     expect(out).toContain(":15975");
+    expect(out).toContain("gemma4:e4b-q4_K_M");
+    expect(out).toContain("● postgres");
+    expect(out).toContain("● ai");
+    // Blank │ row separates the Docker header from whatever sits above.
+    expect(out).toMatch(/│\n◇ {2}Docker/);
     expect(out).not.toMatch(/\u001b\[/);
   });
 });