@demlik/tea 0.14.0 → 0.16.0

package/dist/{machine-CdIcN2Xm.d.ts → machine-BQzTV8On.d.ts}

@@ -1,133 +1,101 @@
-import { C as Cmd, j as Tagged, I as Interpret, A as AnyCmdDef, a as CmdOf, b as CmdDef, e as Settled, k as NoCtx, O as OkOf, E as ErrOf, l as MalformedResult, i as CmdValue, g as PortEmitter, m as Requirements, n as TaggedError, M as Machine } from './core-CTzMJ82M.js';
-import { a as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-NjrT3fL2.js';
-import { R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientState, M as MsgType, b as MsgTypeValue } from './index-B5BZ-_cT.js';
-import { D as DeadlineExceeded, a as DeadlineSub } from './index-q0hXFeZ0.js';
-import { F as FanOutState } from './index-6A7dB8f6.js';
+import { C as Cmd, s as Tagged, p as Interpret, A as AnyCmdDef, c as CmdOf, b as CmdDef, j as Settled, t as OkOf, u as ErrOf, r as MalformedResult, l as Outcome, v as CmdValue, m as PortEmitter, g as TaggedError, M as Machine, d as Subscribe } from './core-BbgtiXdg.js';
+import { a as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-Bz5Rh9Ga.js';
+import { R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientState, r as RunCmdDef } from './index-Cou86-GX.js';
+import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-Xufl55W8.js';
+import { M as MsgType, a as MsgTypeValue } from './protocol-ClRZBhHQ.js';
+import { F as FanOutState } from './index-CkFYA9Y6.js';
 import { RetryPolicy, AnyRetryPolicy } from './retry-backoff/index.js';
-import { Result } from 'better-result';
-import { z } from 'zod';
-
-/**
- * @packageDocumentation
- * internal/llm-call — `resilient-call` + structured-output parse + a typed
- * failure variant, around a purpose-discriminated LLM invocation. Internal
- * since #49 — not published on any subpath; `@demlik/tea/agent` re-exports
- * the types a consumer meets.
- *
- * This is the ~60-line `call_llm` handler from the audit-agent seed
- * (`interpret.ts` / `effects.ts`) collapsed into the uniform L2 knob: a config
- * object, the resilient-call slice it inherits, and one interpret handler that
- * assembles messages, binds the structured-output schema for the call's
- * `purpose`, invokes the model (retry composed from `../resilient-call`, NOT
- * reinvented), parses the output, and RETURNS the enriched resilient settle Msg
- * (`resilient_ok` / `resilient_err`) so it re-enters the host reducer and drives
- * the inherited succeed/fail → backoff → onTimer loop.
- *
- * ## What it adds over `../resilient-call`
- *
- *   - **Two DI ports** (the seed's two seams):
- *       1. `model` — either `async (messages) => answer`, the plain-function
- *          port (#58), or `(modelId) => LLM`, the model factory that binds the
- *          structured-output schema itself. Tests pass a fake so the handler
- *          runs end-to-end without touching a real provider; the production
- *          worker wires `createChatModel(env, …)`.
- *       2. `loadMessages: Loader` — the SDK / message loader. The seed lazy-
- *          imports `@langchain/core/messages` (a top-level `import type` blows
- *          up the workers test runner); the loader keeps that import lazy and
- *          stubbable. It produces the `BaseMessage[]` for a given call.
- *   - **Structured-output parse** — each `purpose` maps to a `Schema` in
- *     `config.schemas`. The handler binds `model.withStructuredOutput(schema)`
- *     so the invoke resolves to a typed object; a `Schema.parse` that throws
- *     becomes a `resilient_err` carrying an `LlmErr` (a parse failure is a
- *     failure, not a stall — "errors are data"). `withStructuredOutput` is the
- *     seed's brain-only path; the fake model in tests returns the typed object
- *     directly.
- *   - **A typed failure variant** — every failure (model throw, timeout-via-
- *     retry-exhaustion, schema parse) is surfaced as the `LlmErr` carried on the
- *     enriched `resilient_err` settle Msg, tagged with the `purpose` so the
- *     consumer's reducer routes per-stage. The seed dispatched
- *     `llm_failed{purpose}`; the consumer rebuilds that shape in its reducer arm
- *     from `m.error: LlmErr`.
- *
- * ## Inheriting resilient-call by composition (not reinvention)
- *
- * The retry / backoff lives in `../resilient-call`: `createLlmCall` builds a
- * `createResilientCall` knob over the model-invoke port and DELEGATES `init`,
- * `attempt`, `succeed`, `fail`, `onTimer`, `subs` to it verbatim — the slice is
- * literally resilient-call's slice (the spec's "retry lives here"). There is no
- * second backoff implementation here. The handler runs the invoke through the
- * resilient-call handler so a transient model failure backs off exactly as a
- * resilient HTTP call would; the `purpose`-branch + structured parse wrap the
- * port the resilient handler drives.
- *
- * ## The two non-negotiables (canon, inherited)
- *
- *   - **Durable** — the slice is resilient-call's plain-data slice (a Model
- *     field). Input carried on the `resilient_run` Cmd is the plain
- *     `LlmCall` request (purpose + modelId + payload) — no closures.
- *   - **Replayable** — every transition is a resilient-call verb; the handler
- *     is the only impurity, and the one clock read is `Date.now()` at the
- *     effect boundary (inside the handler), exactly as the seed stamped its
- *     `llm_responded` / `llm_failed` Msgs.
- *
- * ## Typical wiring
- *
- *   const llm = createLlmCall<MyPurpose, MyOutputs>({
- *     model: (id) => createChatModel(env, id),
- *     schemas: { plan: planSchema, report: reportSchema },
- *     retry: defaultRetryPolicy,
- *     loadMessages: defaultMessagesLoader,
- *   });
- *
- *   // in the machine:
- *   init: () => [{ resilience: llm.init() }, []],
- *   update: {
- *     call_llm:  (s, m) => lift(s, llm.attempt(s.resilience, m.input, m.at)),
- *     // `resilient_ok` / `resilient_err` RE-ENTER from `handlers` (the settle
- *     // Msg the interpret handler returns). Run the inherited verb FIRST so the
- *     // succeed/fail → backoff → onTimer loop advances, THEN fold the enriched
- *     // payload (`m.result: LlmOk` / `m.error: LlmErr`) into the host's own
- *     // state — the enrichment lives in the reducer arm, not the handler.
- *     resilient_ok:  (s, m) => {
- *       const [slice, cmds] = llm.succeed(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, output: m.result.output }, cmds];
- *     },
- *     resilient_err: (s, m) => {
- *       const [slice, cmds] = llm.fail(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, failure: m.error }, cmds];
- *     },
- *     deadline_exceeded: (s, m) => lift(s, llm.onTimer(s.resilience, m)),
- *   },
- *   subscriptions: (s) => llm.subs(s.resilience),
- *   subscribe: { deadline: subscribeDeadline },
- *   interpret: llm.handlers(),
- */
+import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
  * The minimal structured-output schema contract: `parse(unknown) => T`, the
- * zod-style call the handler uses to validate the model's output before it
- * settles `resilient_ok`. A throwing `parse` (the zod contract on invalid
- * input) propagates out of `invokeOne` and is caught by the resilient handler,
- * which settles `resilient_err` (enriched to `LlmErr`) — a parse failure is a
- * failure, never a silent pass. Structural so a real `z.ZodType<T>` satisfies
- * it without an import.
+ * zod-style call `decode` uses to validate the model's output before it
+ * settles `resilient_run_ok`. A throwing `parse` (the zod contract on invalid
+ * input) becomes a `port_rejected` outcome — a parse failure is a failure,
+ * never a silent pass. Structural so a real `z.ZodType<T>` satisfies it
+ * without an import.
  */
 interface Schema<T> {
     /** Validate + narrow `value` to `T`, or throw on mismatch (the zod contract). */
     parse(value: unknown): T;
 }
+/**
+ * One LLM call request — the resilient-call `input` for this module, carried on
+ * the `resilient_run` Cmd as plain data — no closures, so it survives
+ * persistence and replay. Purpose-discriminated: a `purpose` selecting the
+ * schema + prompt assembly, the `model` id, and the opaque per-purpose
+ * `payload` the handler's message loader consumes.
+ *
+ * `key` defaults to `purpose` when the consumer calls `attempt(s, input, at)`,
+ * so one in-flight call per purpose is tracked under the resilient-call slice —
+ * the common single-call-per-stage shape. A consumer that fans out many calls
+ * of one purpose passes a distinct `key`.
+ */
+interface LlmCall<P extends string> {
+    /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */
+    readonly purpose: P;
+    /** The model id to invoke; `null` = the host's default model. */
+    readonly model: string | null;
+    /** The per-purpose prompt payload the message loader consumes. Opaque to the knob. */
+    readonly payload: unknown;
+}
+/** The parsed, typed success carried on `resilient_run_ok`, tagged with its purpose. */
+interface LlmOk<P extends string, O extends Record<P, unknown>> {
+    readonly key: string;
+    readonly purpose: P;
+    readonly output: O[P];
+}
+/** The typed failure variant — every failure path surfaces this, tagged by purpose. */
+interface LlmErr<P extends string> {
+    readonly key: string;
+    readonly purpose: P;
+    /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */
+    readonly reason: string;
+    /** The original error, carried untouched for the consumer to inspect. */
+    readonly error: unknown;
+}
+/**
+ * The effect Cmd this module emits: run the LLM call for `key` with `input`. It
+ * is `../resilient-call`'s `Cmd.define`d `RunCmd` specialized to the `LlmCall`
+ * input — NOT a re-declared shape — so the resilient verbs' return tuples
+ * thread through `attempt` / `succeed` / `fail` / `onTimer` with no cast.
+ */
+type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;
+/** The success Msg the engine mints — resilient-call's, with the parsed `LlmOk`. */
+type LlmSucceedMsg<P extends string, O extends Record<P, unknown>> = SucceedMsg<LlmOk<P, O>, "resilient", LlmCall<P>>;
+/**
+ * The failure Msg the engine mints — resilient-call's. Its `error` is the
+ * handler's `port_rejected` (an {@link LlmRejected} when the handler used
+ * `decode` / `rejected`); read it as the typed {@link LlmErr} with `errOf`.
+ */
+type LlmFailMsg<P extends string> = FailMsg<"resilient", LlmCall<P>>;
+/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */
+type LlmTimerMsg = DeadlineExceeded;
+
+/**
+ * @demlik/tea/agent — the model ports and the brain call's Promise handler.
+ *
+ * `../internal/llm-call` is pure: it owns the brain call's slice, its
+ * `Cmd.define`d run Cmd and the parse that turns a model's answer into that
+ * Cmd's outcome, and it ships no engine code (ADR 0021). The agent is a Promise
+ * host — `toMachine` hands its caller an `interpret` table and `defineAgent`
+ * runs itself — so the one handler that actually invokes the model lives here:
+ * the two DI ports (`model`, `loadMessages`) and {@link brainHandler}, which
+ * calls them and returns the outcome `llm.decode` builds.
+ */
+
 /**
  * The minimal chat-model contract every model the handler talks to must
  * satisfy — the seed's `InjectableChatModel`, trimmed to the one operation
- * llm-call drives for brain-only stages:
+ * the brain call drives for brain-only stages:
  *
  *   `withStructuredOutput(schema)` → a runnable whose `invoke(messages)`
  *   resolves to a typed object matching `schema`.
  *
  * `BaseChatModel` from `@langchain/core` is the runtime type; this surface
- * names only what llm-call calls so a test fake can ignore the rest. Generic
+ * names only what the handler calls so a test fake can ignore the rest. Generic
  * over the message shape `Msg` so a consumer's loader and model agree on it
- * without llm-call inspecting messages.
+ * without the agent inspecting messages.
  */
 interface Llm<Msg> {
     withStructuredOutput<T>(schema: Schema<T>): {
@@ -153,8 +121,8 @@ type ModelFactory<Msg> = (modelId: string | null) => Llm<Msg>;
  * The plain-function model port — the common path. One async function
  * from the assembled messages to the model's answer; the handler validates the
  * answer through the purpose's `Schema` exactly as it re-validates the
- * structured-output path, so a malformed answer is a `resilient_err`, never a
- * corrupt success. `ModelFactory` → `withStructuredOutput(schema).invoke(...)`
+ * structured-output path, so a malformed answer is a `resilient_run_err`, never
+ * a corrupt success. `ModelFactory` → `withStructuredOutput(schema).invoke(...)`
  * stays the advanced form for a model that binds the schema itself.
  *
  * `T` is the answer type the schema narrows to — for the agent, an `AgentTurn`.
@@ -182,96 +150,6 @@ declare function plainModel<Msg, T>(fn: PlainModel<Msg, T>): ModelFactory<Msg>;
  * passed as `model` bare — the one runtime shape neither port can own.
  */
 declare const PLAIN_MODEL_MISROUTE_REASON: string;
-/**
- * One LLM call request — the resilient-call `input` for this module, carried on
- * the `resilient_run` Cmd as plain data — no closures, so it survives
- * persistence and replay. Purpose-discriminated: a `purpose` selecting the
- * schema + prompt assembly, the `model` id, and the opaque per-purpose
- * `payload` the loader consumes.
- *
- * `key` defaults to `purpose` when the consumer calls `attempt(s, purpose, …)`,
- * so one in-flight call per purpose is tracked under the resilient-call slice —
- * the common single-call-per-stage shape. A consumer that fans out many calls
- * of one purpose passes a distinct `key`.
- */
-interface LlmCall<P extends string> {
-    /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */
-    readonly purpose: P;
-    /** The model id to invoke; `null` = the host's default model. */
-    readonly model: string | null;
-    /** The per-purpose prompt payload the `MessageLoader` consumes. Opaque to the knob. */
-    readonly payload: unknown;
-}
-/** The parsed, typed success carried on the `resilient_ok` settle Msg, tagged with its purpose. */
-interface LlmOk<P extends string, O extends Record<P, unknown>> {
-    readonly key: string;
-    readonly purpose: P;
-    readonly output: O[P];
-}
-/** The typed failure variant — every failure path surfaces this, tagged by purpose. */
-interface LlmErr<P extends string> {
-    readonly key: string;
-    readonly purpose: P;
-    /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */
-    readonly reason: string;
-    /** The original error, carried untouched for the consumer to inspect. */
-    readonly error: unknown;
-}
-/**
- * The settle Msgs llm-call's handler RETURNS from `interpret` so the substrate
- * enqueues them as follow-up Msgs (re-entry) into the host reducer — exactly as
- * `../resilient-call` does. They are the resilient-call settle Msgs with the
- * payloads ENRICHED to llm-call's typed variants: `result` is the parsed,
- * purpose-tagged `LlmOk`; `error` is the typed `LlmErr` (purpose + reason +
- * raw). The host wires `resilient_ok` → `succeed` and `resilient_err` → `fail`
- * reducer arms (the doc-comment wiring), and folds the enriched payload into its
- * own state there — llm-call never forces a Msg vocabulary on the host, and the
- * settle Msg drives the inherited succeed/fail → backoff → onTimer loop instead
- * of bypassing it.
- */
-type LlmSucceedMsg<P extends string, O extends Record<P, unknown>> = SucceedMsg<LlmOk<P, O>>;
-/**
- * The FAILURE settle Msg (`resilient_err`) — resilient-call's `FailMsg` with its
- * `error: unknown` narrowed to the typed `LlmErr`, so the host reducer reads the
- * purpose, the reason and the raw payload without a cast.
- */
-type LlmFailMsg<P extends string> = Omit<FailMsg, "error"> & {
-    readonly error: LlmErr<P>;
-};
-/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */
-type LlmTimerMsg = DeadlineExceeded;
-/**
- * The ports the LEGACY detached `handlers(ports)` form takes. Two outbound Msg
- * builders the handler hands the typed Ok / Err; the consumer returns its own
- * Msg (or `undefined`). KEPT only for `../agent`, which still inherits the
- * detached shape; that path does NOT drive the retry loop (it dispatches the
- * consumer's Msg directly and never re-enters the resilient settle Msg). New
- * consumers use the no-arg `handlers()` form, which RETURNS the settle Msg for
- * re-entry and drives the inherited succeed/fail → backoff → onTimer loop.
- * `../agent` carries the same retry-loop gap and is fixed separately.
- *
- * The builders return `M | undefined` — `undefined` is the "dispatch nothing"
- * sentinel the detached form checks (`!== undefined`), spelled as `undefined`
- * rather than `void` so the union is unambiguous (a `void` member of a union is
- * confusing and reads as "may return anything").
- */
-interface LlmCallPorts<P extends string, O extends Record<P, unknown>, M> {
-    /** Build the Msg dispatched on a parsed success. Return `undefined` to dispatch nothing. */
-    readonly onOk: (ok: LlmOk<P, O>) => M | undefined;
-    /** Build the Msg dispatched on any failure (throw / retry-exhausted / parse). */
-    readonly onErr: (err: LlmErr<P>) => M | undefined;
-}
-/**
- * The effect Cmd this module emits: run the LLM call for `key` with `input`. The
- * `input` is the plain `LlmCall` request — the handler reads `purpose` /
- * `model` / `payload` off it (invariant 3: Cmds are data).
- *
- * It is `../resilient-call`'s `RunCmd` specialized to the `LlmCall` input — NOT a
- * re-declared shape — so the resilient verbs' return tuples (`[State, RunCmd[]]`)
- * are this exact type and thread through `attempt` / `succeed` / `fail` /
- * `onTimer` with no cast.
- */
-type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;
 
 /**
  * @demlik/tea/agent — the domain data model: the tool + turn shapes the consumer
@@ -1121,8 +999,8 @@ type CompactInterpret<M extends {
  */
 
 /**
- * The prefix a protocol discriminant was minted from: `resilient_ok` →
- * `resilient`, `compact_run` → `compact`. A tool named by that prefix would
+ * The prefix a protocol discriminant was minted from: `resilient_run_ok` →
+ * `resilient_run`, `compact_run` → `compact`. A tool named by that prefix would
  * mint the same `<name>_ok` / `<name>_err` the agent's reducer already owns.
  */
 type SettlePrefixOf<T extends string> = T extends `${infer P}_ok` | `${infer P}_err` | `${infer P}_run` ? P : never;
@@ -1132,10 +1010,13 @@ declare const SNAPSHOT_WRITE_TYPE = "snapshot_write";
  * A tool name `tool()` refuses. A tool's name is its Cmd `type` — so
  * its interpret key — and the prefix of its settle Msgs, so every string
  * already spoken by the protocol is taken twice over: the settle prefixes
- * (`resilient`, `agent_tool`, `compact`) would overwrite the agent's own
+ * (`resilient_run`, `agent_tool`, `compact`) would overwrite the agent's own
  * reducer handlers through `toMachine`'s last-wins spread, and the discriminants
  * themselves (`compact_run`, `resilient_run`, …) would shadow the interpret
- * handler of that name. Both halves derive from `MsgType`: a new entry there
+ * handler of that name. `resilient` is reserved as a Cmd prefix — the part
+ * before `_run` in the brain Cmd `resilient_run` — not as a settle prefix: its
+ * `resilient_ok` / `resilient_err` name nothing the agent settles. Both halves
+ * derive from `MsgType`: a new entry there
  * reserves its name and its prefix with no second edit. The two names outside
  * the protocol are the router's own `tool_rejected` and the checkpoint handler
  * `snapshot_write`, which `toMachine` merges under the consumer's key.
@@ -1173,60 +1054,67 @@ type ToolThrown = {
  * fixed to what the `ok` schema parses, so a value of the wrong shape is
  * refused where it is written.
  */
-type ToolOk<Ok, E extends Tagged> = (value: Ok) => Result<Ok, E>;
+type ToolOk<Ok, E extends Tagged> = (value: Ok) => Outcome<Ok, E>;
 /**
  * The typed failure constructor a handler receives: `fail({ _tag })` with `E`
  * fixed to the declared tags, so the literal is checked against them where it
  * is written. (A bare `{ _tag: "x" }` built elsewhere infers `_tag: string`
  * and cannot be — the parameter type is what keeps it literal.)
  */
-type ToolFail<Ok, E extends Tagged> = (error: E) => Result<Ok, E>;
+type ToolFail<Ok, E extends Tagged> = (error: E) => Outcome<Ok, E>;
 /**
  * The two constructors a handler is handed, one per channel — `ok` for the
- * value the `ok` schema parses, `fail` for a declared `{ _tag }`. Both are
- * tea's, so a handler settles either arm without naming the result library
- * underneath.
+ * value the `ok` schema parses, `fail` for a declared `{ _tag }`. Both build
+ * the core's `Outcome` record (ADR 0021).
  */
 type ToolConstructors<Ok, E extends Tagged> = {
     readonly ok: ToolOk<Ok, E>;
     readonly fail: ToolFail<Ok, E>;
 };
 /**
- * A tool's handler: the parsed `args`, the ctx slice `requirements` named, and the
- * typed `{ ok, fail }`, to a result over the declared channels — `Ok` is what
- * the `ok` schema parses, `E` the declared `_tag` union. An undeclared tag
- * does not compile.
+ * A tool's handler: the parsed `args`, the plain `ctx` the host handed `run`,
+ * and the typed `{ ok, fail }`, to an outcome over the declared channels — `Ok`
+ * is what the `ok` schema parses, `E` the declared `_tag` union. An undeclared
+ * tag does not compile. `Ctx` is whatever the handler annotates its `ctx`
+ * parameter with; tea does no dependency injection (ADR 0020).
  */
-type ToolHandler<Args, Ok, E extends Tagged, R> = (args: Args, ctx: R & PortEmitter, settle: ToolConstructors<Ok, E>) => Promise<Result<Ok, E>>;
+type ToolHandler<Args, Ok, E extends Tagged, Ctx> = (args: Args, ctx: Ctx & PortEmitter, settle: ToolConstructors<Ok, E>) => Promise<Outcome<Ok, E>>;
 /**
  * What `tool()` returns: the `Cmd.define`d constructor (so `Settled<typeof t>`
  * / `CmdOf<typeof t>` read it like any def) plus the colocated `interpret` handler,
  * the bare `args` schema the router parses a call against, and the
  * `description` a provider adapter declares to the model beside that schema.
  * `E` is the full failure union the Cmd settles with — the declared tags plus
- * `thrown`.
+ * `thrown`. `Ctx` is the ctx the colocated handler reads — a fact about the
+ * handler, never about the Cmd it builds (ADR 0020).
  */
-type ToolDef<Name extends string, Args, Ok, E extends Tagged, R> = CmdDef<Name, ToolInput<Args>, Ok, E, R> & {
+type ToolDef<Name extends string, Args, Ok, E extends Tagged, Ctx> = CmdDef<Name, ToolInput<Args>, Ok, E> & {
     readonly description: string;
-    readonly args: z.ZodType<Args>;
+    readonly args: StandardSchemaV1<unknown, Args>;
     /**
      * The timeout / retry knob this tool declared, or `null` when it declared
      * neither. `toolRouter` serves it to the agent as `resilienceOf`.
      */
     readonly resilience: ToolResilience | null;
-    readonly interpret: (cmd: CmdValue<Name, ToolInput<Args>, E, R>, ctx: R & PortEmitter) => Promise<Settled<CmdDef<Name, ToolInput<Args>, Ok, E, R>>>;
+    /**
+     * The colocated handler, as an interpret cell: it returns the tool's
+     * outcome, and the engine mints `<name>_ok` / `<name>_err` from it.
+     */
+    readonly interpret: (cmd: CmdValue<Name, ToolInput<Args>, Ok, E>, ctx: Ctx & PortEmitter) => Promise<Outcome<Ok, E>>;
+    /** Phantom — the ctx the handler reads. Never assigned. */
+    readonly __ctx?: Ctx;
 };
 /** The declaration-erased view the router reads. */
 type AnyToolDef = AnyCmdDef & {
     readonly description: string;
-    readonly args: z.ZodType;
+    readonly args: StandardSchemaV1;
     readonly resilience: ToolResilience | null;
     readonly interpret: (cmd: never, ctx: never) => Promise<unknown>;
 };
 /**
  * Declare one tool the model may call — its name, the schemas for its arguments
  * and result, the failures it may return and the handler that runs it — and get
- * back a `Cmd<T, E, R>` definition, whose `T` is what `ok` parses and whose `E`
+ * back a `Cmd<T, Ok, E>` definition, whose `Ok` is what `ok` parses and whose `E`
  * is the `err` tag union, that you pass to `toolRouter` or `defineAgent`.
  *
  * So a tool's two declared channels ARE the kernel's two typed effect channels
@@ -1240,9 +1128,10 @@ type AnyToolDef = AnyCmdDef & {
  * `description`, OpenAI `function.description`) so the model can tell when to
  * call the tool, read off `def.description`, never off the `input` schema;
  * `input` parses the model's `args`; `ok` parses the handler's value at the
- * edge; `err` is the `_tag` list the handler may fail with; `requirements` is the ctx
- * slice it reads, demanded at `run`. The handler returns one of the two
- * constructors it is handed — `ok(value)` or the typed `fail({ _tag })`; a
+ * edge; `err` is the `_tag` list the handler may fail with. The handler reads
+ * its services off the plain `ctx` `run` was handed — annotate its `ctx`
+ * parameter and `defineAgent` asks for that ctx at `run`. The handler returns
+ * one of the two constructors it is handed — `ok(value)` or the typed `fail({ _tag })`; a
  * throw settles `<name>_err` — with the thrown `_tag` when it is a declared
  * one, else as `{ _tag: "thrown", message }`.
  *
@@ -1250,12 +1139,11 @@ type AnyToolDef = AnyCmdDef & {
  * as a widened `string` throws — the same declaration-bug refusal
  * `toolRouter` gives a name declared twice.
  */
-declare function tool<const Name extends string, Args, Ok, const Tags extends readonly string[], R = unknown>(name: Name & NotReserved<Name>, spec: {
+declare function tool<const Name extends string, Args, Ok, const Tags extends readonly string[], Ctx = unknown>(name: Name & NotReserved<Name>, spec: {
     readonly description: string;
-    readonly input: z.ZodType<Args>;
-    readonly ok: z.ZodType<Ok>;
+    readonly input: StandardSchemaV1<unknown, Args>;
+    readonly ok: StandardSchemaV1<unknown, Ok>;
     readonly err: Tags;
-    readonly requirements?: Requirements<R>;
     /**
      * The budget one call of this tool gets, in ms — the overall cap, measured
      * from the first attempt and not restarted by a retry. When it elapses the
@@ -1275,7 +1163,7 @@ declare function tool<const Name extends string, Args, Ok, const Tags extends re
      * Omit → the first failure is the outcome.
      */
     readonly retry?: ToolResilience["retry"];
-}, handler: ToolHandler<Args, Ok, TaggedError<Tags[number]>, R>): ToolDef<Name, Args, Ok, TaggedError<Tags[number] | "thrown">, R>;
+}, handler: ToolHandler<Args, Ok, TaggedError<Tags[number]>, Ctx>): ToolDef<Name, Args, Ok, TaggedError<Tags[number] | "thrown">, Ctx>;
 /**
  * A call the router could not hand to a tool: the model named a tool nobody
  * declared, or its `args` failed the tool's `input` schema. `toolOf` is total —
@@ -1302,11 +1190,24 @@ declare const rejected: CmdDef<"tool_rejected", {
 } | {
     readonly [detail: string]: unknown;
     readonly _tag: "malformed_args";
-}, unknown>;
+}>;
 /** The Cmd `tool_rejected` builds — the router-owned variant of `ToolCmd`. */
 type ToolRejectedCmd = CmdOf<typeof rejected>;
 /** The Cmd union a router's `toolOf` produces — `TC` for `createAgent`. */
 type ToolCmd<T extends AnyToolDef> = CmdOf<T> | ToolRejectedCmd;
+/** The ctx one tool's handler reads; `unknown` for a handler that reads none. */
+type ToolCtxOf<T> = T extends {
+    readonly __ctx?: infer Ctx;
+} ? Ctx : unknown;
+type UnionToIntersection<U> = (U extends unknown ? (u: U) => void : never) extends (u: infer I) => void ? I : never;
+type ToolCtxBoxed<T> = T extends unknown ? [ToolCtxOf<T>] : never;
+type KnownToolCtx<B> = B extends [infer Ctx] ? unknown extends Ctx ? never : Ctx : never;
+/**
+ * The ctx a tool set's handlers read, intersected — what `run` asks the host
+ * for once the tools are wired into a machine. A tool whose handler reads
+ * nothing leaves its siblings' demand intact.
+ */
+type ToolsCtx<T extends AnyToolDef> = UnionToIntersection<KnownToolCtx<ToolCtxBoxed<T>>>;
 /** The settled Msg union a router's handlers return — folded by `toMachine`. */
 type ToolMsg<T extends AnyToolDef> = Settled<T> | Settled<typeof rejected>;
 /**
@@ -1355,7 +1256,7 @@ interface ToolRouter<T extends AnyToolDef> {
     /** The `toolOf` for `createAgent`: total, pure, parses `args` at the edge. */
     readonly toolOf: (call: ToolCall) => ToolCmd<T>;
     /** One interpret handler per tool plus the `tool_rejected` handler. */
-    readonly interpret: Interpret<ToolMsg<T>, ToolCmd<T>, NoCtx>;
+    readonly interpret: Interpret<ToolMsg<T>, ToolCmd<T>, ToolsCtx<T>>;
     /**
      * The timeout / retry knob the called tool declared — `AgentConfigCore`'s
      * `toolResilienceOf` seam, filled from the `tool()` specs. `null` for a tool
@@ -1419,7 +1320,7 @@ declare function toolRouter<T extends AnyToolDef>(tools: readonly T[]): ToolRout
  * the bare cells at the serial default, and a tool that never overlaps is the
  * exact function `toolRouter` built.
  */
-declare function fanOutInterpret<T extends AnyToolDef>(interpret: Interpret<ToolMsg<T>, ToolCmd<T>, NoCtx>): Interpret<ToolMsg<T>, ToolCmd<T>, NoCtx>;
+declare function fanOutInterpret<T extends AnyToolDef>(interpret: Interpret<ToolMsg<T>, ToolCmd<T>, ToolsCtx<T>>): Interpret<ToolMsg<T>, ToolCmd<T>, ToolsCtx<T>>;
 /**
  * Turn a tool failure into the human-readable reason string the conversation
  * carries — pass the `{ _tag, ...detail }` a tool failed with, get the tag
@@ -1487,7 +1388,10 @@ type SnapshotInterpret<M extends {
     readonly snapshot_write?: never;
 };
 /**
- * The `toMachine` signature, parametrized on the `Snap` + `Compact` discriminants
+ * The `toMachine` signature. It returns a `Wired`: the machine and, beside it,
+ * the merged `interpret` table and the `deadline` runner its one Sub needs — a
+ * machine carries no handlers (#278, #279), so it is run as
+ * `run(wired.machine, { ...wired, ctx })`. Parametrized on the `Snap` + `Compact` discriminants
  * so the snapshotting / compaction overloads of `createAgent` hand back the right
  * obligations. The `toolInterpret` requires (ON) or forbids (OFF) the
  * `snapshot_write` handler via {@link SnapshotInterpret} and the `compact_run` handler
@@ -1503,11 +1407,16 @@ type SnapshotInterpret<M extends {
 type AgentToMachine<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd, Snap extends boolean, Compact extends boolean> = <Ctx = object, T extends AnyToolDef = never>(opts?: {
     readonly tools?: ToolRouter<T>;
     readonly toolInterpret?: Interpret<AgentMachineMsg<P, O, R> | WiredToolMsg<T>, Exclude<TC, WiredToolCmd<T>>, Ctx> & SnapshotInterpret<AgentMachineMsg<P, O, R> | WiredToolMsg<T>, Snap, Ctx> & CompactInterpret<AgentMachineMsg<P, O, R> | WiredToolMsg<T>, Compact, Ctx>;
-}) => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R> | WiredToolMsg<T>, AgentCmd<P, TC, Snap, Compact>, DeadlineSub, Ctx>;
+}) => {
+    readonly machine: Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R> | WiredToolMsg<T>, AgentCmd<P, TC, Snap, Compact>, DeadlinesSub, Ctx & ToolsCtx<T>>;
+    readonly interpret: Interpret<AgentMachineMsg<P, O, R> | WiredToolMsg<T>, AgentCmd<P, TC, Snap, Compact>, Ctx & ToolsCtx<T>>;
+    readonly subscribe: Subscribe<AgentMachineMsg<P, O, R> | WiredToolMsg<T>, DeadlinesSub, Ctx & ToolsCtx<T>>;
+};
 /**
  * The agent handle `createAgent` returns — the uniform verb contract every tea
- * composition exposes, plus the wired `toMachine` and the `unsafeDetachedHandlers`
- * escape hatch. `Snap` flows ONLY into `toMachine`'s `toolInterpret` obligation
+ * composition exposes, plus the wired `toMachine` and `brainInterpret`, the
+ * brain call's handler for a consumer wiring the verbs by hand. `Snap` flows
+ * ONLY into `toMachine`'s `toolInterpret` obligation
  * (the snapshot derivation); every verb is snapshot-agnostic. The model
  * message shape `Msg` does not appear on the handle's surface (it is internal to the
  * brain call's loader), so it is not a type parameter here — only `createAgent`
@@ -1537,12 +1446,10 @@ interface AgentKnob<Stage, P extends string, O extends Record<P, AgentTurn>, R,
         at: number
     ]>;
     readonly succeed: AgentVerb1<Stage, P, O, R, TC, [
-        key: string,
         msg: AgentLlmOkMsg<P, O>,
         at: number
     ]>;
     readonly fail: AgentVerb1<Stage, P, O, R, TC, [
-        key: string,
         msg: AgentLlmErrMsg<P>,
         at: number
     ]>;
@@ -1563,15 +1470,23 @@ interface AgentKnob<Stage, P extends string, O extends Record<P, AgentTurn>, R,
     readonly brainCall: (s: AgentState<Stage, P, O, R>) => LlmCall<P>;
     readonly subs: (s: AgentState<Stage, P, O, R>) => readonly DeadlineSub[];
     readonly toMachine: AgentToMachine<Stage, P, O, R, TC, Snap, Compact>;
-    readonly unsafeDetachedHandlers: <M>(ports: AgentPorts<P, O, M>) => AgentDetachedHandlers<P, M>;
+    /**
+     * The brain call's `resilient_run` handler — the one `toMachine` wires. Its
+     * Cmd is `Cmd.define`d, so it returns an outcome and the engine mints the
+     * `resilient_run_ok` / `resilient_run_err` Msg that `succeed` / `fail` fold
+     * (ADR 0021). List `AgentKnob`'s brain Cmd def in `cmds` when you hand-wire.
+     */
+    readonly brainInterpret: () => Interpret<AgentLlmOkMsg<P, O> | AgentLlmErrMsg<P>, AgentLlmRunCmd<P>, unknown>;
+    /** The brain call's `Cmd.define`d run Cmd def — list it in `cmds` when you hand-wire. */
+    readonly brain: RunCmdDef<LlmCall<P>, LlmOk<P, O>>;
 }
 /** A verb taking the state + `Args`, returning the agent's `[State, Cmd[]]` tuple. */
 type AgentVerb1<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd, Args extends readonly unknown[]> = (s: AgentState<Stage, P, O, R>, ...args: Args) => readonly [AgentState<Stage, P, O, R>, readonly AgentCmd<P, TC>[]];
 /** The brain-call SUCCESS settle Msg, inherited from `../llm-call`. */
 type AgentLlmOkMsg<P extends string, O extends Record<P, unknown>> = LlmSucceedMsg<P, O>;
 /**
- * The brain-call FAILURE settle Msg, inherited from `../llm-call` — it re-enters
- * the agent's `fail` verb, which backs off via the retry ladder rather than
+ * The brain-call FAILURE settle Msg, inherited from `../llm-call` — the engine
+ * mints it from the brain handler's outcome and it drives the agent's `fail` verb, which backs off via the retry ladder rather than
  * ending the run.
  */
 type AgentLlmErrMsg<P extends string> = LlmFailMsg<P>;
@@ -1579,35 +1494,11 @@ type AgentLlmErrMsg<P extends string> = LlmFailMsg<P>;
  * The timer Msg (retry + safety deadline) — `DeadlineExceeded`, the shared
  * shape of both composed wrappers' timer Msgs (`LlmTimerMsg` and `MonitoredRunTimerMsg`
  * are both `DeadlineExceeded`). One Msg variant covers both timers; `onTimer`
- * disambiguates by Sub id. This is also the machine Msg the `subscribeDeadline`
- * handler dispatches directly (no wrapping), matching the sibling gold standard.
+ * disambiguates by deadline id. This is also the machine Msg the
+ * `subscribeDeadline` runner dispatches directly (no wrapping), matching the
+ * sibling gold standard.
  */
 type AgentTimerMsg = LlmTimerMsg;
-/** Ports the consumer supplies to the llm-call handler — re-exported shape. */
-type AgentPorts<P extends string, O extends Record<P, unknown>, M> = LlmCallPorts<P, O, M>;
-/**
- * The LEGACY detached brain-call handler dictionary `handlers(ports)` returns,
- * superseded by the `Interpret` table `AgentKnob.toMachine()` wires — reach for
- * `toMachine()` unless you are hand-wiring the verbs yourself.
- *
- * It is the inherited `../llm-call` detached form's exact shape, NOT an
- * `Interpret`.
- * The `resilient_run` handler runs the invoke inside `ctx.waitUntil` and dispatches
- * the consumer's `onOk` / `onErr` Msg directly (returning `void`), so it is a
- * fire-and-forget handler with a structural `{ waitUntil, dispatch }` ctx — it
- * does not re-enter the resilient settle Msg and so does not drive the retry
- * loop. Naming the type precisely (rather than laundering it through
- * `as unknown as Interpret<...>`) keeps `agent.unsafeDetachedHandlers(ports)` honest: the
- * consumer that wires the verbs by hand gets the real detached shape, and its
- * `resilient_run` is callable with a plain Cmd + a `{ waitUntil, dispatch }` ctx
- * with no `as never` at the call site.
- */
-type AgentDetachedHandlers<P extends string, M> = {
-    readonly resilient_run: (cmd: AgentLlmRunCmd<P>, ctx: {
-        waitUntil(p: Promise<unknown>): void;
-        dispatch(msg: M): unknown;
-    }) => void;
-};
 /** The Msg `do/host`'s `autoBoot` fires to re-enter the agent's `boot` verb on rehydrate. */
 type AgentBootMsg = {
     readonly type: typeof MsgType.AgentBoot;
@@ -1637,16 +1528,16 @@ declare function agentCancelMsg(at: number): AgentCancelMsg;
  * The agent machine's Msg union — one variant per reducer entry point. A
  * consumer using `toMachine` dispatches `agent_start` to begin and `agent_tool_ok`
  * / `agent_tool_err` to route settled tools back; the brain-call settle Msgs
- * (`resilient_ok` / `resilient_err`) RE-ENTER from the FIXED `brainHandlers`
- * (the substrate enqueues an interpret handler's returned Msg as a follow-up),
- * driving `succeed` / `fail`. Time enters via `at` on every variant — the
+ * (`resilient_run_ok` / `resilient_run_err`) are minted by the engine from the
+ * outcome the FIXED `brainHandlers` returns (ADR 0021), driving `succeed` /
+ * `fail`. Time enters via `at` on every variant — the
  * reducer never reads the clock.
  *
  * There is deliberately NO `agent_turn` variant here. The wired loop folds a
- * model turn INSIDE `succeed` from the re-entered `resilient_ok` — a single
+ * model turn INSIDE `succeed` from the minted `resilient_run_ok` — a single
  * settle Msg advances both the retry slice and the conversation (the L3 fix).
  * Exposing `agent_turn` as a dispatchable Msg re-opened the stuck-`running` bug:
- * a hand-fed turn folds the conversation without ever re-entering `resilient_ok`,
+ * a hand-fed turn folds the conversation without ever settling `resilient_run_ok`,
  * so `succeed` never runs and the resilient slice stays `running`. The
  * `turn` verb remains on the handle for the consumer that wires the verbs by hand
  * (manual wiring), but it is not part of the one wired machine's Msg surface.
@@ -1678,7 +1569,7 @@ type AgentMachineMsg<P extends string, O extends Record<P, unknown>, R> = {
  * the retry plumbing is renamed.
  *
  *   - `TurnSettled` — a brain turn settled (the model produced an `AgentTurn`).
- *     Projected off the private `resilient_ok` settle Msg; carries the parsed
+ *     Projected off the private `resilient_run_ok` settle Msg; carries the parsed
  *     `turn` (the narration + tool calls the model asked for).
  *   - `ToolSettled` — a tool call settled OK. Projected off the private
  *     `agent_tool_ok` Msg; carries the `callId` and the tool `result`.
@@ -1704,7 +1595,7 @@ type AgentEvent<R> = {
  * `run(machine, { events: agentEvents() })` to light up `runtime.on(...)`.
  *
  * This is the ONE place the agent's PRIVATE Msg names are read: it maps
- * `resilient_ok` → `TurnSettled` and `agent_tool_ok` → `ToolSettled`, and reads
+ * `resilient_run_ok` → `TurnSettled` and `agent_tool_ok` → `ToolSettled`, and reads
  * the post-transition `run.phase` for `RunDone`. The mapping is total over the
  * Msg union (a `default`-free switch on the discriminant) and returns `[]` for
  * the transitions that carry no public event (start / boot / timer / the error
@@ -1712,7 +1603,7 @@ type AgentEvent<R> = {
  *
  * A single transition may emit more than one event: the brain turn that retires
  * the final stage settles a turn (`TurnSettled`) AND finishes the run
- * (`RunDone`) — both are projected from that one `resilient_ok` transition.
+ * (`RunDone`) — both are projected from that one `resilient_run_ok` transition.
  * `RunDone` is gated on `run.phase === "done"`, which the wired loop reaches
  * exactly once (the agent is terminal there and dispatches no further
  * transition), so the event fires once per run.
@@ -1770,4 +1661,4 @@ declare function liftAgent<S extends {
     agent: AgentState<Stage, P, O, R>;
 }, Stage, P extends string, O extends Record<P, unknown>, R, C extends Cmd>(state: S, [slice, cmds]: readonly [AgentState<Stage, P, O, R>, readonly C[]]): readonly [S, readonly C[]];
 
-export { PLAIN_MODEL_MISROUTE_REASON as $, type AnyToolDef as A, type AgentSnapshotConfig as B, type Conversation as C, type AgentStatus as D, type AgentTerminalFailure as E, type AgentTimerMsg as F, type AgentToMachine as G, type Awaiting as H, COMPACTION_PURPOSE as I, type CompactInterpret as J, type CompactionOutputs as K, type CompactionPurpose as L, type CompactionSummary as M, type LlmCall as N, type LlmErr as O, type PlainModel as P, type LlmFailMsg as Q, type LlmOk as R, type StreamingModel as S, type ToolCall as T, type LlmRunCmd as U, type LlmSucceedMsg as V, type WiredToolMsg as W, type MessageLoader as X, type ModelFactory as Y, type ModelPort as Z, type ModelStream as _, type ToolOutcome as a, type ReservedToolName as a0, type Schema as a1, type SnapshotInterpret as a2, TOOL_RETRY_EXHAUSTED_TAG as a3, TOOL_TIMEOUT_TAG as a4, type TaggedFailure as a5, type ToolConstructors as a6, type ToolDef as a7, type ToolError as a8, type ToolFail as a9, liftAgent as aA, mergeInterpret as aB, plainModel as aC, status as aD, tool as aE, toolErrorReason as aF, toolRouter as aG, type ToolFailure as aa, type ToolHandler as ab, type ToolInput as ac, type ToolMsg as ad, type ToolOk as ae, type ToolRecord as af, type ToolRejectedCmd as ag, type ToolRejection as ah, type ToolResilience as ai, type ToolResilienceError as aj, type ToolRetryExhausted as ak, type ToolRouter as al, type ToolSettlement as am, type ToolThrown as an, type ToolTimedOut as ao, type WiredToolCmd as ap, agentBootMsg as aq, agentCancelMsg as ar, agentEvents as as, agentTurnSchema as at, compactionSummarySchema as au, fanOutInterpret as av, isAgentTurn as aw, isCompactionSummary as ax, isReservedToolName as ay, isStreamingModel as az, type AgentTurn as b, type AgentState as c, type ToolResult as d, type ToolFailureOf as e, type ToolCmd as f, type AgentEvent as g, type TurnChunk as h, type AgentMachineMsg as i, type AgentCmd as j, type AgentConfigCore as k, type CompactionPolicy as l, type AgentKnob as m, type AgentBootMsg as n, type AgentCancelMsg as o, type AgentCompactErrMsg as p, type AgentCompactOkMsg as q, type AgentCompactRunCmd as r, type AgentCompactionConfig as s, type AgentConfig as t, type AgentDetachedHandlers as u, type AgentFailure as v, type AgentLlmErrMsg as w, type AgentLlmOkMsg as x, type AgentLlmRunCmd as y, type AgentPorts as z };
+export { PLAIN_MODEL_MISROUTE_REASON as $, type AnyToolDef as A, type AgentStatus as B, type Conversation as C, type AgentTerminalFailure as D, type AgentTimerMsg as E, type AgentToMachine as F, type Awaiting as G, COMPACTION_PURPOSE as H, type CompactInterpret as I, type CompactionOutputs as J, type CompactionPurpose as K, type CompactionSummary as L, type Llm as M, type LlmCall as N, type LlmErr as O, type PlainModel as P, type LlmFailMsg as Q, type LlmOk as R, type StreamingModel as S, type ToolCall as T, type LlmRunCmd as U, type LlmSucceedMsg as V, type WiredToolMsg as W, type MessageLoader as X, type ModelFactory as Y, type ModelPort as Z, type ModelStream as _, type ToolOutcome as a, type ReservedToolName as a0, type Schema as a1, type SnapshotInterpret as a2, TOOL_RETRY_EXHAUSTED_TAG as a3, TOOL_TIMEOUT_TAG as a4, type TaggedFailure as a5, type ToolConstructors as a6, type ToolDef as a7, type ToolError as a8, type ToolFail as a9, liftAgent as aA, mergeInterpret as aB, plainModel as aC, status as aD, tool as aE, toolErrorReason as aF, toolRouter as aG, type ToolFailure as aa, type ToolHandler as ab, type ToolInput as ac, type ToolMsg as ad, type ToolOk as ae, type ToolRecord as af, type ToolRejectedCmd as ag, type ToolRejection as ah, type ToolResilience as ai, type ToolResilienceError as aj, type ToolRetryExhausted as ak, type ToolRouter as al, type ToolSettlement as am, type ToolThrown as an, type ToolTimedOut as ao, type WiredToolCmd as ap, agentBootMsg as aq, agentCancelMsg as ar, agentEvents as as, agentTurnSchema as at, compactionSummarySchema as au, fanOutInterpret as av, isAgentTurn as aw, isCompactionSummary as ax, isReservedToolName as ay, isStreamingModel as az, type AgentTurn as b, type AgentState as c, type ToolResult as d, type ToolFailureOf as e, type ToolsCtx as f, type AgentEvent as g, type TurnChunk as h, type AgentMachineMsg as i, type AgentCmd as j, type ToolCmd as k, type AgentConfigCore as l, type CompactionPolicy as m, type AgentKnob as n, type AgentBootMsg as o, type AgentCancelMsg as p, type AgentCompactErrMsg as q, type AgentCompactOkMsg as r, type AgentCompactRunCmd as s, type AgentCompactionConfig as t, type AgentConfig as u, type AgentFailure as v, type AgentLlmErrMsg as w, type AgentLlmOkMsg as x, type AgentLlmRunCmd as y, type AgentSnapshotConfig as z };