@demlik/tea 0.13.0 → 0.15.0

package/dist/agent/index.d.ts

@@ -1,22 +1,606 @@
-import { C as Cmd } from '../core-Co0LWkIA.js';
-export { LlmCall, LlmErr, LlmFailMsg, LlmOk, LlmRunCmd, LlmSucceedMsg, MessageLoader, ModelFactory, Schema } from '../llm-call/index.js';
-import { A as AgentTurn, a as AgentConfigCore, C as CompactionPolicy, b as AgentKnob } from '../machine-BtFWQmmq.js';
-export { c as AgentBootMsg, d as AgentCmd, e as AgentCompactErrMsg, f as AgentCompactOkMsg, g as AgentCompactRunCmd, h as AgentCompactionConfig, i as AgentConfig, j as AgentDetachedHandlers, k as AgentEvent, l as AgentFailure, m as AgentLlmErrMsg, n as AgentLlmOkMsg, o as AgentLlmRunCmd, p as AgentMachineMsg, q as AgentPorts, r as AgentSnapshotConfig, s as AgentState, t as AgentStatus, u as AgentTerminalFailure, v as AgentTimerMsg, w as AgentToMachine, x as Awaiting, y as COMPACTION_PURPOSE, z as CompactInterpret, B as CompactionOutputs, D as CompactionPurpose, E as CompactionSummary, F as Conversation, S as SnapshotInterpret, T as ToolCall, G as ToolOutcome, H as ToolRecord, I as agentBootMsg, J as agentEvents, K as agentTurnSchema, L as compactionSummarySchema, M as isAgentTurn, N as isCompactionSummary, O as liftAgent, P as mergeInterpret, Q as status } from '../machine-BtFWQmmq.js';
-export { MonitoredRunCmd, RunFailure } from '../monitored-run/index.js';
-export { DeadlineSub, deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import { R as RequiredCtx, M as Machine, I as Interpret, C as Cmd } from '../core-DnzqWy6u.js';
+import { T as ToolCall, a as ToolOutcome, C as Conversation, A as AnyToolDef, P as PlainModel, b as AgentTurn, S as StreamingModel, c as AgentState, d as ToolResult, e as ToolFailureOf, f as ToolCmd, g as AgentEvent, h as TurnChunk, i as AgentMachineMsg, W as WiredToolMsg, j as AgentCmd, k as AgentConfigCore, l as CompactionPolicy, m as AgentKnob } from '../machine-DGlPWCWI.js';
+export { n as AgentBootMsg, o as AgentCancelMsg, p as AgentCompactErrMsg, q as AgentCompactOkMsg, r as AgentCompactRunCmd, s as AgentCompactionConfig, t as AgentConfig, u as AgentDetachedHandlers, v as AgentFailure, w as AgentLlmErrMsg, x as AgentLlmOkMsg, y as AgentLlmRunCmd, z as AgentPorts, B as AgentSnapshotConfig, D as AgentStatus, E as AgentTerminalFailure, F as AgentTimerMsg, G as AgentToMachine, H as Awaiting, I as COMPACTION_PURPOSE, J as CompactInterpret, K as CompactionOutputs, L as CompactionPurpose, M as CompactionSummary, N as LlmCall, O as LlmErr, Q as LlmFailMsg, R as LlmOk, U as LlmRunCmd, V as LlmSucceedMsg, X as MessageLoader, Y as ModelFactory, Z as ModelPort, _ as ModelStream, $ as PLAIN_MODEL_MISROUTE_REASON, a0 as ReservedToolName, a1 as Schema, a2 as SnapshotInterpret, a3 as TOOL_RETRY_EXHAUSTED_TAG, a4 as TOOL_TIMEOUT_TAG, a5 as TaggedFailure, a6 as ToolConstructors, a7 as ToolDef, a8 as ToolError, a9 as ToolFail, aa as ToolFailure, ab as ToolHandler, ac as ToolInput, ad as ToolMsg, ae as ToolOk, af as ToolRecord, ag as ToolRejectedCmd, ah as ToolRejection, ai as ToolResilience, aj as ToolResilienceError, ak as ToolRetryExhausted, al as ToolRouter, am as ToolSettlement, an as ToolThrown, ao as ToolTimedOut, ap as WiredToolCmd, aq as agentBootMsg, ar as agentCancelMsg, as as agentEvents, at as agentTurnSchema, au as compactionSummarySchema, av as fanOutInterpret, aw as isAgentTurn, ax as isCompactionSummary, ay as isReservedToolName, az as isStreamingModel, aA as liftAgent, aB as mergeInterpret, aC as plainModel, aD as status, aE as tool, aF as toolErrorReason, aG as toolRouter } from '../machine-DGlPWCWI.js';
+import { a as ScopedCtxArg, S as Store } from '../runtime-types-CMF13BBh.js';
+import { E as EndedRun } from '../index-KXqTRJyb.js';
+export { M as MonitoredRunCmd, R as RunFailure } from '../index-KXqTRJyb.js';
+import { RetryPolicy } from '../retry-backoff/index.js';
+import { a as DeadlineSub } from '../index-HSYgG2Yt.js';
+export { b as deadlineSub, s as subscribeDeadline } from '../index-HSYgG2Yt.js';
 import 'zod';
-import '../resilient-call/index.js';
-import '../cache/index.js';
-import '../types-XS_miRnB.js';
-import '../circuit-breaker/index.js';
-import '../protocol-B5YmJr0d.js';
-import '../rate-limit/index.js';
-import '../retry-backoff/index.js';
-import '../fan-out/index.js';
-import '../work-queue/index.js';
-import '../runtime-types-CNLmhWif.js';
+import '../index-CA_7I5g9.js';
+import '../protocol-D8VbH-VH.js';
+import '../index-CuNO9m8i.js';
+import '../index-CSyMYDAB.js';
 import 'better-result';
-import '../snapshot/index.js';
+import '../index-ZCMhnVKN.js';
+import '../types-BseNPIhr.js';
+
+/**
+ * @demlik/tea/agent — `defineAgent`, the convenience layer over `createAgent`.
+ *
+ * `defineAgent({ model, tools, instructions })` is the three-line door: it
+ * defaults the single-stage wiring (`stages`, `turnOf`, `schemas`), derives the
+ * tool handlers from `toolRouter`, renders the prompt off the Model, and absorbs
+ * the drive loop through `driveToDone`. It hides wiring, never state (ADR
+ * 0015): the Model it runs is the same `AgentState` a hand-wired `createAgent`
+ * produces, under the same keys, and `machine(input)` is the door down to the
+ * raw kernel `run`. Each hidden thing is a named helper below.
+ */
+
+/**
+ * One message a `defineAgent` `model` receives. Plain data the adapter renders into
+ * its provider's shape: the head is the `instructions` (when set) and the
+ * run's `input`; then, per model turn, the `assistant` turn followed by the
+ * `tool` outcomes that turn asked for. A tool outcome rides as data — the
+ * adapter decides how a failure reads to its model. An `assistant` message
+ * carries the turn's opaque `provider` slot exactly as the adapter returned it
+ * (see `AgentTurn`), present only when the stored turn has one.
+ */
+type AgentMessage = {
+    readonly role: "system";
+    readonly content: string;
+} | {
+    readonly role: "user";
+    readonly content: string;
+} | {
+    readonly role: "assistant";
+    readonly content: string;
+    readonly toolCalls: readonly ToolCall[];
+    readonly provider?: unknown;
+} | {
+    readonly role: "tool";
+    readonly callId: string;
+    readonly name: string;
+    readonly outcome: ToolOutcome<unknown>;
+};
+/**
+ * The brain-call payload `defineAgent` builds from the durable state — everything
+ * `messagesOf` renders, so the prompt is a pure function of the Model and the
+ * resilient slice carries exactly what was sent.
+ */
+interface AgentPrompt<R> {
+    readonly instructions: string | null;
+    readonly input: string | null;
+    readonly conversation: Conversation<R>;
+}
+/** The one purpose a `defineAgent` agent runs. */
+type LidPurpose = "act";
+type LidOutputs = {
+    readonly [K in LidPurpose]: AgentTurn;
+};
+/** The Model a defined agent runs — a hand-wired `createAgent`'s, key for key. */
+type DefinedAgentState<T extends AnyToolDef> = AgentState<string, LidPurpose, LidOutputs, ToolResult<T>>;
+/**
+ * The Model `run` RESOLVES with — {@link DefinedAgentState} whose `run` slice is
+ * narrowed to the ended phases ({@link EndedRun}).
+ *
+ * `run`'s terminal predicate is `done || cancelled` and its `failed` one rejects,
+ * so the never-started `idle` arm is unreachable on the resolved value. Typing
+ * the promise as the whole Model published that unreachable arm anyway, and
+ * `idle` carries no `runId` — so `(await agent.run(input)).run.runId`, a field
+ * every resolved run has, did not typecheck (#155). The narrow is on what `run`
+ * can RESOLVE; the `idle` arm is untouched and still carries no `runId`.
+ *
+ * `DefinedAgentState` itself stays wide, because it is the DURABLE Model: an
+ * `init` slice is `idle`, and a `Store<DefinedAgentState<T>>` has to hold one.
+ */
+type DefinedAgentResolvedState<T extends AnyToolDef> = Omit<DefinedAgentState<T>, "run"> & {
+    readonly run: EndedRun<string>;
+};
+/** The ctx the tools' `needs` demand, intersected — what `run` asks for. */
+type DefinedAgentCtx<T extends AnyToolDef> = RequiredCtx<ToolCmd<T>>;
+/** The Msg union a defined agent's machine folds. */
+type DefinedAgentMsg<T extends AnyToolDef> = AgentMachineMsg<LidPurpose, LidOutputs, ToolResult<T>> | WiredToolMsg<T>;
+/**
+ * The Cmd union a defined agent's machine emits — one interpret cell per member.
+ *
+ * Snapshotting is fixed OFF (the lid checkpoints through the run's `store`, not
+ * the monitored-run cadence), so `snapshot_write` is out of the union.
+ * Compaction is fixed ON, which is the SUPERSET of the two machines
+ * `defineAgent` builds: with the knob set the `compact_run` cell is the one the
+ * lid wires, and without it the reducer provably emits no such Cmd, so the
+ * machine carries no cell for it and the union simply has a member nothing
+ * reaches. Naming the superset is what lets one type describe both arms — and
+ * it is why `with` may wrap `compact_run` on a compacting agent and gets
+ * `overlaid`'s "this machine has none of that cell" throw on one without.
+ */
+type DefinedAgentCmd<T extends AnyToolDef> = AgentCmd<LidPurpose, ToolCmd<T>, false, true>;
+/**
+ * The interpret table of the machine `defineAgent` wired: one cell per
+ * {@link DefinedAgentCmd}, keyed by its `type` — a tool's own Cmd type, the
+ * router's `tool_rejected`, and the agent-owned brain call.
+ */
+type DefinedAgentInterpret<T extends AnyToolDef> = Interpret<DefinedAgentMsg<T>, DefinedAgentCmd<T>, DefinedAgentCtx<T>>;
+/** The wired machine `defineAgent` builds per `input` — feed it to the raw `run`. */
+type DefinedAgentMachine<T extends AnyToolDef> = Machine<DefinedAgentState<T>, DefinedAgentMsg<T>, DefinedAgentCmd<T>, DeadlineSub, DefinedAgentCtx<T>>;
+/**
+ * The brain a defined agent runs, in either of its two shapes:
+ *
+ *   - `async (messages) => turn` — the plain port, and the common path.
+ *   - `async (messages, { onChunk }) => turn` — the same call, plus a side
+ *     channel it may write token deltas to while the turn is in flight.
+ *
+ * `defineAgent` takes one field for both and tells them apart by arity
+ * (`isStreamingModel`), so there is no config flag saying which you passed and
+ * no way for that flag to disagree with the function. Whichever shape you
+ * write, the run's Model is the same: the turn it RESOLVES is what the reducer
+ * folds, and the deltas end at the `onChunk` run option (see
+ * {@link DefinedAgentRunOptions}).
+ *
+ * Both members are unions of one signature so a model written inline still gets
+ * its `messages` parameter typed from the config field.
+ */
+type DefinedAgentModel = PlainModel<AgentMessage, AgentTurn> | StreamingModel<AgentMessage, AgentTurn>;
+/**
+ * What `defineAgent` takes: the model, the tools and the instructions, plus the
+ * four optional guards that stop a run — `maxTurns`, `deadlineMs`,
+ * `maxElapsedMs` and `stopWhen` — and the one that keeps a run going, `retry`,
+ * the brain call's backoff ladder. Omit every guard and the run is unbounded:
+ * it ends only when the model stops asking for tools.
+ *
+ * Two more knobs bound what a run COSTS rather than whether it ends:
+ * `compaction`, which stops the transcript growing, and `toolConcurrency`,
+ * which says how many of a turn's tool calls go out at once.
+ */
+interface DefineAgentConfig<T extends AnyToolDef> {
+    /** The brain — either {@link DefinedAgentModel} shape. */
+    readonly model: DefinedAgentModel;
+    /** The `tool()`s the model may call. */
+    readonly tools: readonly T[];
+    /**
+     * The system prompt — stored on the Model at `init` (ADR 0004) and never
+     * re-read, so a resumed run keeps the prompt it started with even across a
+     * redeploy that changed this string; to replace a bad prompt already in
+     * flight, end that run and start a new one rather than resuming it.
+     */
+    readonly instructions: string;
+    /**
+     * Stops a run that keeps going: the maximum number of model round-trips it
+     * may take. Once the completed-turn count reaches it the run fails rather
+     * than calling the model again. Omit → no limit on turns.
+     */
+    readonly maxTurns?: number;
+    /**
+     * Stops a run that stops progressing: milliseconds the run may sit without
+     * advancing before it fails. The budget is a no-progress watchdog, not a
+     * total wall-clock cap — it restarts each time the run moves. Omit → no
+     * watchdog.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * Stops a run that keeps going, by the clock: total milliseconds from the
+     * run's start it may take before it fails. This is the total wall-clock cap
+     * `deadlineMs` is not — the budget never restarts, so a run that keeps
+     * progressing is bounded by it where `deadlineMs` would let it run forever,
+     * and it counts elapsed time where `maxTurns` counts round-trips. It is read
+     * at the turn boundary, so like both of those it stops the run rather than
+     * cancelling the work already in flight. Omit → no wall-clock cap.
+     *
+     * The run's start time is on the durable Model, so a run killed and resumed
+     * continues the ORIGINAL budget — the time it spent dead counts against it.
+     *
+     * The same name on a `DurationRetryPolicy` (`retry`, and a tool's own) is the
+     * same idea one altitude down: that one bounds how long ONE call's retry
+     * ladder may keep climbing, this one how long the whole run may take.
+     */
+    readonly maxElapsedMs?: number;
+    /**
+     * Stops a run on a condition only you can see: a predicate consulted at the
+     * turn boundary, after the other three guards have passed, over the run's
+     * durable Model. Answer `true` and the run ends there — settled `cancelled`,
+     * the same terminal an aborted `signal` reaches, with the transcript intact
+     * and no further model call made. Where `maxTurns` and `maxElapsedMs` bound
+     * a quantity the agent counts for you and `deadlineMs` watches for a stall,
+     * this bounds whatever you name — a token ledger you keep, an external flag,
+     * a condition on the turns so far. Omit → no predicate.
+     *
+     * It must be PURE: the reducer calls it, so a replay hands it the same state
+     * and must get the same answer. And it is config rather than Model — a
+     * resumed run consults the predicate the config passed to THIS boot, exactly
+     * as it uses the `maxTurns` passed to this boot.
+     */
+    readonly stopWhen?: (state: DefinedAgentState<T>) => boolean;
+    /**
+     * The backoff ladder a FAILED BRAIN CALL climbs — the same `RetryPolicy`
+     * shape `AgentConfigCore.retry` takes, threaded straight to it, so the ladder
+     * runs in the resilient slice that already exists and lives on the Model:
+     * each failure is recorded there and the next attempt is armed as a timer
+     * Sub, which is what makes the wait durable and the attempt count survive a
+     * reload.
+     *
+     * The per-tool knob grows no lid option because a `tool()` is a spec object
+     * that declares its own policy (`ToolResilience.retry`). A
+     * `defineAgent` `model` is a bare function with no spec object, so the lid is
+     * the only declaration site a brain-call policy has.
+     *
+     * Omit → NO backoff, exactly as before: one throw from `model` ends the run
+     * after a single attempt. Nothing is defaulted on your behalf — a silent
+     * default would change the failure timing of every existing caller.
+     */
+    readonly retry?: RetryPolicy;
+    /**
+     * Observe a tool call that failed, typed against THIS agent's tools: the
+     * outcome is `{ kind: "error", _tag, …payload, reason }` over
+     * `ToolError`'s union — declared tags, `thrown`, `malformed_result`,
+     * `unknown_tool`, `malformed_args` — so a `switch` on `_tag` is exhaustive and an
+     * unhandled failure mode is a compile error rather than a silent turn (#115).
+     * The model still reads `reason` next turn either way — this is the host's
+     * channel beside it, never instead of it.
+     *
+     * Called ONCE per failed call, at the interpret boundary: after the handler
+     * settled, before the failure is folded into the conversation. It is awaited,
+     * so an async hook holds the settle until it resolves — keep it short, and put
+     * anything slow on your own queue.
+     *
+     * A resume calls it for the calls THIS process runs and no others: an outcome
+     * a previous process already folded is in the Model the Store handed back and
+     * is never re-interpreted, so a durable run does not re-fire the hook over its
+     * history.
+     *
+     * The hook is CONTAINED, exactly as `onEvent` is: a throw (or a rejected
+     * promise) is warned about and the run goes on, so `run`'s contract does not
+     * depend on the hook's.
+     *
+     * Omit → the router is wired unwrapped and nothing observes failures.
+     */
+    readonly onToolError?: (outcome: ToolFailureOf<T>, ctx: ToolErrorContext) => void | Promise<void>;
+    /**
+     * Bounds a run that keeps going without ever failing: the transcript budget,
+     * past which the OLDEST turns are folded into one model-written summary
+     * before the next brain call, so a long run's prompt stops growing instead of
+     * climbing until the provider rejects it.
+     *
+     * The knob is a THRESHOLD, not a policy function — see
+     * {@link DefineAgentCompaction}. `compaction` is what a run tolerates, and the
+     * summarize round-trip that enforces it is wiring, so the lid takes the
+     * former and supplies the latter from the `model` it already has.
+     *
+     * Omit → NO compaction, exactly as before: the transcript grows for as long
+     * as the model keeps asking for tools. Nothing is defaulted on your behalf —
+     * a silent budget would change the prompt every existing caller sends.
+     */
+    readonly compaction?: DefineAgentCompaction;
+    /**
+     * How many of ONE turn's tool calls a transition launches at once. At the
+     * default `1` a turn's calls go out one at a time, each waiting for the last
+     * to settle; raise it and up to that many are launched together, so they are
+     * all in flight in the fan-out ledger rather than queued behind each other.
+     * A turn asking for more calls than this runs them in waves.
+     *
+     * Launched together means overlapping on the clock: a turn of two slow tools
+     * costs the slower of them, not their sum. The overlap lives inside the tool
+     * Cmds' own handlers and NOT in the kernel — `runInterpret` still interprets
+     * a transition's Cmds one after another and never interleaves two handlers,
+     * which is ADR 0018's ruling and the reason a replay is unaffected. Settle
+     * Msgs fold in Cmd-EMISSION order whichever call finishes first, so raising
+     * the knob changes the turn's latency and nothing about its Model.
+     *
+     * Omit (or `1`) → serial dispatch, exactly as before.
+     */
+    readonly toolConcurrency?: number;
+}
+/**
+ * The lid's compaction budget: the two numbers that say when a transcript is
+ * too long and how much of it survives the fold. Both are plain counts, so the
+ * trigger they build is PURE — a replay re-decides identically, and no clock or
+ * token estimate enters the Model (ADR 0004).
+ *
+ * This is deliberately a threshold rather than the core's `planCompaction`
+ * function: a policy function is a second place a lid agent would have to learn
+ * the conversation shape, and the lid hides wiring, never state (ADR 0015). A
+ * run that needs its own heuristic descends to `createAgent`, whose
+ * `CompactionPolicy` this is built from.
+ */
+interface DefineAgentCompaction {
+    /**
+     * Fold once the conversation holds at least this many turns, counted BEFORE
+     * the brain call about to fire. Must be at least `1`.
+     */
+    readonly afterTurns: number;
+    /**
+     * How many of the NEWEST turns survive the fold intact, beside the summary.
+     * Everything older becomes the summary's one synthetic head turn. Omit → `0`:
+     * the whole transcript folds into the summary.
+     *
+     * A fold worth fewer than two turns is skipped by the agent itself — one turn
+     * replaced by one summary shrinks nothing — so `keepTurns` within one of
+     * `afterTurns` is a policy that never fires.
+     */
+    readonly keepTurns?: number;
+}
+/**
+ * Which call an `onToolError` failure belongs to: the model's `callId` — the
+ * fan-out identity the outcome folds back on — and the tool `name` the model
+ * asked for, which for an `unknown_tool` is the name it invented rather than
+ * any declared tool.
+ */
+interface ToolErrorContext {
+    readonly callId: string;
+    readonly name: string;
+}
+/**
+ * One lifecycle event a defined agent's run emits — {@link AgentEvent} with the
+ * tool results typed against this agent's own tool set.
+ */
+type DefinedAgentEvent<T extends AnyToolDef> = AgentEvent<ToolResult<T>>;
+/**
+ * Host wiring for one `run`: the store, the ctx the tools need, a runId, a clock.
+ *
+ * `ctx` is `ScopedCtxArg`, the same widening `run` itself takes: an agent's tools
+ * are exactly the handlers a scoped resource is for, so a `provide({ … })` graph
+ * is accepted here in place of the object and gets the same acquire-at-boot /
+ * release-at-terminal lifetime.
+ */
+type DefinedAgentRunOptions<T extends AnyToolDef> = ScopedCtxArg<DefinedAgentCtx<T>> & {
+    readonly store?: Store<DefinedAgentState<T>>;
+    /** The run's identity. Omit → a fresh UUID. */
+    readonly runId?: string;
+    /** The clock that stamps `at`. Omit → `Date.now`. */
+    readonly clock?: () => number;
+    /**
+     * Observe the run's turn-level lifecycle events — `TurnSettled`,
+     * `ToolSettled`, `RunDone` — in the order the kernel settles them. This is
+     * the progress seam: without it the only way to see anything mid-run is
+     * `machine(input)` plus the raw kernel loop.
+     *
+     * It forwards the runtime's existing semantic stream (`agentEvents()` /
+     * `runtime.on`); it mints no vocabulary of its own, so a consumer folds the
+     * same {@link AgentEvent}s a hand-wired `run` would.
+     *
+     * The listener is CONTAINED: a throw is caught and warned, never allowed to
+     * take the run down, and never observable in `run`'s resolution. Only
+     * transitions applied by THIS process project events, so a store-backed
+     * resume replays nothing that settled before the boot.
+     *
+     * Omit → no projector is wired and the run behaves exactly as before.
+     */
+    readonly onEvent?: (event: DefinedAgentEvent<T>) => void;
+    /**
+     * Observe the token deltas of the turn being produced right now — the
+     * granularity below `onEvent`'s. Wired only when the configured `model` is
+     * the streaming shape (`async (messages, { onChunk }) => turn`); a plain
+     * model has no deltas to give, so passing this beside one is silent.
+     *
+     * Chunks ride a SIDE CHANNEL, never state. They are not projected off
+     * transitions like an {@link AgentEvent} is, because nothing about a chunk is
+     * a transition: it is never journaled, never written to the `Store`, and
+     * never folded into the Model. That is the whole rule this option obeys — a
+     * delta that has not settled is not an outcome, so a run that dies mid-turn
+     * loses its chunks and resumes from the last SETTLED turn, and a resumed run
+     * re-emits nothing it did not itself re-produce.
+     *
+     * The listener is CONTAINED exactly as `onEvent`'s is: a throw is caught and
+     * warned, never allowed to fail the model call it fired from.
+     *
+     * Omit → the streaming model is still invoked in its streaming shape, with a
+     * sink that drops every chunk.
+     */
+    readonly onChunk?: (chunk: TurnChunk) => void;
+    /**
+     * Stop the run from outside — the stop button's seam. On abort the run settles
+     * on a CANCELLED terminal Model and `run` RESOLVES with it; it does not reject,
+     * and no `DriveFailedError` is thrown. Read the outcome with `status(state)`,
+     * which answers `{ kind: "cancelled", at }` — distinct from `failed`, because a
+     * run someone stopped did not fail.
+     *
+     * The outcome is durable, so it is also the answer on the next boot: a process
+     * killed after an abort resumes reading a run that ENDED, not one to restart.
+     * A signal already aborted when `run` is called ends it before the first model
+     * call is made.
+     *
+     * It stops DISPATCH, not the work already in flight — a promise cannot be
+     * cancelled, so a tool handler mid-call runs to its own end. Those late results
+     * reach no `onEvent`, no `onToolError` and no Model, and they do not hold the
+     * runtime's teardown. Propagating the signal INTO handlers is a separate seam
+     * this option does not open.
+     *
+     * Omit → the run has no stop button and every path behaves exactly as before.
+     */
+    readonly signal?: AbortSignal;
+};
+/**
+ * One decorator per interpret cell you name: it receives the cell the agent
+ * wired (`next`) and returns the cell that runs in its place. Every key is
+ * optional and a cell nobody names is passed through by REFERENCE, so an
+ * overlay that wraps one tool leaves the others the exact functions
+ * `defineAgent` built.
+ *
+ * The wrapper's signature is the cell's, so calling `next(cmd, ctx, dispatch)`
+ * is how the wrapped work happens — that is the typed Cmd→Msg edge
+ * (`Cmd.define`'s `_ok` / `_err` Msgs), and returning its Msg is what keeps the
+ * fold, and therefore a replay, identical to the unwrapped run's.
+ */
+type InterpretOverlay<T extends AnyToolDef> = CellWrappers<DefinedAgentInterpret<T>>;
+/**
+ * The decorator table over an interpret table `I`. Written over a bare type
+ * parameter because `I[K]` is only indexable when `I` is one: applying the
+ * mapped type to `DefinedAgentInterpret<T>` inline leaves TypeScript indexing
+ * an unreduced generic mapped type, which it refuses.
+ */
+type CellWrappers<I> = {
+    readonly [K in keyof I]?: (next: I[K]) => I[K];
+};
+/**
+ * What `defineAgent(cfg).with(...)` takes — the one documented wrap point over
+ * the machine the lid built.
+ */
+interface DefinedAgentOverlay<T extends AnyToolDef> {
+    readonly interpret: InterpretOverlay<T>;
+}
+/** What `defineAgent` returns. */
+interface DefinedAgent<T extends AnyToolDef> {
+    /**
+     * Run `input` to its terminal Model. Resolves on `run.phase: "done"`; a
+     * failed run rejects with `DriveFailedError` carrying the failed Model.
+     *
+     * With a `store`, the same call is also the resume: a Model the Store hands
+     * back mid-run is booted (`agent_boot`) at its one outstanding effect —
+     * same `runId`, no tool re-run — and one already `done` resolves as it is.
+     * A fresh start needs an empty Store.
+     *
+     * It resolves with {@link DefinedAgentResolvedState} — the Model whose `run`
+     * slice is narrowed to the ENDED phases, so `(await agent.run(i)).run.runId`
+     * reads without a guard against an `idle` arm this promise cannot produce.
+     */
+    readonly run: (input: string, ...opts: [Record<never, never>] extends [DefinedAgentCtx<T>] ? [opts?: DefinedAgentRunOptions<T>] : [opts: DefinedAgentRunOptions<T>]) => Promise<DefinedAgentResolvedState<T>>;
+    /** The machine `run` drives for `input` — the door down to the raw kernel. */
+    readonly machine: (input: string) => DefinedAgentMachine<T>;
+    /**
+     * The ramp between the lid and `createAgent`: wrap ONE interpret cell of the
+     * machine this agent builds and get back a NEW defined agent that runs the
+     * wrapped table. The agent it is called on is untouched, and so is every cell
+     * the overlay does not name.
+     *
+     *     const traced = agent.with({
+     *       interpret: {
+     *         fetch_rate: (next) => async (cmd, ctx, dispatch) => {
+     *           console.time(cmd.callId);
+     *           try { return await next(cmd, ctx, dispatch); }
+     *           finally { console.timeEnd(cmd.callId); }
+     *         },
+     *       },
+     *     });
+     *
+     * The wrapped cell settles through the SAME typed Cmd→Msg edge as the cell it
+     * wraps — it returns whatever `next` returned — so the reducer folds the same
+     * Msgs and a replay of a wrapped run is the unwrapped run's replay. That is
+     * the whole contract: the door is one over the effect boundary, never over
+     * the fold. A cell that must settle DIFFERENTLY is a different machine, and
+     * `createAgent` is still where you build one.
+     *
+     * `with` composes — `agent.with(a).with(b)` puts `b`'s wrapper OUTSIDE `a`'s,
+     * so `b` is entered first and `a`'s cell is what its `next` calls. Naming a
+     * cell the machine has none of throws at `machine(input)`, where the table it
+     * is checked against exists.
+     */
+    readonly with: (overlay: DefinedAgentOverlay<T>) => DefinedAgent<T>;
+}
+/**
+ * Define an agent from a model, the tools it may call and its instructions, and
+ * get back `run(input)` — a promise of the finished state — plus `machine(input)`
+ * for driving the same run yourself, which is the entry point a newcomer picks,
+ * `createAgent` being the layer underneath that you drop to only to walk a stage
+ * pipeline of your own.
+ *
+ * Add `maxTurns`, `deadlineMs`, `maxElapsedMs` or `stopWhen` to bound the run;
+ * all four are described on `DefineAgentConfig`. The run's `input` is its single stage, so it is durable
+ * beside `instructions`, and the prompt is rendered from those two and the
+ * conversation on every model call.
+ *
+ * One unusual requirement does not cost you the lid: `.with({ interpret })`
+ * wraps one interpret cell of the machine this built and hands back another
+ * defined agent, so `createAgent` is for a rebuild rather than for a detour.
+ */
+declare function defineAgent<T extends AnyToolDef>(config: DefineAgentConfig<T>): DefinedAgent<T>;
+/** The prompt as messages: the head, then each turn with its tool outcomes. PURE. */
+declare function renderPrompt(prompt: AgentPrompt<unknown>): AgentMessage[];
+
+/**
+ * @packageDocumentation
+ * The transcript collector — the built-in way to KEEP a run's turns, given that
+ * a finished run's Model does not.
+ *
+ * A run that reaches `phase: "done"` clears `conversation` to `null` on
+ * purpose: the terminating turn is stamped onto `output` first, so the answer
+ * survives, and the history that would otherwise grow without bound in storage
+ * kept for its state is dropped (`docs/explanation/durability-model.md`). That
+ * policy is not what this module changes. What it changes is that every
+ * consumer wanting the history had to hand-write the same fold over `onEvent`.
+ *
+ * So this is a COLLECTOR over the event stream that already exists, not a knob
+ * on the Model. Nothing here is durable, nothing here is written to a `Store`,
+ * and a run with a collector attached is byte for byte the run it was without
+ * one — the same reason `onChunk` rides a side channel rather than state.
+ *
+ *   const t = transcript<ToolResult<typeof tools>>();
+ *   const final = await agent.run(input, { store, onEvent: t.onEvent });
+ *   t.read().turns; // every turn this process settled
+ *
+ * ## What a resume needs from you
+ *
+ * Events are projected off the transitions THIS process applies, so a run
+ * resumed from a `Store` re-emits nothing the killed process already settled.
+ * A collector that only ever listened would therefore hold the tail of a
+ * resumed run and call it the whole thing. Hence the seed: hand
+ * {@link transcript} the Model the `Store` handed back and it starts from that
+ * Model's live conversation, so the resumed collector reads as the whole run
+ * rather than its last leg.
+ */
+
+/**
+ * One tool call the run settled OK, as the transcript keeps it — the `callId`
+ * and the result, which is exactly what the `ToolSettled` event carries.
+ *
+ * A tool that FAILED is absent, and that is the event stream's shape rather
+ * than a choice made here: `ToolSettled` is projected off the OK settle alone.
+ * Branch on failures through `onToolError`, whose argument is typed per tag.
+ */
+interface TranscriptToolResult<R> {
+    readonly callId: string;
+    readonly result: R;
+}
+/**
+ * Whether the run has finished, and its terminal turn once it has.
+ *
+ * The two cases are a union rather than a nullable `output` field because
+ * `output` is legitimately `null` on a finished run — a `RunDone` with no
+ * terminating turn — and a single field would make "not finished yet" and
+ * "finished with nothing" the same reading.
+ */
+type TranscriptOutcome = {
+    readonly kind: "running";
+} | {
+    readonly kind: "done";
+    readonly output: AgentTurn | null;
+};
+/** What a collector holds right now — a plain, immutable read. */
+interface TranscriptSnapshot<R> {
+    /** Every model turn the transcript holds, in order. */
+    readonly turns: readonly AgentTurn[];
+    /** Every tool call that settled OK, in settle order. */
+    readonly tools: readonly TranscriptToolResult<R>[];
+    /** Whether `RunDone` has been seen, and the terminal turn if so. */
+    readonly outcome: TranscriptOutcome;
+}
+/**
+ * The Model a resumed collector starts from — structural on purpose, so any
+ * agent state (`DefinedAgentState<T>`, `AgentState<…>`) satisfies it without
+ * this module importing the lid, and a bare `{ conversation }` object works in
+ * a test.
+ */
+interface TranscriptSeed<R> {
+    readonly conversation: Conversation<R> | null;
+}
+/**
+ * A live transcript: the listener you wire, and the read you take off it.
+ *
+ * `onEvent` is a bound function, so `{ onEvent: t.onEvent }` is the whole
+ * wiring — there is no `this` to lose.
+ */
+interface Transcript<R> {
+    /** Wire this to `run`'s `onEvent`. */
+    readonly onEvent: (event: AgentEvent<R>) => void;
+    /** The transcript as of now. Each call returns a fresh immutable snapshot. */
+    readonly read: () => TranscriptSnapshot<R>;
+}
+/**
+ * Open a transcript collector over an agent run's event stream.
+ *
+ * Wire `onEvent` to `run`'s `onEvent` option and `read()` gives you the turns
+ * and settled tool results afterwards — the transcript the finished Model no
+ * longer carries.
+ *
+ * Pass `seed` when the run is a RESUME: the Model the `Store` handed back still
+ * holds the live conversation the killed process built, and seeding from it is
+ * what makes the collector hold the whole run rather than the leg this process
+ * ran. One collector per process is the honest unit; a fresh run needs no seed.
+ *
+ * A seed taken from an already-finished Model contributes nothing, and
+ * correctly so: that Model's `conversation` is `null` and its answer is its
+ * `output`, which you already hold.
+ */
+declare function transcript<R>(seed?: TranscriptSeed<R>): Transcript<R>;
 
 /**
  * @packageDocumentation
@@ -25,16 +609,15 @@ import '../snapshot/index.js';
  * drives the classic loop `llm → tools → fold → llm` until the model stops
  * asking for tools.
  *
- * This is the `seed/audit-agent-machine` reducer generalized: the seed's audit /
- * glyph / violation domain specifics are stripped, and what remains — the loop,
- * the durability, the boot-reconcile crash recovery, the serial-vs-fanned tool
- * dispatch — is yours. The consumer supplies the only things that are genuinely
- * domain: the tools, the prompts (via the llm-call message loader), the schemas,
- * and the model. `createAgent(config)` returns the uniform knob contract every
+ * This generalizes a production audit agent: the domain specifics are stripped,
+ * and what remains — the loop, the durability, the boot-reconcile crash
+ * recovery, the serial-vs-fanned tool dispatch — is yours. The consumer
+ * supplies the only things that are genuinely domain: the tools, the prompts
+ * (via the llm-call message loader), the schemas, and the model. `createAgent(config)` returns the uniform handle contract every
  * composition exposes (`init` / verbs returning `readonly [State, Cmd[]]` /
  * `subs`) AND a ready-to-`run` `defineMachine` (`toMachine`) — THE one wired
  * path. (`unsafeDetachedHandlers` is the hand-wiring escape hatch; its name
- * advertises that it does not drive the retry loop — see #54.)
+ * advertises that it does not drive the retry loop.)
  *
  * ## The composition (three siblings wired into ONE machine)
  *
@@ -43,18 +626,21 @@ import '../snapshot/index.js';
  *     position survives eviction, the no-progress deadline auto-fails a wedged
  *     run, and `boot` resumes mid-pipeline. The agent slice OWNS this slice and
  *     delegates `start` / `advance` / `progress` / `onDeadline` / `boot` to it.
- *   - `../llm-call` — every brain call (the seed's `call_llm{purpose}`). One
+ *   - `../llm-call` — every brain call. One
  *     `LlmCall` per turn, structured-output parsed, retry composed in. The agent
  *     delegates the resilient slice + verbs and reuses the detached handler.
- *   - `../fan-out` — the tool calls a turn produced. The seed dispatched tools
- *     SERIALLY (concurrency 1); fan-out generalizes that to bounded concurrency
- *     `config.toolConcurrency` (default 1 = the seed's serial behavior). Each
+ *   - `../fan-out` — the tool calls a turn produced. Tools dispatch SERIALLY by
+ *     default (concurrency 1); fan-out generalizes that to a bounded number
+ *     LAUNCHED per transition, `config.toolConcurrency`. Above `1` a router's
+ *     tool cells overlap on the clock while `runInterpret` stays serial — the
+ *     fan-out is inside the Cmd handler, and its settles fold in emission
+ *     order (ADR 0018). Each
  *     tool is an `of(call)` Cmd the consumer's own interpret performs; results
  *     route back through `toolOk` / `toolErr`. When the batch drains, the agent
  *     folds the gathered results back into the conversation and fires the next
  *     brain call (`fold → llm`).
  *
- * ## The flow loop, as TEA (generalized from the seed's `applyAiTurn`)
+ * ## The flow loop, as TEA
  *
  *   1. `start` enters the pipeline; the consumer wires the per-stage outstanding
  *      effect (often a `call_llm` for the agentic stage) off the current stage.
@@ -68,10 +654,12 @@ import '../snapshot/index.js';
  *      queued tool. When the batch drains, fold the gathered outcomes into the
  *      conversation, bump the turn count (livelock guard), and fire the next
  *      brain call — `awaiting` flips back to `llm`.
- *   4. The watchdog + turn-limit guard bound the loop; the deadline fires
- *      `failed`, the turn limit fires `failed { turn_limit }`.
+ *   4. The watchdog bounds a stall and the turn boundary's own stop conditions
+ *      bound the loop: the deadline fires `failed`, the turn limit fires
+ *      `failed { turn_limit }`, the wall-clock cap `failed { elapsed_limit }`,
+ *      and the consumer's `stopWhen` settles the run `cancelled`.
  *
- * ## Boot reconcile (crash recovery — the seed's `outstandingEffect`)
+ * ## Boot reconcile (crash recovery)
  *
  * Cold wake re-derives the ONE outstanding effect from `phase × awaiting`: a
  * brain call in flight re-fires `call_llm`; tools in flight re-fire the in-flight
@@ -98,11 +686,13 @@ import '../snapshot/index.js';
  *   type RunTool = { readonly type: "run_tool" } & ToolCall;
  *   const agent = createAgent<Stage, Purpose, Outputs, Result, RunTool, Msg>({
  *     stages: ["plan", "act", "report"],
- *     model: (id) => createChatModel(env, id),
+ *     // The brain: a plain `async (messages) => turn` (the common path), or the
+ *     // `(id) => Llm` factory when the model binds the schema itself.
+ *     model: async (messages) => client.chat(messages),
  *     schemas: { plan: planSchema, act: turnSchema, report: reportSchema },
  *     turnOf: (stage) => stageToPurpose[stage],   // which brain call a stage runs
  *     toolOf: (call): RunTool => ({ type: "run_tool", ...call }),
- *     toolConcurrency: 1,                          // serial like the seed (default)
+ *     toolConcurrency: 1,                          // launched per transition
  *     deadlineMs: 10 * 60_000,
  *     maxTurns: 60,
  *     retry: defaultRetryPolicy,
@@ -115,21 +705,24 @@ import '../snapshot/index.js';
  */
 
 /**
- * Build an agent knob from `config`. The determinism seam — `config.rng`,
- * injected for the inherited brain-call retry jitter — lives as a named field
- * on the config (pass a fixed `() => 0` to pin backoff in tests; omit → defaults
- * to `Math.random`, read only at the resilient-call verb boundary).
+ * Assemble an agent from `config` — the model, the stages it walks, and how a
+ * tool call is turned into a command — and get back its `init`, verbs and `subs`
+ * plus a `toMachine()` that wires all of it into one machine you hand to `run`,
+ * which is the layer to reach for only once `defineAgent` cannot express the run
+ * you want — a newcomer starts there, not here.
  *
- * Returns the uniform knob contract (`init` / verbs / `subs`) plus `toMachine()`
- * — a `defineMachine` wiring all of it into one runnable machine — and the
- * `unsafeDetachedHandlers` hand-wiring escape hatch.
+ * Pass `snapshotEvery` to have the run persist itself every N steps, and
+ * `compaction` to have long conversations summarized as they grow; each one you
+ * pass obliges you to supply the matching handler at `toMachine`, and each one
+ * you omit forbids it. `rng` is the determinism seam for the retry backoff —
+ * pass a fixed `() => 0` to pin it in tests; omit for `Math.random`.
+ * `unsafeDetachedHandlers` is the hand-wiring escape hatch.
  *
- * `createAgent` is OVERLOADED on TWO independent discriminants — the snapshotting
- * (#55) and the compaction (#85) one — so each `toMachine` obligation is derived
+ * The four overloads exist because the two obligations are derived
  * from the `config` VALUE, never inferred. `{ snapshotEvery: number }` REQUIRES
  * the `snapshot_write` cell, `{ snapshotEvery?: never }` FORBIDS it; `{ compaction:
  * policy }` REQUIRES the `compact_run` cell, `{ compaction?: never }` FORBIDS it.
- * The four overloads enumerate the snapshot × compaction grid: overload resolution
+ * They enumerate the snapshot × compaction grid: overload resolution
  * reads the two fields off `config`, so the right `Snap`/`Compact` pair is fixed
  * even when the call site passes explicit type arguments (TS does not infer
  * trailing type params — a `Cfg`-inference scheme would silently fall back to OFF
@@ -152,4 +745,4 @@ declare function createAgent<Stage, P extends string, O extends Record<P, AgentT
     readonly compaction?: never;
 }): AgentKnob<Stage, P, O, R, TC, false, false>;
 
-export { AgentConfigCore, AgentKnob, AgentTurn, CompactionPolicy, createAgent };
+export { AgentCmd, AgentConfigCore, AgentEvent, AgentKnob, AgentMachineMsg, type AgentMessage, type AgentPrompt, AgentState, AgentTurn, AnyToolDef, CompactionPolicy, Conversation, DeadlineSub, type DefineAgentCompaction, type DefineAgentConfig, type DefinedAgent, type DefinedAgentCmd, type DefinedAgentCtx, type DefinedAgentEvent, type DefinedAgentInterpret, type DefinedAgentMachine, type DefinedAgentModel, type DefinedAgentMsg, type DefinedAgentOverlay, type DefinedAgentResolvedState, type DefinedAgentRunOptions, type DefinedAgentState, EndedRun, type InterpretOverlay, type LidPurpose, PlainModel, StreamingModel, ToolCall, ToolCmd, type ToolErrorContext, ToolFailureOf, ToolOutcome, ToolResult, type Transcript, type TranscriptOutcome, type TranscriptSeed, type TranscriptSnapshot, type TranscriptToolResult, TurnChunk, WiredToolMsg, createAgent, defineAgent, renderPrompt, transcript };