okengine 0.21.1 → 0.23.0

package/site/content/docs/client/calling.mdx

@@ -286,7 +286,7 @@ await api.bookings.get({ id: "bkg_7f3a" }); // GET /bookings/bkg_7f3a
 await api.bookings.manifest({ flightId: "SK481" }); // POST /_oke/bookings/manifest
 ```
 
-Full file-tree rules: [Routing](/docs/elements/flow/routing).
+Full file-tree rules: [Routing](/docs/understand/routing).
 
 ## How input becomes a request
 
@@ -384,23 +384,32 @@ See [Store](/docs/elements/store) for the list query language. Handwritten lists
 
 ## Options
 
-| Option          | Type                                           | Default            | Meaning                                                        |
-| --------------- | ---------------------------------------------- | ------------------ | -------------------------------------------------------------- |
-| `fetch`         | `(input, init?) => Promise<Response>`          | `globalThis.fetch` | Inject a fetch implementation                                  |
-| `headers`       | `Record<string, string>` \| pairs \| `() => …` | —                  | Static headers, or a getter per request                        |
-| `timeout`       | `number` (ms)                                  | —                  | Abort after this many milliseconds                             |
-| `retry.retries` | `number`                                       | `0`                | Extra attempts after the first (network / 5xx)                 |
-| `retry.delay`   | `number` (ms)                                  | `50`               | Initial backoff delay                                          |
-| `retry.backoff` | `number`                                       | `2`                | Multiplier after each retry                                    |
-| `auth.getToken` | `() => string \| null \| …`                    | —                  | Bearer access token (or null) — see [Auth](/docs/client/auth)  |
-| `auth.refresh`  | `() => Promise<string \| null \| …>`           | —                  | Runs once on HTTP 401, then the request retries                |
-| `$routes`       | `ClientRouteMap`                               | —                  | Runtime map from `app.$routes` (REST when method+path present) |
-| `routes`        | `Record<"unit.flow", { method, path }>`        | —                  | Flat REST table; wins over flattening `$routes`                |
+| Option           | Type                                           | Default            | Meaning                                                                                                                 |
+| ---------------- | ---------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `fetch`          | `(input, init?) => Promise<Response>`          | `globalThis.fetch` | Inject a fetch implementation                                                                                           |
+| `headers`        | `Record<string, string>` \| pairs \| `() => …` | —                  | Static headers, or a getter per request                                                                                 |
+| `timeout`        | `number` (ms)                                  | —                  | Abort after this many milliseconds                                                                                      |
+| `retry.retries`  | `number`                                       | `0`                | Extra attempts after the first. With `retry` set, a call retries when it is GET/QUERY or it carries an idempotency key. |
+| `retry.delay`    | `number` (ms)                                  | `50`               | Initial backoff delay                                                                                                   |
+| `retry.backoff`  | `number`                                       | `2`                | Multiplier after each retry                                                                                             |
+| `auth.getToken`  | `() => string \| null \| …`                    | —                  | Bearer access token (or null) — see [Auth](/docs/client/auth)                                                           |
+| `auth.refresh`   | `() => Promise<string \| null \| …>`           | —                  | Runs once on HTTP 401, then the request retries                                                                         |
+| `$routes`        | `ClientRouteMap`                               | —                  | Runtime map from `app.$routes` (REST when method+path present)                                                          |
+| `routes`         | `Record<"unit.flow", { method, path }>`        | —                  | Flat REST table; wins over flattening `$routes`                                                                         |
+| `idempotencyKey` | `string` \| `false`                            | 21-character key   | `Idempotency-Key` on this call. `false` sends no header. Omitted on GET.                                                |
+
+With `retry` configured, a call retries when it is GET/QUERY or it carries an
+idempotency key (automatic on every non-GET call). `idempotencyKey: false` runs
+once unless that call passes `{ retry: true }`.
+
+A `409` whose code is `IdempotencyInProgress` waits for `Retry-After` and retries
+within those attempts. Other error envelopes are returned as-is.
 
 ## Result envelopes
 
 Success may include optional top-level `meta` (for example pagination). Declared flow errors and
 transport failures share the failure arm. Handle them with [`match`](#match--explain).
+A replay sets `meta.idempotentReplayed` when the server sends `Idempotent-Replayed: true`.
 
 ```typescript
 import { isOk, isFail, isTransportError } from "okengine/client";
@@ -473,10 +482,9 @@ Restart `oke dev` after renaming exports.
 </Accordion>
 
 <Accordion title='error.code is "TransportError"'>
-  Network failure, abort (`timeout`), non-JSON body, empty error response, or HTTP status without a
-  `{ data, error }` envelope. Built-in and domain flow codes never use this code.
-  Prefer `error.message` — it always equals `error.data.message`. `explain` maps HTTP 404 transport
-  to kind `missing`.
+  Network failure, abort, non-JSON, or HTTP without a `{ data, error }` envelope. Flow codes never
+  use this code. Prefer `error.message` — it equals `error.data.message`. `explain` maps HTTP 404
+  transport to kind `missing`.
 </Accordion>
 
 <Accordion title="Why import from okengine/client/explain?">
@@ -513,7 +521,7 @@ Restart `oke dev` after renaming exports.
 - [Live](/docs/client/live) — `api.live` and live queries
 - [React](/docs/client/react) — hooks package
 - [Vault · Config](/docs/elements/vault/config) — `PUBLIC_API_URL`, `vault.env`
-- [Routing](/docs/elements/flow/routing) — `$routes` stamps
+- [Routing](/docs/understand/routing) — `$routes` stamps
 - [HTTP](/docs/elements/flow/http) — verbs and envelopes on the server
 - [Errors](/docs/reference/errors) — `fx.fail` helpers, store auto-map, `match` on the client
 - [CLI](/docs/reference/cli) — `oke client add`, `oke dev`
@@ -534,6 +542,6 @@ Restart `oke dev` after renaming exports.
   <Card
     title="Routing"
     description="Folders stamp HTTP paths and client units."
-    href="/docs/elements/flow/routing"
+    href="/docs/understand/routing"
   />
 </Cards>

package/site/content/docs/client/index.mdx

@@ -182,7 +182,7 @@ dev so `createClient("")` stays same-origin behind your proxy.
 
 ## Learn more
 
-- [Routing](/docs/elements/flow/routing) — folders are the URL; `$routes` without `.adopt()`
+- [Routing](/docs/understand/routing) — folders are the URL; `$routes` without `.adopt()`
 - [HTTP](/docs/elements/flow/http) — verbs, `http.resource`, live SSE
 - [The Architecture](/docs/understand/the-architecture) — generated barrel → client → test loop; same contract for Client, Console, MCP
 - [Errors](/docs/reference/errors) — framework codes vs failure values

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`.