okengine 0.23.2 → 0.24.0

package/AGENTS.md

@@ -60,7 +60,7 @@ A direct `node:` import (or any other side-channel I/O) in element or flow code
 - `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`).
+- `fx.decide` names a decider and `otherwise` (a Gate, or `"abstain"`). A Gate parks only inside a durable non-HTTP Flow (emit to a consumer). Autonomy is that decider's certificate in `oke-decisions.lock.json` (`oke decide certify` / `oke decide promote`). Prompt evals stay on `oke eval`.
 
 ## Ports
 
@@ -108,6 +108,10 @@ Engine: Bun `>=1.4.2`.
 
 **If the documentation is silent, stop and ask.**
 
+## GitHub workflow
+
+Branch from `dev` with `type/short-name`. Never commit on `dev` or `main`, and never merge. A pull request closes a leaf issue (Feature, Bug, or Task), not an Epic. The title is `type(scope): summary`, with one `type:` label, at least one `area:` label, a milestone, and `Closes #N` (or `Refs #N`). The loop, Ready, and the board are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## After every implementation
 
 Before claiming work done: run [`.agents/skills/oke-ship`](.agents/skills/oke-ship/SKILL.md) — append notes to `changelog.md` under `## Unreleased` (never under a shipped `## v…` section), and update site docs via [`.agents/skills/oke-docs`](.agents/skills/oke-docs/SKILL.md) for any user-facing surface. Version bump is separate: `bun run bump` promotes Unreleased into the next `## vX.Y.Z`. Before that bump, run [`.agents/skills/oke-perf`](.agents/skills/oke-perf/SKILL.md).

package/manifest.v1.schema.json

@@ -697,20 +697,65 @@
         "budget": { "$ref": "#/$defs/AiPromptBudget" }
       }
     },
+    "AiDeciderCapabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["boolean", "choice", "score", "refusal"],
+      "properties": {
+        "boolean": { "type": "boolean" },
+        "choice": { "type": "boolean" },
+        "score": { "type": "boolean" },
+        "refusal": { "type": "boolean" },
+        "maxChoices": { "type": "integer", "minimum": 1 },
+        "minLevels": { "type": "integer", "minimum": 1 },
+        "maxLevels": { "type": "integer", "minimum": 1 },
+        "maxContext": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "AiDecider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["driverId", "baseUrl", "model", "secret", "pinning", "capabilities"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "driverId": { "enum": ["systemone", "openai-decisions"] },
+        "baseUrl": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "secret": { "type": "string", "minLength": 1 },
+        "pinning": { "enum": ["dated", "alias"] },
+        "capabilities": { "$ref": "#/$defs/AiDeciderCapabilities" },
+        "region": { "type": "string", "minLength": 1 },
+        "regionStatus": { "enum": ["declared", "verified"] },
+        "zdr": { "type": "boolean" },
+        "zdrStatus": { "enum": ["declared", "verified"] },
+        "timeout": { "anyOf": [{ "type": "number" }, { "type": "string", "minLength": 1 }] },
+        "concurrency": { "type": "integer", "minimum": 1 }
+      }
+    },
     "AiDecision": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["mode", "questions"],
+      "required": ["mode", "decider", "otherwise", "questions"],
       "properties": {
         "mode": { "enum": ["review", "abstain"] },
         "review": { "type": "string", "minLength": 1 },
-        "model": { "type": "string", "minLength": 1 },
-        "driverId": { "enum": ["openrouter", "typesafe"] },
+        "decider": { "type": "string", "minLength": 1 },
+        "backup": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "otherwise": { "type": "string", "minLength": 1 },
         "questions": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "uniqueItems": true
         },
+        "secrets": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
         "evals": { "type": "string", "minLength": 1 },
         "autonomy": {
           "type": "object",
@@ -743,6 +788,11 @@
           "propertyNames": { "type": "string", "minLength": 1 },
           "additionalProperties": { "$ref": "#/$defs/AiAgent" }
         },
+        "deciders": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "$ref": "#/$defs/AiDecider" }
+        },
         "decisions": {
           "type": "object",
           "propertyNames": { "type": "string", "minLength": 1 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "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": {
@@ -145,6 +145,7 @@
     "dev": "turbo run dev --filter=site",
     "site:build": "turbo run build --filter=site",
     "boundaries": "turbo boundaries",
+    "check": "bun run verify",
     "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",

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

@@ -38,7 +38,7 @@ Default-safe — they return inert data envelopes, never live handles. Approving
 | `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`    |
+| `oke.decisions.list`    | Decision state, `by`, `why`, per-decider certificates, pending count, and drift. Read-only. Inputs are masked. Resolve stays in the Console. | `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. 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.
+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 is the answering decider's certificate in `oke-decisions.lock.json` (`oke decide certify` writes it; `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