@demlik/tea 0.2.0 → 0.4.0

package/dist/machine-B_BF4jij.d.ts

@@ -0,0 +1,804 @@
+import { C as Cmd, c as Interpret, M as Machine } from './core-42kapW0n.js';
+import { LlmCall, LlmOk, ModelFactory, Schema, MessageLoader, LlmErr, LlmSucceedMsg, LlmFailMsg, LlmTimerMsg, LlmRunCmd, LlmCallPorts } from './llm-call/index.js';
+import { MonitoredRunState, RunFailure, MonitoredRunCmd } from './monitored-run/index.js';
+import { M as MsgType } from './protocol-B5YmJr0d.js';
+import { FanOutState } from './fan-out/index.js';
+import { RetryPolicy } from './retry-backoff/index.js';
+import { ResilientState } from './resilient-call/index.js';
+import { DeadlineSub } from './deadline/index.js';
+
+/**
+ * @demlik/tea/agent — the domain data model: the tool + turn shapes the consumer
+ * supplies, the agentic-stage conversation, the `createAgent` config knob, and
+ * the durable agent slice + its lifecycle status.
+ *
+ * Everything here is plain data (durable + replayable): the composed bricks'
+ * slices, the conversation, and the config are all JSON-serializable. The
+ * compaction (#85) vocabulary lives in `./compaction`; this module imports its
+ * types where the slice / config reference them. The reducer core (the verbs +
+ * the wired `toMachine`) lives in `./index`.
+ */
+
+/**
+ * One tool the model asked to call this turn — the seed's `ToolCall`, stripped
+ * of the audit-specific args typing. Plain data so it round-trips through the
+ * durable fan-out ledger: a stable `callId` (the fan-out identity), the tool
+ * `name`, and the opaque `args` the consumer's own interpret reads.
+ */
+interface ToolCall {
+    /** Stable id the model minted; the fan-out item identity (`idOf`). */
+    readonly callId: string;
+    /** The tool to invoke. The consumer's `toolOf` maps it to an effect Cmd. */
+    readonly name: string;
+    /** Args the model emitted, opaque to the agent. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * One model turn — the seed's `AiTurn`, generalized: the narration `content`
+ * the model produced and the `toolCalls` it asked us to run. An empty
+ * `toolCalls` means the model is done with this stage (advance the pipeline).
+ * This is the parsed output of a brain call; the consumer's schema produces it.
+ */
+interface AgentTurn {
+    /** Free-text narration the model produced this turn (folded into the conversation). */
+    readonly content: string;
+    /** The tools the model asked us to run; empty = stage done. */
+    readonly toolCalls: readonly ToolCall[];
+}
+/**
+ * Narrow an unknown to an `AgentTurn` — the runtime witness for tea's own
+ * structured-output type. A consumer's brain schema parses the model's output
+ * into an `AgentTurn` (the agentic purpose's output); rather than every consumer
+ * hand-rolling this guard + a `Schema<AgentTurn>` for a type the agent OWNS, the
+ * agent exports both. Checks the load-bearing fields: `content` is a string and
+ * `toolCalls` is an array of `ToolCall` (each element guarded — the narrow is a
+ * real parse of the boundary, not a shallow `Array.isArray`). PURE — allocates
+ * no Error.
+ */
+declare function isAgentTurn(value: unknown): value is AgentTurn;
+/**
+ * The `Schema<AgentTurn>` for tea's own turn type — the parse target a brain
+ * call binds when the agentic purpose's output is a bare `AgentTurn` (the common
+ * case). Throws on a non-`AgentTurn` (the zod-style `parse` contract the
+ * llm-call handler relies on). Deletes the consumer's hand-rolled
+ * `auditSchema` / `isAgentTurn` pair.
+ *
+ * A consumer whose turn type EXTENDS `AgentTurn` with extra fields still writes
+ * its own schema (it must validate the extra fields); this is for the plain case.
+ */
+declare const agentTurnSchema: Schema<AgentTurn>;
+/**
+ * One settled tool outcome the consumer routes back into the loop — the seed's
+ * `ToolOutcome`. `ok` carries the result the consumer's interpret produced;
+ * `error` carries a reason the model sees (so it recovers rather than stalls —
+ * "errors are data").
+ */
+type ToolOutcome<R> = {
+    readonly kind: "ok";
+    readonly result: R;
+} | {
+    readonly kind: "error";
+    readonly reason: string;
+};
+/**
+ * A folded tool record kept on the conversation once a tool settles — the
+ * call + its outcome, in settle order. The consumer's message loader reads
+ * these (plus `turns`) to assemble the next brain call's prompt.
+ *
+ * `turn` is the `turnCount` at the time the record was folded — the association
+ * compaction needs to drop the RIGHT records (#85 / design A1). When compaction
+ * folds `turns[0..N]` into a summary, it must also drop every tool record that
+ * belonged to those turns; without a turn stamp on the record there is no honest
+ * way to know which. It is the round-trip index, not a wall clock — small and
+ * JSON-stable, preserving the durability invariant.
+ */
+interface ToolRecord<R> {
+    readonly call: ToolCall;
+    readonly outcome: ToolOutcome<R>;
+    /** The `turnCount` at fold time — which round-trip this record belongs to (#85, A1). */
+    readonly turn: number;
+}
+/**
+ * Whether the agentic stage is waiting on the model (`llm`), on tools
+ * (`tools`), or on a compaction round-trip (`compacting`, #85). The in-flight
+ * fan-out batch exists ONLY in the `tools` variant — "awaiting llm with tools
+ * pending" is structurally impossible (the seed's canon §2.6 / Rule 1
+ * impossible-states pin). Discriminated on `kind`.
+ *
+ * `compacting` is the honest state for the dedicated compaction round-trip
+ * (design B1): the transcript grew, the policy asked to fold `folding` of the
+ * OLDEST turns, and the summarize call is in flight INSTEAD of the next brain
+ * call. `folding` is the count `planCompaction` returned — the fold-back
+ * (`compact_ok`) drops exactly that many head turns + their tool records.
+ */
+type Awaiting = {
+    readonly kind: "llm";
+} | {
+    readonly kind: "tools";
+    readonly batchTurn: number;
+} | {
+    readonly kind: "compacting";
+    readonly folding: number;
+};
+/**
+ * The agentic-stage conversation — durable inside the agent slice so an
+ * eviction mid-loop resumes the exact turn. The model turns + folded tool
+ * records are the consumer's prompt source (via the llm-call message loader);
+ * `turnCount` drives the livelock guard; `awaiting` carries the ONE outstanding
+ * effect for the agentic stage.
+ *
+ * Generic over the consumer's tool-result type `R` (what `toolOk` carries).
+ */
+interface Conversation<R> {
+    /** Model turns this stage has produced, in order. */
+    readonly turns: readonly AgentTurn[];
+    /** Settled tool records, in settle order — the model sees these next turn. */
+    readonly toolRecords: readonly ToolRecord<R>[];
+    /** Monotonic round-trip count; the livelock guard compares it to `maxTurns`. */
+    readonly turnCount: number;
+    /** What the loop is waiting for next. */
+    readonly awaiting: Awaiting;
+}
+/**
+ * The snapshotting discriminant (#55). Checkpointing is either OFF — in which
+ * case `snapshotEvery` is structurally absent and the monitored-run slice never
+ * emits a `snapshot_write` Cmd — or ON, in which case `snapshotEvery` is a
+ * `number`. A `{ snapshotEvery?: never }` member (rather than a bare optional)
+ * makes the OFF case load-bearing: it forbids passing `snapshotEvery` at all, so
+ * `toMachine` can config-derive whether the `snapshot_write` interpret cell is
+ * REQUIRED (ON) or FORBIDDEN (OFF) instead of defaulting it to a silent no-op.
+ *
+ * This is what kills the type lie: with checkpointing off, `snapshot_write` is
+ * absent from the consumer's interpret contract entirely — never a
+ * `snapshot_write: async () => undefined` ceremony that masks a real wiring bug.
+ */
+type AgentSnapshotConfig = {
+    readonly snapshotEvery?: never;
+} | {
+    readonly snapshotEvery: number;
+};
+/**
+ * The core (non-snapshot, non-compaction) agent knob. The full `AgentConfig`
+ * intersects this with the `AgentSnapshotConfig` + `AgentCompactionConfig`
+ * discriminants — see those types for why the cadence / policy are discriminated
+ * unions rather than bare optionals.
+ *
+ * Type parameters:
+ *   - `Stage`   — the consumer's pipeline stage id (any JSON value).
+ *   - `P`       — the brain-call purpose union (`"plan" | "act" | ...`).
+ *   - `O`       — the purpose→output map. Every purpose drives the agentic loop,
+ *                 so each output is pinned to `AgentTurn` (or a subtype) by the
+ *                 `O extends Record<P, AgentTurn>` bound — that is what the loop
+ *                 folds. An `Outputs` whose purpose output is NOT an `AgentTurn`
+ *                 fails to compile here; the rule lives in the type, not a cast.
+ *   - `R`       — the consumer's tool-result type (what `toolOk` carries).
+ *   - `TC`      — the consumer's per-tool effect Cmd, the discriminated variant
+ *                 `toolOf` produces. Kept PRECISE (a closed Cmd variant, not the
+ *                 open `Cmd`) so `AgentCmd<P, TC>` stays a closed discriminated
+ *                 union and the wired machine's interpret merge type-checks per
+ *                 key — the brain cell maps to `resilient_run`, the tool cell to
+ *                 `TC["type"]` — with no laundering cast. Defaults to `Cmd` for
+ *                 the consumer that does not care to name its tool Cmd.
+ *   - `Msg`     — the model's message shape (threaded through the llm-call loader).
+ */
+interface AgentConfigCore<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd = Cmd, Msg = unknown> {
+    /** The ordered stages. Omit / empty → a single-shot run (one agentic stage). */
+    readonly stages?: readonly Stage[];
+    /** No-progress watchdog budget, in ms. Omit → no watchdog. */
+    readonly deadlineMs?: number;
+    /** DI port — the model factory `(modelId) => Llm`. */
+    readonly model: ModelFactory<Msg>;
+    /** One structured-output schema per purpose; the parse target per brain call. */
+    readonly schemas: {
+        readonly [K in P]: Schema<O[K]>;
+    };
+    /** Backoff policy for brain calls, composed into `../llm-call`. Omit → no backoff. */
+    readonly retry?: RetryPolicy;
+    /** DI port — the SDK / message loader. Omit → brain calls invoke with `[]`. */
+    readonly loadMessages?: MessageLoader<P, Msg>;
+    /** Map one tool call to the effect Cmd the consumer's interpret performs. */
+    readonly toolOf: (call: ToolCall) => TC;
+    /** Max tools in flight at once. Omit / `1` → serial dispatch (the seed's behavior). */
+    readonly toolConcurrency?: number;
+    /**
+     * Which brain-call purpose a given stage runs. The agent fires
+     * `call_llm{ turnOf(stage) }` to drive the agentic stage's loop. The purpose's
+     * schema output is an `AgentTurn` — enforced by the `O extends Record<P,
+     * AgentTurn>` bound, not left to a doc-comment.
+     */
+    readonly turnOf: (stage: Stage | undefined) => P;
+    /** Build the per-purpose brain-call payload from the conversation. Omit → `null`. */
+    readonly payloadOf?: (stage: Stage | undefined, conversation: Conversation<R>) => unknown;
+    /** The model id every brain call invokes. Omit → `null` (the host's default). */
+    readonly modelId?: string | null;
+    /**
+     * Livelock guard: bound on model round-trips within one run. On
+     * `turnCount >= maxTurns` the run fails `{ reason: "turn_limit" }`. Omit → no
+     * turn guard (only the deadline watchdog bounds the loop).
+     */
+    readonly maxTurns?: number;
+    /**
+     * The impurity-injection seam for the inherited brain-call retry jitter — the
+     * ONE place this otherwise-pure machine reads randomness. Pass a fixed
+     * `() => 0` to pin backoff (tests, replay, durability proofs). Omit →
+     * `Math.random`, read only at the resilient-call verb boundary.
+     */
+    readonly rng?: () => number;
+}
+/**
+ * The agent knob — the core seams intersected with the snapshotting discriminant
+ * (`AgentSnapshotConfig`). Type parameters are documented on `AgentConfigCore`;
+ * the only addition here is that `snapshotEvery` is the discriminant that drives
+ * whether `toMachine` requires (or forbids) the `snapshot_write` interpret cell.
+ */
+type AgentConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd = Cmd, Msg = unknown> = AgentConfigCore<Stage, P, O, R, TC, Msg> & AgentSnapshotConfig & AgentCompactionConfig<R, Msg>;
+/**
+ * Why a run terminated as `failed`, beyond monitored-run's own reasons. The
+ * `turn_limit` reason is the agent's livelock guard; deadline / stage failures
+ * surface through the monitored-run slice's own `failure`.
+ */
+type AgentFailure = {
+    readonly reason: "turn_limit";
+    readonly at: number;
+} | {
+    readonly reason: "llm";
+    readonly error: unknown;
+    readonly at: number;
+};
+/**
+ * The agent slice — every composed brick's slice plus the loop's conversation
+ * and the agent-specific failure annotation.
+ *
+ *   - `run`          — the `../monitored-run` slice (pipeline position +
+ *                      lifecycle + watchdog). The OUTER lifecycle truth.
+ *   - `resilience`   — the `../llm-call` (= resilient-call) slice (brain-call
+ *                      retry / backoff). Per-purpose retry lives here.
+ *   - `tools`        — the `../fan-out` ledger for the current turn's tools.
+ *   - `conversation` — the agentic-stage loop state. `null` until the loop is
+ *                      entered (the consumer seeds it at the agentic stage).
+ *   - `failure`      — the agent-specific terminal annotation (turn-limit /
+ *                      llm), null otherwise. Distinct from `run.failure`.
+ */
+interface AgentState<Stage, P extends string, O extends Record<P, unknown>, R> {
+    readonly run: MonitoredRunState<Stage>;
+    readonly resilience: ResilientState<LlmCall<P>, LlmOk<P, O>>;
+    readonly tools: FanOutState<ToolCall, ToolOutcome<R>>;
+    readonly conversation: Conversation<R> | null;
+    /**
+     * The compaction round-trip's resilient slice (#85, design B1) — a DEDICATED
+     * resilient-call slice for the reserved `$compact` purpose, separate from the
+     * brain `resilience` slice so a compaction retry/backoff never disturbs the
+     * brain call's breaker or retry counter. Always present (empty `calls` when no
+     * compaction is in flight, or when no policy is configured) so the slice stays
+     * a flat plain-data record — durable + replayable like every composed brick.
+     */
+    readonly compaction: ResilientState<LlmCall<CompactionPurpose>, LlmOk<CompactionPurpose, CompactionOutputs>>;
+    readonly failure: AgentFailure | null;
+    /**
+     * The run's terminal output — the FIRST-CLASS result (issue #46). `null`
+     * until the pipeline finishes; set to the last model turn (the empty-tool
+     * turn that retired the final stage) the instant `run.phase` becomes `"done"`.
+     *
+     * This survives the `conversation` clear on stage retire: clearing the
+     * conversation is correct durability hygiene (a finished stage's transcript
+     * is not live state), but the run's PRODUCT is, so it lives here on the
+     * durable slice rather than being scraped off the `observe` firehose by
+     * matching the private `resilient_ok` Msg and racing the clear (the old
+     * `captureLastTurn` dance this field deletes). A consumer reads
+     * `runtime.result()?.output` / `(await runtime.done()).output`.
+     *
+     * Typed `AgentTurn | null` (not `O[P]`): the run's output is always a model
+     * turn — the `O extends Record<P, AgentTurn>` knob bound pins every purpose's
+     * output to an `AgentTurn`, and the terminating turn is the one with no tool
+     * calls. The wider `Record<P, unknown>` bound on `AgentState` itself does not
+     * constrain `O[P]`, so naming the concrete `AgentTurn` keeps this field's type
+     * total without a purpose-indexing narrow.
+     */
+    readonly output: AgentTurn | null;
+}
+/**
+ * The unified terminal failure (issue #49). The agent terminates `failed`
+ * through TWO independent slice channels:
+ *
+ *   - `state.failure` (`AgentFailure`) — the AGENT'S OWN annotation
+ *     (`turn_limit` livelock guard / `llm` exhausted-retry). Set WITHOUT moving
+ *     `run.phase` (it stays `running`); `isSettled` treats a non-null `failure`
+ *     as terminal regardless of `run.phase`.
+ *   - `state.run.failure` (`RunFailure`) — the monitored-run channel
+ *     (`deadline` watchdog / `stage` failure), present iff `run.phase` is
+ *     `"failed"`.
+ *
+ * Callers used to union these by hand at every status question. `status`
+ * collapses them into ONE `failure`, so a consumer reads `status(s).failure`
+ * without knowing which channel produced it.
+ */
+type AgentTerminalFailure<Stage> = AgentFailure | RunFailure<Stage>;
+/**
+ * The agent's lifecycle status — THE single typed channel for "what is this run
+ * doing?" (issue #49). A discriminated union on `kind` so any change to the
+ * private slice shape (`Awaiting`, the failure channels, `run.phase`) forces a
+ * compile error at the call sites that switch on it, instead of silently
+ * breaking a hand-rolled re-derivation. Make-invalid-states-unrepresentable:
+ *
+ *   - `running`   — live, NOT awaiting tools (a brain call is in flight, or the
+ *                   run is between stages). Not resumable on cold wake by
+ *                   itself — the in-flight brain call re-fires from `boot`.
+ *   - `suspended` — the RESUMABLE case: running + a live conversation +
+ *                   `awaiting.kind === "tools"`. `pending` is the outstanding
+ *                   tool calls (`conversation.awaiting` … the in-flight batch),
+ *                   read off `tools.running`. This is exactly the shape
+ *                   `agentIsResumable` re-derived by hand.
+ *   - `done`      — the pipeline finished; `output` is the terminal model turn
+ *                   stamped on `state.output` (issue #46), `null` if the run
+ *                   produced no turn.
+ *   - `failed`    — terminal failure; `failure` is the UNIFIED channel
+ *                   (`AgentTerminalFailure`), absorbing the `state.failure` vs
+ *                   `state.run.failure` dual channel so callers stop unioning.
+ */
+type AgentStatus<Stage> = {
+    readonly kind: "running";
+} | {
+    readonly kind: "suspended";
+    readonly pending: readonly ToolCall[];
+} | {
+    readonly kind: "done";
+    readonly output: AgentTurn | null;
+} | {
+    readonly kind: "failed";
+    readonly failure: AgentTerminalFailure<Stage>;
+};
+/**
+ * Derive the agent's lifecycle `status` from its durable slice — the pure
+ * status function that REPLACES every caller's hand re-derivation of the private
+ * shape (issue #49). PURE — reads no clock / RNG, allocates one small record.
+ *
+ * Ordering is terminal-first so a settled run never reports `running`:
+ *
+ *   1. `state.failure` (the agent's own annotation, set WITHOUT moving
+ *      `run.phase`) → `failed`. Checked first because `turn_limit` / `llm`
+ *      leave `run.phase === "running"`; reading `run.phase` first would
+ *      misreport such a run as `running`. This is the canonical failure source
+ *      when present.
+ *   2. `run.phase === "failed"` → `failed`, carrying `run.failure` (deadline /
+ *      stage). The fallback channel.
+ *   3. `run.phase === "done"` → `done` with `state.output` (#46).
+ *   4. running + conversation + `awaiting.kind === "tools"` → `suspended` with
+ *      the outstanding tool calls (`tools.running`). THE resumability condition.
+ *   5. otherwise → `running`.
+ */
+declare function status<Stage, P extends string, O extends Record<P, unknown>, R>(s: AgentState<Stage, P, O, R>): AgentStatus<Stage>;
+
+/**
+ * @demlik/tea/agent — the context-compaction seam (#85).
+ *
+ * The opt-in transcript snapshot-and-compact policy, shaped exactly like
+ * `AgentSnapshotConfig` (see `./types`) so a short agent pays nothing and cannot
+ * even mention the machinery. This module owns the whole `$compact` vocabulary:
+ * the reserved purpose, the summary schema, the consumer policy, the config
+ * discriminant, and the dedicated `compact_run` / `compact_ok` / `compact_err`
+ * Cmd + Msgs re-keyed off the composed resilient call at the agent boundary.
+ */
+
+/**
+ * The reserved purpose the compaction round-trip runs under (#85). Compaction
+ * is a DEDICATED resilient LLM call (design B1), NOT one of the consumer's brain
+ * purposes `P` — so it carries its own purpose literal, kept in the agent's
+ * private `$`-namespace (the same reserved-namespace discipline `with-resilience`
+ * uses) so it never collides with a consumer purpose. A consumer never names it.
+ */
+type CompactionPurpose = "$compact";
+/** The reserved compaction purpose's value — the single in-flight summarize call's key. */
+declare const COMPACTION_PURPOSE: CompactionPurpose;
+/**
+ * The purpose→output map for the compaction LLM call — the single reserved
+ * `$compact` purpose mapping to a {@link CompactionSummary}. Mirrors the brain
+ * call's `O` map, scoped to the one compaction purpose, so the composed
+ * `createLlmCall` parses the summarize output under the same structured-output
+ * contract the brain call uses.
+ */
+interface CompactionOutputs extends Record<CompactionPurpose, unknown> {
+    readonly $compact: CompactionSummary;
+}
+/**
+ * Narrow an unknown to a {@link CompactionSummary} — the runtime witness for the
+ * compaction call's structured output. Checks the one load-bearing field
+ * (`summary` is a string). PURE — allocates no Error.
+ */
+declare function isCompactionSummary(value: unknown): value is CompactionSummary;
+/**
+ * The `Schema<CompactionSummary>` the compaction call binds — tea's own parse
+ * target for the summarize round-trip (it OWNS the `$compact` purpose's output).
+ * Throws on a non-summary (the zod-style `parse` contract the llm-call handler
+ * relies on), so a malformed summary is a `compact_err` (errors are data), never
+ * a corrupt fold-back.
+ */
+declare const compactionSummarySchema: Schema<CompactionSummary>;
+/**
+ * The result a compaction round-trip produces — the model's summary of the
+ * folded-away turns. Tea OWNS this shape (the `$compact` purpose's output): the
+ * fold-back (`compact_ok`) writes `summary` into a synthetic head `AgentTurn`
+ * (design A1), so a consumer's `loadMessages` reads it as a normal turn with no
+ * watermark to learn. Generic-free — the summary is always plain text.
+ */
+interface CompactionSummary {
+    /** The model's summary of the folded-away (oldest) turns + their tool records. */
+    readonly summary: string;
+}
+/**
+ * The consumer's compaction policy (#85). One PURE trigger; the impure
+ * summarize round-trip is composed by the agent (a dedicated resilient LLM call
+ * under the reserved `$compact` purpose, inheriting retry/backoff — design B1),
+ * so the policy never reaches the model itself.
+ *
+ *   - `planCompaction` — PURE: given the live conversation ABOUT to fire a brain
+ *     call, return how many of the OLDEST turns to fold into a summary, or `0`
+ *     to skip. No clock, no RNG → replay re-decides identically (design D). A
+ *     char-length / turn-count / real deterministic-tokenizer heuristic all
+ *     qualify. Returning `>= turns.length` is clamped to "fold all but keep the
+ *     loop alive" by the trigger (it never folds the turn currently in flight).
+ *   - `payloadOf` — build the per-call prompt payload the compaction
+ *     `MessageLoader` reads (the turns being folded). Omit → `null` (the loader,
+ *     if any, reads the conversation off the agent's own state). Opaque to the
+ *     agent, exactly like the brain call's `payloadOf`.
+ */
+interface CompactionPolicy<R, Msg = unknown> {
+    /** PURE trigger: how many OLDEST turns to fold (`0` = skip). No clock/RNG. */
+    readonly planCompaction: (conversation: Conversation<R>) => number;
+    /** Build the summarize call's prompt payload from the turns being folded. Omit → `null`. */
+    readonly payloadOf?: (conversation: Conversation<R>, folding: number) => unknown;
+    /** DI port — the SDK / message loader for the summarize call. Omit → invoke with `[]`. */
+    readonly loadMessages?: MessageLoader<CompactionPurpose, Msg>;
+}
+/**
+ * The compaction discriminant (#85), shaped exactly like {@link
+ * AgentSnapshotConfig}. Compaction is either OFF —
+ * `compaction` is structurally absent and the agent never emits a `compact_run`
+ * Cmd — or ON, in which case `compaction` is a {@link CompactionPolicy}. A `{
+ * compaction?: never }` member (rather than a bare optional) makes the OFF case
+ * load-bearing: it forbids passing `compaction` at all, so `toMachine`
+ * config-derives whether the `compact_run` interpret cell is REQUIRED (ON) or
+ * FORBIDDEN (OFF) — never a silent no-op cell, the #55 type-lie-killer reused.
+ */
+type AgentCompactionConfig<R, Msg> = {
+    readonly compaction?: never;
+} | {
+    readonly compaction: CompactionPolicy<R, Msg>;
+};
+/**
+ * The "summarize the oldest N turns" effect Cmd — the compaction round-trip's
+ * carrier (#85). It mirrors the brain `resilient_run` Cmd's shape (a `key` + the
+ * plain `LlmCall<CompactionPurpose>` input, no closures) but under the dedicated
+ * `compact_run` discriminant so it routes to the compaction interpret cell, not
+ * the brain one. The cell composes the resilient brick (retry/backoff) and
+ * returns the re-keyed `compact_ok` / `compact_err` settle for re-entry.
+ */
+type AgentCompactRunCmd = Cmd<typeof MsgType.CompactRun> & {
+    readonly key: CompactionPurpose;
+    readonly input: LlmCall<CompactionPurpose>;
+};
+/** The compaction round-trip success settle Msg — carries the parsed {@link CompactionSummary}. */
+type AgentCompactOkMsg = {
+    readonly type: typeof MsgType.CompactOk;
+    readonly key: CompactionPurpose;
+    readonly result: LlmOk<CompactionPurpose, CompactionOutputs>;
+    readonly at: number;
+};
+/** The compaction round-trip failure settle Msg — carries the typed {@link LlmErr}. */
+type AgentCompactErrMsg = {
+    readonly type: typeof MsgType.CompactErr;
+    readonly key: CompactionPurpose;
+    readonly error: LlmErr<CompactionPurpose>;
+    readonly at: number;
+};
+/**
+ * The CONFIG-DERIVED compaction obligation on `toMachine`'s `toolInterpret`
+ * (#85), the exact twin of {@link SnapshotInterpret}.
+ * Resolves on the `Compact` discriminant the compaction overload of
+ * `createAgent` fixes:
+ *
+ *   - compaction ON  → a REQUIRED `compact_run` cell
+ *     (`Interpret<M, AgentCompactRunCmd, Ctx>`). The summarize round-trip MUST be
+ *     wired — the agent never defaults it to a no-op.
+ *   - compaction OFF → `{ compact_run?: never }`. The cell is FORBIDDEN: with no
+ *     policy the agent never emits a `compact_run` Cmd, so wiring it would be
+ *     dead code. The consumer cannot even mention `compact_run`.
+ *
+ * Same type-lie-killer as the snapshot derivation: the obligation is present
+ * EXACTLY when the Cmd can fire, never as a silent gap the agent backfills.
+ */
+type CompactInterpret<M extends {
+    type: string;
+}, Compact extends boolean, Ctx> = Compact extends true ? Interpret<M, AgentCompactRunCmd, Ctx> : {
+    readonly compact_run?: never;
+};
+
+/**
+ * @demlik/tea/agent — the wired-machine surface.
+ *
+ * The Cmd / Msg vocabulary the knob speaks, the knob interface `createAgent`
+ * returns (`AgentKnob` / `AgentToMachine`), the do↔agent boot port, the
+ * semantic lifecycle event stream + its projector (`agentEvents`), and the two
+ * pure wiring helpers `mergeInterpret` / `liftAgent`. The reducer core (the
+ * `createAgent` factory that implements this surface) lives in `./index`.
+ */
+
+/** The brain-call effect Cmd, inherited from `../llm-call`. */
+type AgentLlmRunCmd<P extends string> = LlmRunCmd<P>;
+/**
+ * The Cmd union the agent emits, as a CLOSED discriminated union (precise `TC`,
+ * not the open `Cmd`) so `Interpret<M, AgentCmd<P, TC>, Ctx>` maps each key
+ * precisely and `toMachine` merges the interpret halves with no laundering cast:
+ *
+ *   - `AgentLlmRunCmd<P>`     — the brain-call run Cmd (`resilient_run`), folded
+ *                              by the wired `brainHandlers` cell.
+ *   - `MonitoredRunCmd<unknown>` — the durable checkpoint write the monitored-run
+ *                              slice emits, present in the union ONLY when
+ *                              checkpointing is on (`Snap = true`). With
+ *                              checkpointing off the monitored-run slice never
+ *                              emits a `snapshot_write` Cmd, so it is config-derived
+ *                              OUT of the emitted set — the consumer is never asked
+ *                              to interpret a Cmd that can never fire (#55).
+ *   - `TC`                    — the consumer's per-tool effect, mapped to the
+ *                              consumer's own tool interpret cell.
+ *
+ * `Snap` defaults to `true` so the verb-internal usage (which forwards whatever
+ * monitored-run emits) and the published type stay a safe superset; the wired
+ * machine `toMachine` returns is parametrized on the overload-fixed `Snap` so its
+ * Cmd set is exact (`MonitoredRunCmd` present only when checkpointing is on).
+ */
+type AgentCmd<P extends string, TC extends Cmd = Cmd, Snap extends boolean = true, Compact extends boolean = true> = AgentLlmRunCmd<P> | (Snap extends true ? MonitoredRunCmd<unknown> : never) | (Compact extends true ? AgentCompactRunCmd : never) | TC;
+/**
+ * The CONFIG-DERIVED snapshot obligation on `toMachine`'s `toolInterpret` (#55).
+ * Resolves on the `Snap` discriminant the snapshotting overload of `createAgent`
+ * fixes (`true` checkpointing-on / `false` off):
+ *
+ *   - checkpointing ON  → a REQUIRED `snapshot_write` cell
+ *     (`Interpret<M, MonitoredRunCmd<unknown>, Ctx>`). A real checkpoint write
+ *     MUST be wired — the agent never defaults it to a no-op.
+ *   - checkpointing OFF → `{ snapshot_write?: never }`. The cell is FORBIDDEN:
+ *     the Cmd is config-derived out of the emitted set, so wiring it would be
+ *     dead code. The consumer cannot even mention `snapshot_write`.
+ *
+ * This is the type that kills the `snapshot_write: async () => undefined`
+ * ceremony: the obligation is present in the contract EXACTLY when the Cmd can
+ * fire, never as a silent gap the agent backfills.
+ */
+type SnapshotInterpret<M extends {
+    type: string;
+}, Snap extends boolean, Ctx> = Snap extends true ? Interpret<M, MonitoredRunCmd<unknown>, Ctx> : {
+    readonly snapshot_write?: never;
+};
+/**
+ * The `toMachine` signature, 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` cell via {@link SnapshotInterpret} and the `compact_run` cell
+ * via {@link CompactInterpret}, and the machine's Cmd type is the config-derived
+ * `AgentCmd<P, TC, Snap, Compact>`.
+ */
+type AgentToMachine<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd, Snap extends boolean, Compact extends boolean> = <Ctx = object>(opts?: {
+    readonly toolInterpret?: Interpret<AgentMachineMsg<P, O, R>, TC, Ctx> & SnapshotInterpret<AgentMachineMsg<P, O, R>, Snap, Ctx> & CompactInterpret<AgentMachineMsg<P, O, R>, Compact, Ctx>;
+}) => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, AgentCmd<P, TC, Snap, Compact>, DeadlineSub, Ctx>;
+/**
+ * The agent knob `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
+ * (the snapshot derivation, #55); every verb is snapshot-agnostic. The model
+ * message shape `Msg` does not appear on the knob surface (it is internal to the
+ * brain call's loader), so it is not a type parameter here — only `createAgent`
+ * carries it, to thread the config's `loadMessages` / `model` ports.
+ */
+interface AgentKnob<Stage, P extends string, O extends Record<P, AgentTurn>, R, TC extends Cmd, Snap extends boolean, Compact extends boolean> {
+    readonly init: () => AgentState<Stage, P, O, R>;
+    readonly start: AgentVerb1<Stage, P, O, R, TC, [runId: string, at: number]>;
+    readonly turn: AgentVerb1<Stage, P, O, R, TC, [
+        result: AgentTurn,
+        at: number
+    ]>;
+    readonly toolOk: AgentVerb1<Stage, P, O, R, TC, [
+        callId: string,
+        result: R,
+        at: number
+    ]>;
+    readonly toolErr: AgentVerb1<Stage, P, O, R, TC, [
+        callId: string,
+        reason: string,
+        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
+    ]>;
+    readonly compactOk: AgentVerb1<Stage, P, O, R, TC, [
+        key: string,
+        msg: AgentCompactOkMsg,
+        at: number
+    ]>;
+    readonly compactErr: AgentVerb1<Stage, P, O, R, TC, [
+        key: string,
+        msg: AgentCompactErrMsg,
+        at: number
+    ]>;
+    readonly onTimer: AgentVerb1<Stage, P, O, R, TC, [msg: AgentTimerMsg]>;
+    readonly boot: AgentVerb1<Stage, P, O, R, TC, [at: number]>;
+    readonly isSettled: (s: AgentState<Stage, P, O, R>) => boolean;
+    readonly currentStage: (s: AgentState<Stage, P, O, R>) => Stage | undefined;
+    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>;
+}
+/** A verb taking the state + `Args`, returning the knob'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 / failure settle Msgs, inherited from `../llm-call`. */
+type AgentLlmOkMsg<P extends string, O extends Record<P, unknown>> = LlmSucceedMsg<P, O>;
+type AgentLlmErrMsg<P extends string> = LlmFailMsg<P>;
+/**
+ * The timer Msg (retry + safety deadline) — `DeadlineExceeded`, the shared
+ * shape of both bricks' 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`
+ * cell 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 —
+ * the inherited `../llm-call` detached form's exact shape, NOT an `Interpret`.
+ * The `resilient_run` cell 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;
+    readonly at: number;
+};
+/**
+ * The do↔agent boot port: construct the `agent_boot` Msg `autoBoot` dispatches
+ * on a resumable rehydrate. The agent owns this constructor so the boot Msg
+ * shape lives in ONE place — the host fires it through here, never as a raw
+ * `{ type: "agent_boot" }` literal.
+ */
+declare function agentBootMsg(at: number): AgentBootMsg;
+/**
+ * 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
+ * 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
+ * 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`,
+ * so `succeed` never runs and the resilient slice stays `running` (#54). The
+ * `turn` verb remains on the knob for the consumer that wires the verbs by hand
+ * (manual wiring), but it is not part of the one wired machine's Msg surface.
+ */
+type AgentMachineMsg<P extends string, O extends Record<P, unknown>, R> = {
+    readonly type: typeof MsgType.AgentStart;
+    readonly runId: string;
+    readonly at: number;
+} | {
+    readonly type: typeof MsgType.AgentToolOk;
+    readonly callId: string;
+    readonly result: R;
+    readonly at: number;
+} | {
+    readonly type: typeof MsgType.AgentToolErr;
+    readonly callId: string;
+    readonly reason: string;
+    readonly at: number;
+} | AgentLlmOkMsg<P, O> | AgentLlmErrMsg<P> | AgentCompactOkMsg | AgentCompactErrMsg | AgentTimerMsg | AgentBootMsg;
+/**
+ * The agent's PUBLIC lifecycle events — the semantic stream a consumer
+ * subscribes to via `runtime.on(type, …)` (#47). This is the seam that
+ * DECOUPLES observability/SSE code from the agent's PRIVATE retry/loop Msg
+ * vocabulary: where the old code switched on `resilient_ok` / `agent_tool_ok`
+ * (the inherited resilient-call / tool-fan-out plumbing) off the raw `observe`
+ * firehose, a consumer now folds these named events. The private Msg names live
+ * ONLY inside `agentEvents` (the projector) — they appear nowhere in this union
+ * or any exported type, so a UI built on `TurnSettled` does not break the day
+ * 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
+ *     `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`.
+ *   - `RunDone` — the run finished. Projected off the post-transition State
+ *     reaching `run.phase === "done"`; carries the run's `output` (the terminal
+ *     model turn, or `null`) — the same first-class result `Runtime.result()`
+ *     reads (#46), surfaced as an event for the streaming consumer.
+ */
+type AgentEvent<R> = {
+    readonly type: "TurnSettled";
+    readonly turn: AgentTurn;
+} | {
+    readonly type: "ToolSettled";
+    readonly callId: string;
+    readonly result: R;
+} | {
+    readonly type: "RunDone";
+    readonly output: AgentTurn | null;
+};
+/**
+ * Project one APPLIED agent transition `(msg, state)` to its semantic
+ * {@link AgentEvent}s (#47) — the `events` projector a consumer passes to
+ * `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
+ * 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
+ * arms), so a private name never escapes into `AgentEvent`.
+ *
+ * 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` 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.
+ *
+ * PURE — reads only the passed `(msg, state)`; no clock, no RNG, no throw.
+ *
+ * @typeParam P     Brain-call purposes.
+ * @typeParam O     Per-purpose outputs (bound to `AgentTurn`, the agentic shape).
+ * @typeParam R     Tool result type.
+ * @typeParam Stage Pipeline stage type.
+ */
+declare function agentEvents<Stage, P extends string, O extends Record<P, AgentTurn>, R>(): (msg: AgentMachineMsg<P, O, R>, state: AgentState<Stage, P, O, R>) => readonly AgentEvent<R>[];
+/**
+ * Join two `Interpret` dictionaries over DISJOINT Cmd subsets `A` and `B` (over
+ * the same Msg union `M` and Ctx) into the full `Interpret<M, A | B, Ctx>`. The
+ * agent uses it to merge the consumer's per-tool / snapshot interpret (`A`) with
+ * the agent-owned brain-call handler (`B = AgentLlmRunCmd`) into the wired
+ * machine's single interpret table.
+ *
+ * The runtime result is exactly the spread of the two key-disjoint records. The
+ * single `as` is a SOUND mapped-type identity, not a laundering cast: `Interpret`
+ * is a homomorphic mapped type keyed by `Cmd["type"]`, so
+ * `Interpret<M, A, Ctx> & Interpret<M, B, Ctx>` IS `Interpret<M, A | B, Ctx>`
+ * (`(A | B)["type"] = A["type"] | B["type"]`). TypeScript does not reduce that
+ * intersection of two GENERIC mapped types on its own, so the equality is
+ * asserted ONCE here — preserving `M` and `Ctx` exactly — rather than smuggled
+ * through `as unknown as Interpret<...>` at every wiring site. Pure.
+ */
+declare function mergeInterpret<M extends {
+    type: string;
+}, A extends Cmd, B extends Cmd, Ctx>(a: Interpret<M, A, Ctx> | undefined, b: Interpret<M, B, Ctx>): Interpret<M, A | B, Ctx>;
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice
+ * lives at `state.agent`. Convenience for a host that nests the agent slice
+ * under a named field; the single-slice host uses the verbs' tuple directly.
+ * PURE — a thin record rebuild, no clock / RNG.
+ */
+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 { type AgentTurn as A, mergeInterpret as B, type CompactionPolicy as C, liftAgent as D, isAgentTurn as E, agentTurnSchema as F, type ToolOutcome as G, type ToolRecord as H, type Awaiting as I, type Conversation as J, type AgentSnapshotConfig as K, type AgentConfig as L, type AgentFailure as M, type AgentState as N, type AgentTerminalFailure as O, type AgentStatus as P, status as Q, type SnapshotInterpret as S, type ToolCall as T, type AgentConfigCore as a, type AgentKnob as b, type CompactionPurpose as c, COMPACTION_PURPOSE as d, type CompactionOutputs as e, compactionSummarySchema as f, type CompactionSummary as g, type AgentCompactionConfig as h, isCompactionSummary as i, type AgentCompactRunCmd as j, type AgentCompactOkMsg as k, type AgentCompactErrMsg as l, type CompactInterpret as m, type AgentLlmRunCmd as n, type AgentCmd as o, type AgentToMachine as p, type AgentLlmOkMsg as q, type AgentLlmErrMsg as r, type AgentTimerMsg as s, type AgentPorts as t, type AgentDetachedHandlers as u, type AgentBootMsg as v, agentBootMsg as w, type AgentMachineMsg as x, type AgentEvent as y, agentEvents as z };