okengine 0.22.0 → 0.23.0

package/src/kernel/app.ts

@@ -6,6 +6,7 @@
  * pipeline, and wires `fx.call` to untriggered (and triggered) flows.
  */
 
+import { bindAgentApprovalFlows } from "../elements/ai/approval-http.ts";
 import { compileRoute } from "../compiler/dynamic.ts";
 import type { CompiledRoute } from "../compiler/aot.ts";
 import { encodeExecuteResult, encodeFailure } from "../compiler/response.ts";
@@ -67,6 +68,7 @@ import {
 import { GATE_PUBLIC_NAME } from "../elements/gate/flatten.ts";
 import type { JsonCodeAuth } from "../runtime/json-code-block.ts";
 import { resolveDurationMs } from "./elapsed.ts";
+import { captureHttpFrame } from "./http-frame.ts";
 import { fail, throwOke, OkeError } from "./errors.ts";
 import { FLOW_NAME_DUPLICATE, FLOW_UNNAMED } from "./errors-flow-name.ts";
 import { ONCE_SIGNAL_MULTI_FLOW } from "./errors-once-signal.ts";
@@ -217,6 +219,39 @@ function loadClientDescriptor(): typeof import("./client-descriptor.ts") {
   return lazyRequire(import.meta.dir, ["client", "descriptor"].join("-"));
 }
 
+/** Decision HTTP flows. A static `import()` still lands on every HTTP bundle. */
+function loadDecisionBind(): typeof import("../elements/ai/decisions/bind.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["bi", "nd"].join(""));
+}
+
+/** Decision lockfile. Loaded only when the manifest declares decisions. */
+function loadDecisionCertificate(): typeof import("../elements/ai/decisions/certificate.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["certificate"].join(""));
+}
+
+/** Decision label opener. Loaded only when the manifest declares decisions. */
+function loadDecisionLabels(): typeof import("../elements/ai/decisions/labels.ts") {
+  return lazyRequire(`${import.meta.dir}/../elements/ai/decisions`, ["lab", "els"].join(""));
+}
+
+/** Drift-flag registration. Loaded only when the manifest declares decisions. */
+function loadDecisionLabelStore(): typeof import("./decision-label-store.ts") {
+  return lazyRequire(import.meta.dir, ["decision", "label", "store"].join("-"));
+}
+
+/** `fx.decide` gate hook. Loaded only when the manifest declares decisions. */
+function loadFxDecideModule(): typeof import("./fx-decide.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "decide"].join("-"));
+}
+
+/**
+ * Full boot graph (drivers, elements). A static `import()` string is still
+ * bundled into every HTTP app; the stem stays computed.
+ */
+function loadBoot(): typeof import("./boot.ts") {
+  return lazyRequire(import.meta.dir, ["bo", "ot"].join(""));
+}
+
 /** Options for {@link oke}. */
 export interface OkeOptions {
   /** Application name (Manifest `app`). */
@@ -1095,6 +1130,8 @@ export function oke(options: OkeOptions): OkeApp {
   // contribute auth-method Bindings before traffic (plan Phase 2).
   const router: Router<Binding> = smart;
 
+  bindAgentApprovalFlows(adoptBinding);
+
   function adoptBinding(b: Binding): void {
     adopted.push(b);
     registerFlow(b.flow);
@@ -1115,6 +1152,24 @@ export function oke(options: OkeOptions): OkeApp {
 
   /** Once-per-app: system `_oke_search_embed_*` CDC bindings from Manifest. */
   let searchEmbedFlowsBound = false;
+  let decisionFlowsBound = false;
+
+  /**
+   * Register the decision aggregate, drift monitor, and candidate route
+   * when any decision declares autonomy.
+   *
+   * @param manifest - Boot manifest
+   */
+  async function ensureDecisionFlows(manifest: BootOptions["manifest"] | undefined): Promise<void> {
+    if (decisionFlowsBound || !manifest) return;
+    const { bindDecisionFlows, manifestHasDecisionAutonomy } = loadDecisionBind();
+    if (!manifestHasDecisionAutonomy(manifest)) {
+      decisionFlowsBound = true;
+      return;
+    }
+    bindDecisionFlows(adoptBinding, manifest);
+    decisionFlowsBound = true;
+  }
   /**
    * Auto-register hybrid-search embed CDC flows when any `.embed()` column
    * exists. Lazy-loads search-bind so edge graphs without search stay lean.
@@ -1339,6 +1394,19 @@ export function oke(options: OkeOptions): OkeApp {
             ...durableResumeFx(),
             ...(gateConfig.auth?.tenant ? (loadAppTenant().w(5, gateConfig.auth) as object) : {}),
             ...(existing?.tenant ? { tenant: { id: existing.tenant } } : {}),
+            callHandler: async (name, callInput) => {
+              const target = flowsByName.get(name);
+              if (!target) return undefined;
+              const inner = await execute(
+                target,
+                callInput,
+                { kind: "internal" } satisfies InternalTrigger,
+                { parentId: runId },
+              );
+              if (inner.failure) return inner.failure;
+              if (inner.ctx.error !== undefined) throw inner.ctx.error;
+              return inner.output;
+            },
           },
         });
       } catch (err) {
@@ -1367,7 +1435,7 @@ export function oke(options: OkeOptions): OkeApp {
   }
 
   async function doBoot(overrides?: Partial<BootOptions>): Promise<BootResult> {
-    const { bootApplication, resolveElementNeeds } = await import("./boot.ts");
+    const { bootApplication, resolveElementNeeds } = loadBoot();
     const { assertHttpGatePosture } = await import("../elements/gate/boot.ts");
     const { assertPluginNeeds, buildAvailableNeedTokens } = await import("./plugin-needs.ts");
     const dockerFlag =
@@ -1388,6 +1456,7 @@ export function oke(options: OkeOptions): OkeApp {
     }
 
     const unguardedHttp = overrides?.unguardedHttp ?? gateConfig.unguardedHttp ?? "deny";
+    await ensureDecisionFlows(overrides?.manifest ?? options.manifest);
     // Auth bindings are in `adopted` — missing posture fails with GateBootError.
     assertHttpGatePosture(adopted, { unguardedHttp, env: bootEnv });
 
@@ -1557,6 +1626,26 @@ export function oke(options: OkeOptions): OkeApp {
     // Built-in hybrid search — auto-register durable embed CDC flows when the
     // Manifest declares any `.embed()` column (writer flows stay embed-free).
     await ensureSearchEmbedFlows(overrides?.manifest ?? options.manifest);
+    const decisionManifest = overrides?.manifest ?? options.manifest;
+    const declaredDecisions = decisionManifest?.ai?.decisions;
+    if (declaredDecisions && Object.keys(declaredDecisions).length > 0) {
+      const { loadDecisionLockfile, setDecisionDrift } = loadDecisionCertificate();
+      const { openDecisionLabelStore } = loadDecisionLabels();
+      const { setDeclaredDriftDecisions } = loadDecisionLabelStore();
+      const { setDecisionGateAllow } = loadFxDecideModule();
+      const root = overrides?.rootDir ?? options.rootDir ?? process.env["OKE_ROOT_DIR"];
+      if (!root) {
+        throw new Error(
+          "oke boot: decisions are declared but rootDir and OKE_ROOT_DIR are unset, so the decision lockfile cannot load.",
+        );
+      }
+      await loadDecisionLockfile(root);
+      setDeclaredDriftDecisions(Object.keys(declaredDecisions));
+      if (result.journal && result.journal.store.decisions) {
+        await openDecisionLabelStore(result.journal.store, setDecisionDrift);
+      }
+      if (result.gate) setDecisionGateAllow((names, ctx) => result.gate!.allow(names, ctx));
+    }
     // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
@@ -2257,6 +2346,14 @@ export function oke(options: OkeOptions): OkeApp {
         : durationMs;
       if (journalSession) {
         inflightRuns.delete(journalSession.runId);
+        const parked = streamOut?.parked;
+        if (parked) {
+          ctx.state.sleeping = {
+            wakeAt: parked.wakeAt,
+            label: parked.label,
+            runId: journalSession.runId,
+          };
+        }
         const sleeping = ctx.state.sleeping as
           | { readonly wakeAt: number; readonly label: string; readonly runId: string }
           | undefined;
@@ -2277,6 +2374,8 @@ export function oke(options: OkeOptions): OkeApp {
             fx,
             error: terminalErr,
           });
+        } else if (parked && sleeping) {
+          await journalSession.commit("sleeping", { wakeAt: sleeping.wakeAt });
         } else if (!sleeping) {
           await journalSession.commit("completed", {
             output: streamOut ? { streamed: true } : result.output,
@@ -2309,6 +2408,9 @@ export function oke(options: OkeOptions): OkeApp {
               ? { output: streamOut ? { streamed: true } : result.output }
               : {}),
             ...(parentId !== undefined ? { parentId } : {}),
+            ...(trigger.kind === "http" && extras?.request
+              ? { http: captureHttpFrame(extras.request, result.response) }
+              : {}),
           },
           archiveCleartext,
         );

package/src/kernel/boot-bind/ai.ts

@@ -14,6 +14,7 @@ import type { AiDriver, AiOpenOptions } from "../../drivers/ai-types.ts";
 import { createAiRuntime, type AiRuntime } from "../../elements/ai.ts";
 import type { GateRuntime } from "../../elements/gate.ts";
 import type { VaultRuntime } from "../../elements/vault.ts";
+import type { JournalStore } from "../journal.ts";
 import type { BootOptions } from "../boot.ts";
 
 /**
@@ -33,6 +34,7 @@ export function bindAi(
   env: ConfigEnv = "test",
   docker = false,
   vault?: VaultRuntime,
+  journalStore?: JournalStore,
 ): AiRuntime {
   const id = resolveAiDriverId(options, env, docker);
   const driver =
@@ -48,6 +50,7 @@ export function bindAi(
     },
     gates: options.ai?.gates ?? gate,
     now,
+    ...(journalStore ? { journalStore } : {}),
   });
 }
 

package/src/kernel/boot-bind/store.test.ts

@@ -13,6 +13,7 @@ import {
   resolveIndexDriverId,
   resolveKvDriverId,
   resolveSqlDriverId,
+  sqlBindingForDecl,
 } from "./store.ts";
 
 describe("bindStore driver resolution", () => {
@@ -99,6 +100,31 @@ describe("bindStore driver resolution", () => {
   });
 });
 
+describe("sqlBindingForDecl", () => {
+  test("pool.max and replica URLs land on the binding; min is ignored", () => {
+    const binding = sqlBindingForDecl("db", "postgres://primary/db", {
+      driver: "postgres",
+      pool: { max: 20, min: 2 },
+      replicas: ["postgres://ro-1/db", "postgres://ro-2/db"],
+    });
+    expect(binding).toEqual({
+      name: "db",
+      primary: { url: "postgres://primary/db", pool: { max: 20 } },
+      replicas: [
+        { url: "postgres://ro-1/db", pool: { max: 20 } },
+        { url: "postgres://ro-2/db", pool: { max: 20 } },
+      ],
+    });
+  });
+
+  test("a string pin keeps the URL and omits pool and replicas", () => {
+    expect(sqlBindingForDecl("db", "memory://", "memory")).toEqual({
+      name: "db",
+      primary: { url: "memory://" },
+    });
+  });
+});
+
 describe("bindStore durable KV routing", () => {
   const prev = {
     redis: process.env.REDIS_URL,

package/src/kernel/boot-bind/store.ts

@@ -2,7 +2,14 @@
  * Lazy store binder — loaded only when Store is declared.
  */
 
-import { resolveDomainDdlMode, resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import {
+  driverRefId,
+  resolveDomainDdlMode,
+  resolveDriverId,
+  resolveDriverRef,
+  type ConfigEnv,
+  type DriverRef,
+} from "../../config/index.ts";
 import {
   STORE_FILES_DEFAULTS,
   STORE_KV_DEFAULTS,
@@ -18,6 +25,7 @@ import { redisDriver } from "../../drivers/redis.ts";
 import { s3Driver } from "../../drivers/s3.ts";
 import type { FilesDriver, IndexDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
+import type { SqlRuntimeBinding } from "../../elements/store/runtime.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
 import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
@@ -129,17 +137,15 @@ export function bindStore(
     warnKvMemoryDurable(durableKvDecls.map((d) => d.name));
   }
 
-  const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
+  const sqlRef = resolveSqlDriverRef(options, env, docker);
+  const sqlBindings: Record<string, SqlRuntimeBinding> = {};
   const kvBindings: Record<string, { url?: string }> = {};
   const filesBindings: Record<string, { root?: string }> = {};
   const indexBindings: Record<string, { url?: string; apiKey?: string }> = {};
 
   for (const decl of options.stores ?? []) {
     if (isSqlDecl(decl)) {
-      sqlBindings[decl.name] = {
-        name: decl.name,
-        primary: { url: sqlUrl },
-      };
+      sqlBindings[decl.name] = sqlBindingForDecl(decl.name, sqlUrl, sqlRef);
     } else if (isKvDecl(decl)) {
       if (decl.durable === true) {
         kvBindings[decl.name] = {};
@@ -210,6 +216,76 @@ export function resolveSqlDriverId(options: BootOptions, env: ConfigEnv, docker:
   return resolveDriverId(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS)!;
 }
 
+/**
+ * Rich SQL driver ref for the active env. A docker `OKE_SQL_DRIVER` override
+ * that changes the protocol drops `pool` / `replicas` — those belong to the
+ * configured driver, not the override.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+function resolveSqlDriverRef(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): DriverRef | undefined {
+  const configured = resolveDriverRef(options.config?.drivers?.store?.sql, env, STORE_SQL_DEFAULTS);
+  const fromEnv = process.env.OKE_SQL_DRIVER?.trim();
+  if (docker && fromEnv && fromEnv !== driverRefId(configured)) return fromEnv;
+  return configured;
+}
+
+/**
+ * Primary URL plus documented `pool.max` and read-replica URLs.
+ *
+ * `pool.min` is ignored — Bun.SQL has no minimum pool size. Unset `max`
+ * leaves pool sizing to the postgres driver default of 8.
+ *
+ * @param name - Store declaration name
+ * @param url - Primary connection URL
+ * @param ref - Active driver pin (string or rich object)
+ */
+export function sqlBindingForDecl(
+  name: string,
+  url: string,
+  ref: DriverRef | undefined,
+): SqlRuntimeBinding {
+  const max = driverPoolMax(ref);
+  const pool = max !== undefined ? { pool: { max } } : {};
+  const replicas = driverReplicaUrls(ref).map((replicaUrl) => ({
+    url: replicaUrl,
+    ...pool,
+  }));
+  return {
+    name,
+    primary: { url, ...pool },
+    ...(replicas.length > 0 ? { replicas } : {}),
+  };
+}
+
+/**
+ * Positive finite `pool.max` from a rich driver ref.
+ *
+ * @param ref - Driver pin
+ */
+function driverPoolMax(ref: DriverRef | undefined): number | undefined {
+  if (ref === undefined || typeof ref === "string") return undefined;
+  const max = ref.pool?.max;
+  if (typeof max !== "number" || !Number.isFinite(max) || max < 1) return undefined;
+  return Math.floor(max);
+}
+
+/**
+ * Replica connection strings from a rich driver ref. Non-strings are dropped.
+ *
+ * @param ref - Driver pin
+ */
+function driverReplicaUrls(ref: DriverRef | undefined): readonly string[] {
+  if (ref === undefined || typeof ref === "string" || ref.replicas === undefined) return [];
+  return ref.replicas.filter((item): item is string => typeof item === "string" && item.length > 0);
+}
+
 /**
  * @param options - Boot options
  * @param env - Active env

package/src/kernel/boot.ts

@@ -282,9 +282,14 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   const considerFlow = (f: AnyFlowDef): void => {
     const e = f.effects;
     if (f.durable === true) journal = true;
-    if ((e?.reads?.length ?? 0) > 0 || (e?.writes?.length ?? 0) > 0) {
-      store = true;
-    }
+    const touchesStore = [...(e?.reads ?? []), ...(e?.writes ?? [])].some(
+      (ref) =>
+        ref.startsWith("sql:") ||
+        ref.startsWith("kv:") ||
+        ref.startsWith("files:") ||
+        ref.startsWith("index:"),
+    );
+    if (touchesStore) store = true;
     if ((e?.emits?.length ?? 0) > 0) signal = true;
     if ((e?.secrets?.length ?? 0) > 0) vault = true;
     if ((e?.sends?.length ?? 0) > 0) channel = true;
@@ -548,6 +553,12 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       if (clockRt) void Promise.resolve(clockRt.tick()).catch(ignoreBenignSql);
       if (journal && durableResume) void Promise.resolve(durableResume()).catch(ignoreBenignSql);
       if (fleet) void fleet.maybeHeartbeat().catch(ignoreBenignSql);
+      const stem = ["run", "events"].join("-");
+      void import(`../elements/ai/${stem}.ts`)
+        .then((mod: typeof import("../elements/ai/run-events.ts")) =>
+          mod.sweepInstalledAgentEvents(),
+        )
+        .catch(ignoreBenignSql);
     }, period);
     schedulerTimer.unref?.();
   }
@@ -567,7 +578,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 6. AI
   let ai = pre.ai;
   if (needs.ai && !ai) {
-    ai = aiBind!.bindAi(options, gate, now, env, docker, vault);
+    ai = aiBind!.bindAi(options, gate, now, env, docker, vault, journal?.store);
   }
 
   // 7. Runs

package/src/kernel/builtin-errors.ts

@@ -25,6 +25,7 @@ export const BUILTIN_ERROR_STATUS = {
   IdempotencyKeyInvalid: 400,
   IdempotencyKeyReused: 422,
   IdempotencyInProgress: 409,
+  JournalLeaseBusy: 409,
 } as const;
 
 /** Built-in error code (including `DatabaseError`). */
@@ -94,6 +95,7 @@ export type BuiltinErrorMap = {
   readonly IdempotencyKeyInvalid: Record<string, never>;
   readonly IdempotencyKeyReused: Record<string, never>;
   readonly IdempotencyInProgress: { readonly retryAfter?: number };
+  readonly JournalLeaseBusy: { readonly retryAfter?: number };
 };
 
 /**

package/src/kernel/capability.ts

@@ -21,6 +21,7 @@ const UNDECLARED_KEY: Readonly<Record<EffectKind, keyof typeof OKE_ERRORS>> = {
   secret: "UNDECLARED_SECRET",
   call: "UNDECLARED_CALL",
   fetch: "UNDECLARED_FETCH",
+  decide: "UNDECLARED_DECIDE",
 };
 
 /** Maps effect kind → the corresponding `Effects` field. */
@@ -34,6 +35,7 @@ const EFFECTS_FIELD: Readonly<Record<EffectKind, keyof Effects>> = {
   secret: "secrets",
   call: "calls",
   fetch: "fetches",
+  decide: "decides",
 };
 
 /**
@@ -91,6 +93,7 @@ export function createCapabilityToken(flow: string, declared?: Effects): Capabil
     secret: new Set(effects.secrets ?? []),
     call: new Set(effects.calls ?? []),
     fetch: new Set(effects.fetches ?? []),
+    decide: new Set(effects.decides ?? []),
   };
 
   return {