okengine 0.22.0 → 0.23.1

package/AGENTS.md

@@ -55,6 +55,13 @@ We build only what genuinely does not exist: the effect system, the Manifest and
 
 A direct `node:` import (or any other side-channel I/O) in element or flow code is a **defect**. `fx` is the single door to the outside world; effects are inferred from what a Flow touches through it. Deterministic tests, least privilege, cache invalidation, live queries, and durability all depend on this invariant.
 
+## AI
+
+- `fx.ask` runs a prompt (repair, budgets). `fx.run` runs an agent (`maxSteps`, `maxCostPerRun`, `stopReason`). `fx.decide` runs a decision.
+- A tool with `approval` requires `durable: true`. Resolve it in the Console or on the approval routes. Do not resolve it from MCP.
+- Stream with `return fx.json.stream(fx.run(agent, input, { stream: true }))`. Follow with `GET /agent/runs/:runId/events` (`Last-Event-ID`). Client: `okengine/client/agent`. React: `useAgentRun`.
+- `fx.decide` takes exactly one of `review` or `onUncertain: "abstain"`. Review only inside a durable non-HTTP Flow (emit to a consumer). Autonomy needs `{ maxError, audit }` and comes only from `oke-decisions.lock.json` (`oke eval --certify` / `oke decide promote`).
+
 ## Ports
 
 | Port     | Surface              |

package/manifest.v1.schema.json

@@ -185,6 +185,11 @@
           "type": "array",
           "items": { "$ref": "#/$defs/FlowRef" },
           "uniqueItems": true
+        },
+        "decides": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
         }
       }
     },
@@ -666,6 +671,7 @@
         "version": { "type": "integer", "minimum": 1 },
         "evals": { "type": "string", "minLength": 1 },
         "budget": { "$ref": "#/$defs/AiPromptBudget" },
+        "repair": { "type": "integer", "enum": [0, 1] },
         "model": { "type": "string", "minLength": 1 },
         "in": { "$ref": "#/$defs/JsonSchema" },
         "out": { "$ref": "#/$defs/JsonSchema" }
@@ -680,11 +686,44 @@
           "items": { "$ref": "#/$defs/FlowRef" },
           "uniqueItems": true
         },
+        "approvals": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "const": true }
+        },
         "maxSteps": { "type": "integer", "minimum": 1 },
+        "maxDepth": { "type": "integer", "minimum": 1 },
         "model": { "type": "string", "minLength": 1 },
         "budget": { "$ref": "#/$defs/AiPromptBudget" }
       }
     },
+    "AiDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "questions"],
+      "properties": {
+        "mode": { "enum": ["review", "abstain"] },
+        "review": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "driverId": { "enum": ["openrouter", "typesafe"] },
+        "questions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "evals": { "type": "string", "minLength": 1 },
+        "autonomy": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["maxError", "audit"],
+          "properties": {
+            "maxError": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+            "audit": { "type": "number", "minimum": 0, "maximum": 1 },
+            "risk": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
+          }
+        }
+      }
+    },
     "Ai": {
       "type": "object",
       "additionalProperties": false,
@@ -703,6 +742,11 @@
           "type": "object",
           "propertyNames": { "type": "string", "minLength": 1 },
           "additionalProperties": { "$ref": "#/$defs/AiAgent" }
+        },
+        "decisions": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "$ref": "#/$defs/AiDecision" }
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "Apache-2.0",
   "repository": {
@@ -73,6 +73,7 @@
     "./client": "./src/client/index.ts",
     "./client/auth": "./src/client/auth.ts",
     "./client/explain": "./src/client/explain.ts",
+    "./client/agent": "./src/client/agent.ts",
     "./client-react": "./src/client-react/index.ts",
     "./test": "./src/test/index.ts",
     "./testing": {
@@ -104,36 +105,46 @@
     }
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/console/tsconfig.ui-next.json && tsc --noEmit -p src/console/ui-next && bun run --cwd packages/create-oke typecheck && bun run --cwd examples/keel typecheck",
-    "lint": "oxlint --quiet",
+    "typecheck": "turbo run typecheck typecheck:framework typecheck:console typecheck:console-tests",
+    "typecheck:framework": "tsc --noEmit",
+    "typecheck:console": "tsc --noEmit -p src/console/ui-next",
+    "typecheck:console-tests": "tsc --noEmit -p tests/console/tsconfig.ui-next.json",
+    "lint": "turbo run lint:repo",
+    "lint:repo": "oxlint --quiet",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",
     "format": "oxfmt",
-    "fmt:check": "oxfmt --check",
-    "test": "bun test --pass-with-no-tests",
+    "fmt:check": "turbo run fmt:check:repo",
+    "fmt:check:repo": "oxfmt --check",
+    "test": "turbo run test:framework",
+    "test:framework": "bun test --pass-with-no-tests",
     "test:coverage": "bun test --coverage --pass-with-no-tests",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
     "test:console:setup": "bunx playwright test --config playwright.ui-next.config.ts",
     "test:console:setup:report": "bunx playwright show-report playwright-report/ui-next",
-    "build": "bunx --bun vite build --config src/console/ui-next/vite.config.ts",
-    "dev:console": "bunx --bun vite --config src/console/ui-next/vite.config.ts",
-    "dev:console:seed": "OKE_CONSOLE_SEEDED=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
-    "dev:console:fresh": "OKE_CONSOLE_FRESH=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
-    "dev:console:fresh:seed": "OKE_CONSOLE_FRESH=1 OKE_CONSOLE_SEEDED=1 bunx --bun vite --config src/console/ui-next/vite.config.ts",
-    "dev:keel": "bun run --cwd examples/keel dev",
-    "dev:keel:seed": "bun run --cwd examples/keel seed",
-    "dev:keel:reset": "bun run --cwd examples/keel reset",
-    "test:keel": "bun run --cwd examples/keel test",
-    "test:keel:docker": "OKE_TEST_DOCKER=1 bun run --cwd examples/keel test",
-    "build:lib": "bun src/release/build-lib.ts",
+    "build": "turbo run build:console",
+    "build:console": "bunx --bun vite build --config src/console/ui-next/vite.config.ts",
+    "dev:console": "turbo run dev:console:repo",
+    "dev:console:repo": "bunx --bun vite --config src/console/ui-next/vite.config.ts",
+    "dev:console:seed": "OKE_CONSOLE_SEEDED=1 turbo run dev:console:repo",
+    "dev:console:fresh": "OKE_CONSOLE_FRESH=1 turbo run dev:console:repo",
+    "dev:console:fresh:seed": "OKE_CONSOLE_FRESH=1 OKE_CONSOLE_SEEDED=1 turbo run dev:console:repo",
+    "dev:keel": "turbo run dev --filter=@oke/example-keel",
+    "dev:keel:seed": "turbo run seed --filter=@oke/example-keel",
+    "dev:keel:reset": "turbo run reset --filter=@oke/example-keel",
+    "test:keel": "turbo run test --filter=@oke/example-keel",
+    "test:keel:docker": "OKE_TEST_DOCKER=1 turbo run test --filter=@oke/example-keel",
+    "build:lib": "turbo run build:lib:repo",
+    "build:lib:repo": "bun src/release/build-lib.ts",
     "prepack": "bun run build && bun run build:lib",
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts src/okid.bench.test.ts",
     "bench:load": "OKE_BENCH=1 bun test ./src/bench/*.bench.ts --timeout 600000 --pass-with-no-tests",
     "budgets": "bun src/release/publish.ts",
     "budgets:core": "bun test src/kernel/budget.test.ts src/client/budget.test.ts",
     "gate": "PUBLISH_GATE=1 bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts",
-    "dev": "bun run --cwd site dev",
-    "site:build": "bun run --cwd site build",
+    "dev": "turbo run dev --filter=site",
+    "site:build": "turbo run build --filter=site",
+    "boundaries": "turbo boundaries",
     "verify": "bun run lint && bun run fmt:check && bun run typecheck && bun run test && bun run gate && bun run site:build",
     "ci": "bun scripts/ci.ts",
     "bump": "bun run scripts/bump-version.ts",
@@ -213,6 +224,7 @@
     "shiki": "^4.4.3",
     "tailwind-merge": "^3.7.0",
     "tailwindcss": "^4.3.3",
+    "turbo": "^2.11.4",
     "tw-animate-css": "^1.4.0",
     "typescript": "^7.0.2",
     "valibot": "^1.5.0",
@@ -285,5 +297,6 @@
   },
   "engines": {
     "bun": ">=1.4.2"
-  }
+  },
+  "packageManager": "bun@1.4.2"
 }

package/site/content/docs/ai/mcp.mdx

@@ -16,7 +16,7 @@ Two genuinely distinct things share the protocol in OKE:
 
 OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes.
 
-The server on **6535** speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
+The server on **6535** speaks JSON-RPC over HTTP. It implements `initialize`, `ping`, `tools/list`, and `tools/call`, and advertises protocol `2024-11-05`. A client that sends another `protocolVersion` is rejected. An omitted version gets `2024-11-05`. It requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead. The outbound client that calls external MCP servers probes `2026-07-28` (`_meta` on each request) and falls back to a `2024-11-05` `initialize`. That probe is not what this server advertises.
 
 <Callout title="The one rule">
   MCP inherits the operator's capability and can never exceed it. Server-level controls alone are
@@ -26,15 +26,19 @@ The server on **6535** speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), re
 
 ## Read tools
 
-Default-safe — they return inert data envelopes, never live handles:
-
-| Tool               | Returns                                        | Scope (any of)                                |
-| ------------------ | ---------------------------------------------- | --------------------------------------------- |
-| `oke.manifest.get` | The current Manifest catalogue                 | `mcp:manifest:read` · `console:manifest:read` |
-| `oke.schema.get`   | In/out/error schemas for one flow (`flowId`)   | `mcp:schema:read` · `console:manifest:read`   |
-| `oke.effects.get`  | Declared effects for one flow (`flowId`)       | `mcp:effects:read` · `console:manifest:read`  |
-| `oke.traces.list`  | Recent runs (`limit` ≤ 200, optional `flowId`) | `mcp:traces:read` · `console:runs:read`       |
-| `oke.traces.get`   | One run/trace record (`runId`)                 | `mcp:traces:read` · `console:runs:read`       |
+Default-safe — they return inert data envelopes, never live handles. Approving a tool, resolving a review, and promoting a decision are not tools. Those stay with a person in the Console or the CLI.
+
+| Tool                    | Returns                                                                                                                                      | Scope (any of)                                |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `oke.manifest.get`      | The current Manifest catalogue                                                                                                               | `mcp:manifest:read` · `console:manifest:read` |
+| `oke.schema.get`        | In/out/error schemas for one flow (`flowId`)                                                                                                 | `mcp:schema:read` · `console:manifest:read`   |
+| `oke.effects.get`       | Declared effects for one flow (`flowId`)                                                                                                     | `mcp:effects:read` · `console:manifest:read`  |
+| `oke.traces.list`       | Recent runs (`limit` ≤ 200, optional `flowId`)                                                                                               | `mcp:traces:read` · `console:runs:read`       |
+| `oke.traces.get`        | One run/trace record (`runId`)                                                                                                               | `mcp:traces:read` · `console:runs:read`       |
+| `oke.ai.runs.list`      | Agent runs for the token's tenant (`limit` ≤ 200). `console:*` or `mcp:*` may omit `tenant` or name another one. PII and secrets are masked. | `mcp:ai:read` · `console:runs:read`           |
+| `oke.ai.runs.get`       | One agent run plus its follow events (`runId`). Same tenant rule. Args, trail, and events are masked.                                        | `mcp:ai:read` · `console:runs:read`           |
+| `oke.ai.approvals.list` | Pending tool approvals for the token's tenant. Same operator rule. Approval args are masked.                                                 | `mcp:ai:read` · `console:runs:read`           |
+| `oke.decisions.list`    | Decision state, pending count, metrics, and drift for the token's tenant. Same operator rule. Inputs are masked.                             | `mcp:decisions:read` · `console:runs:read`    |
 
 ## Write tools — confirmed, every single call
 

package/site/content/docs/ai/skills.mdx

@@ -23,7 +23,7 @@ Contributor-only skills in the same tree (not required for app authors):
 
 ## AGENTS.md — the root contract
 
-Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements bound to one contract, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
+Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements bound to one contract, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. The AI section separates `fx.ask`, `fx.run`, and `fx.decide`: tool approvals need `durable: true` and a human resolve, streams follow `GET /agent/runs/:runId/events`, and autonomy comes only from `oke-decisions.lock.json` (`oke eval --certify` writes the certificate; `oke decide promote` installs it). Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
 
 ## Skills — installable know-how
 

package/site/content/docs/elements/ai/agents.mdx

@@ -77,9 +77,9 @@ when inference does not see `fx.run`.
 <Step>
 ### Bound termination
 
-Default `maxSteps` is **6** when omitted. Hitting the step cap ends the loop; exceeding
-`budget.maxCostPerRun` throws `AiBudgetExceededError`:
-`ai: agent "…" exceeded maxCostPerRun N`.
+Default `maxSteps` is **6**. `stopReason` is `completed`, `max_steps` (`ok: false`),
+`budget` (partial trail, no throw), or `error` (a thrown tool, rethrown). A denial fed
+back to the model stays `completed`.
 
 </Step>
 
@@ -159,23 +159,66 @@ ai.agent("planner", {
 
 ## Options
 
-| Option     | Type                                  | Default     | Meaning                      |
-| ---------- | ------------------------------------- | ----------- | ---------------------------- |
-| `model`    | `AiModelDecl` \| `string`             | first model | Logical binding for the loop |
-| `tools`    | Flow / MCP refs                       | `[]`        | Callable via `fx.call`       |
-| `maxSteps` | `number`                              | `6`         | Hard cap on tool rounds      |
-| `budget`   | `{ maxCostPerCall?, maxCostPerRun? }` | —           | Cost contracts for the run   |
+| Option     | Type                                                         | Default     | Meaning                      |
+| ---------- | ------------------------------------------------------------ | ----------- | ---------------------------- |
+| `model`    | `AiModelDecl` \| `string`                                    | first model | Logical binding for the loop |
+| `tools`    | Flow ref, MCP ref, or `{ name, approval?, gate?, timeout? }` | `[]`        | Callable via `fx.call`       |
+| `maxSteps` | `number`                                                     | `6`         | Hard cap on tool rounds      |
+| `maxDepth` | `number`                                                     | `3`         | Nested agent limit           |
+| `budget`   | `{ maxCostPerCall?, maxCostPerRun? }`                        | —           | Cost contracts for the run   |
 
 ## `fx.run` input
 
-Pass a string or `{ message: string }` (and any extra fields your tools need in context). The
-agent declaration does **not** take Zod `in` / `out` — validate on the surrounding Flow.
+Pass a string, `{ message }`, or `{ messages }` (user, assistant, and tool turns). Passing both
+`message` and `messages` throws. History stays in your Store — `fx.run` does not persist it.
 
 ```typescript
 await fx.run(supportAgent, "Summarize open tickets");
 await fx.run(supportAgent, { message: "Summarize open tickets" });
+await fx.run(supportAgent, {
+  messages: [
+    { role: "user", content: "Summarize open tickets" },
+    { role: "assistant", content: "There are 3." },
+    { role: "user", content: "Open the oldest." },
+  ],
+});
+```
+
+## Agents as tools
+
+Another agent can sit in `tools`. The child uses its own `maxSteps`. Its cost cap is the
+smaller of its budget and what the parent has left. Past `maxDepth` (default 3) the tool
+result is an error and no further child starts.
+
+```typescript
+const lookup = ai.agent("lookup", { tools: ["orders.get"], maxSteps: 3 });
+const support = ai.agent("support", { tools: [lookup, "billing.refund"] });
 ```
 
+## Tool approval
+
+<Callout>
+A tool with `approval` parks the run until someone calls `fx.agent.approve` or `fx.agent.deny`. The calling Flow must set `durable: true`. The wait defaults to `24h`, then the model sees `{ denied: true, reason: "timeout" }`.
+</Callout>
+
+```typescript
+const support = ai.agent("support", {
+  tools: [{ name: "billing.refund", approval: true, gate: ops, timeout: "1h" }],
+});
+
+on(
+  http.post("/assist"),
+  flow("assist", {
+    durable: true,
+    do: async (_input, fx) => fx.run(support, { message: "Refund order 14" }),
+  }),
+);
+```
+
+`gate` is who may resolve. A function for `approval` waits only when it returns true.
+Approve may replace `args`. A second resolution is HTTP 409. Deny is not `stopReason: "denied"` —
+the model continues with `{ denied: true, reason }`.
+
 ## Agents vs ask-with-tools
 
 | Surface                        | When                                         |
@@ -195,8 +238,9 @@ Both default `maxSteps` to `6`. Denied or unknown tools surface as
   `oke()`.
 </Accordion>
 
-<Accordion title='ai: agent "…" exceeded maxCostPerRun'>
-  `AiBudgetExceededError` — raise `budget.maxCostPerRun`, lower `maxSteps`, or shrink tools.
+<Accordion title="The agent stopped before it finished">
+  `fx.run` returns the partial trail when `budget.maxCostPerRun` is spent. It does not throw. Raise
+  the budget, lower `maxSteps`, or shrink the tool bag.
 </Accordion>
 
 <Accordion title='ai: model requested unknown tool "…"'>
@@ -204,6 +248,10 @@ Both default `maxSteps` to `6`. Denied or unknown tools surface as
   or tighten instructions in the user `message`.
 </Accordion>
 
+<Accordion title="must set durable: true">
+  An approval tool cannot wait in memory. Set `durable: true` on the Flow that calls `fx.run`.
+</Accordion>
+
 <Accordion title="OKE1005 on agent runs">
   Runtime gates `fx.run` as an ask of the agent name. List `effects: { asks: ["support.assistant"] }`
   when the compiler does not infer `fx.run`.