@demlik/tea 0.17.0 → 0.19.0

package/dist/{machine-BcfCFMYF.d.ts → machine-CuojfZup.d.ts}

@@ -1,9 +1,9 @@
-import { C as Cmd, r as Tagged, o as Interpret, A as AnyCmdDef, c as CmdOf, b as CmdDef, j as Settled, s as OkOf, t as ErrOf, q as MalformedResult, l as Outcome, u as CmdValue, H as HandlerCtx, g as TaggedError, M as Machine, d as Subscribe } from './core-rDbOaJTN.js';
-import { a as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-BOrsbdAf.js';
-import { R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientState, r as RunCmdDef } from './index-q1PoukOZ.js';
-import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-DaX_P35Q.js';
+import { C as Cmd, o as Tagged, I as Interpret, A as AnyCmdDef, a as CmdOf, b as CmdDef, h as Settled, p as OkOf, E as ErrOf, n as MalformedResult, O as Outcome, q as CmdValue, H as HandlerCtx, f as TaggedError, M as Machine, S as Subscribe } from './core-Ce9ncpuv.js';
+import { b as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-Dy3379ve.js';
+import { R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientState, r as RunCmdDef } from './index-2kNxy6az.js';
+import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-e36uEyl4.js';
 import { M as MsgType, a as MsgTypeValue } from './protocol-ClRZBhHQ.js';
-import { F as FanOutState } from './index-Cx0F2M34.js';
+import { F as FanOutState } from './index-Ce5GYAuI.js';
 import { RetryPolicy, AnyRetryPolicy } from './retry-backoff/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
@@ -191,6 +191,15 @@ interface ToolCall {
  * which must be JSON-serializable like the rest of the Model. A compaction fold
  * (ADR 0004) summarises turns into text, so it drops the slot with the turns it
  * summarises. Optional and additive: a persisted turn without it still parses.
+ *
+ * `usage` is what the provider REPORTED this call cost (#332) — never an
+ * estimate tea computes. It is part of the brain call's journaled outcome, like
+ * `content`, so a replay folds the same numbers (ADR 0004's "no token estimate
+ * enters the Model" still holds). The run sums it into its running total
+ * ({@link AgentState.usage}) and the conversation reads the latest context size
+ * off it. Optional and additive: a turn
+ * whose adapter maps no usage, or one persisted before the field existed,
+ * parses and simply counts for nothing.
  */
 interface AgentTurn {
     /** Free-text narration the model produced this turn (folded into the conversation). */
@@ -199,7 +208,39 @@ interface AgentTurn {
     readonly toolCalls: readonly ToolCall[];
     /** Provider-opaque blocks to echo back verbatim next turn. tea never reads it. */
     readonly provider?: unknown;
+    /** The token usage the provider reported for this call. Omit → none reported. */
+    readonly usage?: TurnUsage;
 }
+/**
+ * The token usage a provider reported for one model call, in the provider's own
+ * counts. Every field is a non-negative integer; `agentTurnSchema` refuses
+ * anything else, so a malformed report is the brain call's `llm` failure rather
+ * than a `NaN` in the running total.
+ *
+ * `inputTokens` is the WHOLE prompt the call read, cached tokens included —
+ * the number that says how full the context window is. `cachedInputTokens` is
+ * the part of it the provider served from its prompt cache, so it never exceeds
+ * `inputTokens`. An adapter whose provider reports the two apart (Anthropic's
+ * `input_tokens` excludes cache reads) adds them back together here.
+ *
+ * The same shape is the run's running total ({@link AgentState.usage}): the
+ * sum, field by field, of every turn that reported one.
+ */
+interface TurnUsage {
+    /** Prompt tokens the call read, cached ones included. */
+    readonly inputTokens: number;
+    /** Tokens the model produced. */
+    readonly outputTokens: number;
+    /** Of `outputTokens`, those spent on reasoning — when the provider says. */
+    readonly reasoningTokens?: number;
+    /** Of `inputTokens`, those served from the provider's prompt cache — when it says. */
+    readonly cachedInputTokens?: number;
+}
+/**
+ * Narrow an unknown to a {@link TurnUsage} — the two required counts present,
+ * and each optional one either absent or a count too. PURE — allocates no Error.
+ */
+declare function isTurnUsage(value: unknown): value is TurnUsage;
 /**
  * One partial piece of a turn the model is still producing — a token delta, as
  * the provider emitted it.
@@ -262,8 +303,9 @@ declare function isStreamingModel(model: (...args: never[]) => unknown): boolean
  * 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`). `provider` is
- * opaque, so its presence or absence is not a fact the guard reads. PURE —
- * allocates no Error.
+ * opaque, so its presence or absence is not a fact the guard reads. `usage` is
+ * not opaque — the reducer sums it — so it is either absent or a well-formed
+ * {@link TurnUsage}. PURE — allocates no Error.
  */
 declare function isAgentTurn(value: unknown): value is AgentTurn;
 /**
@@ -436,6 +478,11 @@ type Awaiting = {
  * effect for the agentic stage.
  *
  * Generic over the consumer's tool-result type `R` (what `toolOk` carries).
+ *
+ * `contextTokens` is this transcript's reading of provider-reported usage
+ * (#332); the run's total is not the transcript's, so it lives on
+ * {@link AgentState.usage}. A Model persisted before `contextTokens` existed
+ * comes back without it, and the first transition fills it in as `null`.
  */
 interface Conversation<R> {
     /** Model turns this stage has produced, in order. */
@@ -446,6 +493,14 @@ interface Conversation<R> {
     readonly turnCount: number;
     /** What the loop is waiting for next. */
     readonly awaiting: Awaiting;
+    /**
+     * The latest context size: `inputTokens + outputTokens` of the most recent
+     * brain turn — how much of the context window the transcript now fills.
+     * `null` when that turn reported no usage, when a compaction fold has run
+     * since (the pre-fold size describes a transcript that no longer exists), and
+     * at the start of each stage. `compaction.afterContextTokens` reads it.
+     */
+    readonly contextTokens: number | null;
 }
 /**
  * The snapshotting discriminant. Checkpointing is either OFF — in which
@@ -595,8 +650,10 @@ interface AgentConfigCore<Stage, P extends string, O extends Record<P, AgentTurn
      * transcript stands and no further model call goes out. Omit → no predicate.
      *
      * Where `maxTurns` and `maxElapsedMs` bound a quantity this agent counts,
-     * this bounds one only the caller can see (a token ledger, an external flag,
-     * a condition on the turns so far). It must be PURE and total over the state
+     * this bounds one only the caller can see (an external flag, a condition on
+     * the turns so far) — or a token budget: `state.usage` is the run's running
+     * total of provider-reported usage, so a budget stop is a predicate over it
+     * and needs no knob of its own (#332). It must be PURE and total over the state
      * it is handed — the reducer calls it, so a replay of the same Msg log calls
      * it with the same state and must get the same answer. It is config, not
      * Model: a resumed run consults the predicate the config passed to THIS boot.
@@ -646,6 +703,8 @@ type AgentFailure = {
  *   - `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).
+ *   - `usage`        — the run's provider-reported token total. It outlives
+ *                      every conversation, `done` included.
  *   - `failure`      — the agent-specific terminal annotation (turn-limit /
  *                      llm), null otherwise. Distinct from `run.failure`.
  *   - `instructions` — the system prompt this run was configured with, set at
@@ -656,6 +715,20 @@ interface AgentState<Stage, P extends string, O extends Record<P, unknown>, R> {
     readonly resilience: ResilientState<LlmCall<P>, LlmOk<P, O>>;
     readonly tools: FanOutState<ToolCall, ToolOutcome<R>>;
     readonly conversation: Conversation<R> | null;
+    /**
+     * The run's running usage total (#332, #354): every brain turn of this RUN
+     * that reported usage, summed field by field. It is what the run cost, so it
+     * belongs to the run and not to any one conversation: a compaction fold keeps
+     * it, a stage advance keeps it, and the retire to `done` keeps it after the
+     * conversation is cleared — `status(state)`'s `done` arm hands it on. Only
+     * `agent_start` resets it to zero. Read it from `stopWhen` for a token budget.
+     *
+     * The one place the total lives. A Model persisted before this field held its
+     * total on `conversation.usage`, and one persisted by 0.17.x held none; the
+     * first transition either takes over lifts the old total here (or starts from
+     * zero) and drops the conversation's copy.
+     */
+    readonly usage: TurnUsage;
     /**
      * The compaction round-trip's resilient slice (#85, design B1) — a DEDICATED
      * resilient-call slice for the reserved `$compact` purpose, separate from the
@@ -702,6 +775,22 @@ interface AgentState<Stage, P extends string, O extends Record<P, unknown>, R> {
      * retire on purpose — that is exactly when a late settle arrives.
      */
     readonly refusedCalls: readonly string[];
+    /**
+     * What THIS transition started, failed or ended (#331) — the outbox the
+     * event projector reads. Cleared on entry to every verb, so it only ever
+     * holds the one transition's facts.
+     *
+     * The projector sees `(msg, post-state)` and nothing else, and none of these
+     * facts can be read back off that pair: a brain call issued after a batch
+     * drains, a queued tool backfilling a slot, a timeout the ladder settled and
+     * the transition that ended the run all leave a state that looks like the
+     * one before. The reducer knows at the moment it does them, so it writes
+     * them down here, the same way `refusedCalls` carries the one fact the
+     * projector could not derive.
+     *
+     * Absent on a Model persisted before 0.18; every reader treats that as empty.
+     */
+    readonly lifecycle: readonly AgentLifecycleNote[];
     readonly failure: AgentFailure | null;
     /**
      * The run's terminal output — the FIRST-CLASS result (issue #46). `null`
@@ -750,6 +839,45 @@ interface AgentState<Stage, P extends string, O extends Record<P, unknown>, R> {
  * without knowing which channel produced it.
  */
 type AgentTerminalFailure<Stage> = AgentFailure | RunFailure<Stage>;
+/**
+ * One fact a transition recorded on {@link AgentState.lifecycle} — the input
+ * the `agentEvents` projector turns into `BrainStarted`, `ToolStarted`,
+ * `ToolFailed` and `RunDone`.
+ *
+ *   - `brain_started` — a brain call was issued for conversation turn `turn`.
+ *     Once per turn, and again on a cold-wake `boot` that re-fires it; a retry
+ *     of the same turn is not a new start. It names the call by its `purpose`,
+ *     which is the call's key on {@link AgentState.resilience}, and carries no
+ *     copy of the request: the in-flight `LlmCall` is already on that slice, so
+ *     a checkpoint holds the prompt once (#354). The projector reads the
+ *     request's `payload` from there.
+ *   - `tool_started`  — a tool call was issued: launched from a batch, a
+ *     queued call backfilling a slot, or re-fired by `boot`. A retry is not a
+ *     new start.
+ *   - `tool_failed`   — a call ended on a failure the model will read: its own
+ *     error, a spent retry budget, or its timeout.
+ *   - `run_ended`     — the run reached `done`, `failed` or `cancelled` on
+ *     this transition.
+ */
+type AgentLifecycleNote = {
+    readonly kind: "brain_started";
+    readonly turn: number;
+    readonly purpose: string;
+    readonly model: string | null;
+    readonly at: number;
+} | {
+    readonly kind: "tool_started";
+    readonly call: ToolCall;
+    readonly at: number;
+} | {
+    readonly kind: "tool_failed";
+    readonly call: ToolCall;
+    readonly failure: ToolFailure;
+    readonly at: number;
+} | {
+    readonly kind: "run_ended";
+    readonly at: number;
+};
 /**
  * The agent's lifecycle status — THE single typed channel for "what is this run
  * doing?". A discriminated union on `kind` so any change to the
@@ -774,7 +902,8 @@ type AgentTerminalFailure<Stage> = AgentFailure | RunFailure<Stage>;
  *                   `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.
+ *                   produced no turn. `usage` is what the whole run cost,
+ *                   `state.usage` (#354).
  *   - `failed`    — terminal failure; `failure` is the UNIFIED channel
  *                   (`AgentTerminalFailure`), absorbing the `state.failure` vs
  *                   `state.run.failure` dual channel so callers stop unioning.
@@ -797,6 +926,7 @@ type AgentStatus<Stage> = {
 } | {
     readonly kind: "done";
     readonly output: AgentTurn | null;
+    readonly usage: TurnUsage;
 } | {
     readonly kind: "failed";
     readonly failure: AgentTerminalFailure<Stage>;
@@ -804,6 +934,14 @@ type AgentStatus<Stage> = {
     readonly kind: "cancelled";
     readonly at: number;
 };
+/**
+ * The three {@link AgentStatus} arms a run can end on — what `RunDone` carries.
+ * `done` holds the output, `failed` the unified failure, `cancelled` when the
+ * stop landed.
+ */
+type AgentEndedStatus<Stage = unknown> = Extract<AgentStatus<Stage>, {
+    readonly kind: "done" | "failed" | "cancelled";
+}>;
 /**
  * Ask where an agent run stands: pass its state, get back one of `idle`,
  * `running`, `suspended` (with the tool calls it is waiting on), `done` (with
@@ -825,7 +963,8 @@ type AgentStatus<Stage> = {
  *      an `init` slice is never mistaken for a run in flight.
  *   3. `run.phase === "failed"` → `failed`, carrying `run.failure` (deadline /
  *      stage). The fallback channel.
- *   4. `run.phase === "done"` → `done` with `state.output` (#46).
+ *   4. `run.phase === "done"` → `done` with `state.output` (#46) and the run's
+ *      usage total (#354).
  *   5. `run.phase === "cancelled"` → `cancelled`, carrying when the stop landed.
  *   6. `running` / `stale` + conversation + `awaiting.kind === "tools"` →
  *      `suspended` with the outstanding tool calls (`tools.running`). THE
@@ -985,17 +1124,81 @@ type CompactInterpret<M extends {
 };
 
 /**
- * @demlik/tea/agent — `tool()` + `toolRouter()`: declare a tool once and derive
- * what a consumer used to hand-write twice — the `toolOf` mapping from a
- * model's `ToolCall` to an effect Cmd, and the interpret handler that runs it
- * and settles it.
+ * @demlik/tea/agent — content parts: the provider-neutral shape a multimodal
+ * message is written in.
  *
- * A tool is a `Cmd.define`d effect whose input is the model's call —
- * `{ callId, args }` — with the handler colocated on the constructor. The
- * router folds a set of them into one `toolOf` and one interpret table; the
- * handlers settle through the minted `<name>_ok` / `<name>_err` Msgs, errors as
- * `{ _tag }` data (ADR 0011). `createAgent(...).toMachine({ tools })` folds
- * those settles into the conversation, so a consumer names nothing twice.
+ * A `user` message's content is a string or a list of parts, and a tool can
+ * hand the model parts beside its outcome (a screenshot, a PDF). The three
+ * kinds are the intersection Anthropic's and OpenAI's content blocks both map
+ * onto — text, an image, a file — and tea imports neither SDK: the adapter
+ * maps a part to its provider's block, exactly as it maps a whole message.
+ */
+/**
+ * Where an image's or a file's bytes are. Inline as base64 text, inline as raw
+ * bytes, or out of band at a URL — one of the three, never a part that carries
+ * both data and a URL.
+ *
+ * A part a tool derives from its result is re-derived on every render from the
+ * durable result, so the part itself is never stored; the RESULT is. Keep what
+ * the result holds JSON-shaped — base64 text survives a JSON `Store`, a
+ * `Uint8Array` does not — and derive `bytes` from it only if your adapter wants
+ * them.
+ */
+type MediaSource = {
+    readonly type: "base64";
+    readonly data: string;
+} | {
+    readonly type: "bytes";
+    readonly data: Uint8Array;
+} | {
+    readonly type: "url";
+    readonly url: string;
+};
+/** A run of text. */
+interface TextPart {
+    readonly type: "text";
+    readonly text: string;
+}
+/** An image the model looks at; `mediaType` is its IANA type, such as `image/jpeg`. */
+interface ImagePart {
+    readonly type: "image";
+    readonly mediaType: string;
+    readonly source: MediaSource;
+}
+/** A document the model reads; `mediaType` is its IANA type, such as `application/pdf`. */
+interface FilePart {
+    readonly type: "file";
+    readonly mediaType: string;
+    readonly source: MediaSource;
+}
+/** One part of a multimodal message. */
+type ContentPart = TextPart | ImagePart | FilePart;
+/** A message's content: a plain string, or a list of parts. */
+type MessageContent = string | readonly ContentPart[];
+/**
+ * A message's content as parts — a string reads as one text part, so an adapter
+ * maps one shape whichever it was handed. PURE.
+ */
+declare function contentParts(content: MessageContent): readonly ContentPart[];
+/** The text an omitted image stands in as. */
+declare const IMAGE_OMITTED = "[image omitted]";
+/** The text an omitted file stands in as. */
+declare const FILE_OMITTED = "[file omitted]";
+/**
+ * The parts with every image and file replaced by a text placeholder — what a
+ * summarizer is handed, since the summary is text and cannot carry the pixels
+ * forward. Text parts pass through by reference. PURE.
+ */
+declare function omitMedia(parts: readonly ContentPart[]): readonly ContentPart[];
+
+/**
+ * @demlik/tea/agent — the one construction every tool definition goes through.
+ *
+ * NOT part of the public `./agent` barrel. `tool()` and `agentTool()` are two
+ * doors onto the same `ToolDef`: `tool()` hands its handler the parsed `args`,
+ * and `agentTool()` needs the whole Cmd — `callId` included — because the call's
+ * identity is what keys the child run. Both are built here, so the reserved-name
+ * refusal, the `thrown` channel and the resilience knob have one definition.
  */
 
 /**
@@ -1007,7 +1210,7 @@ type SettlePrefixOf<T extends string> = T extends `${infer P}_ok` | `${infer P}_
 declare const REJECTED_TYPE = "tool_rejected";
 declare const SNAPSHOT_WRITE_TYPE = "snapshot_write";
 /**
- * A tool name `tool()` refuses. A tool's name is its Cmd `type` — so
+ * A tool name `tool()` and `agentTool()` refuse. 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_run`, `agent_tool`, `compact`) would overwrite the agent's own
@@ -1022,15 +1225,30 @@ declare const SNAPSHOT_WRITE_TYPE = "snapshot_write";
  * `snapshot_write`, which `toMachine` merges under the consumer's key.
  */
 type ReservedToolName = MsgTypeValue | SettlePrefixOf<MsgTypeValue> | typeof REJECTED_TYPE | typeof SNAPSHOT_WRITE_TYPE;
+/** Whether `name` is one a tool door refuses — the set `ReservedToolName` types. */
+declare function isReservedToolName(name: string): name is ReservedToolName;
 /**
  * Widens to `unknown` for a name outside the reserved set and to `never`
  * inside it, so `Name & NotReserved<Name>` is the name itself or
  * unconstructible. A widened `string` passes here — the runtime check in
- * `tool()` is what catches a reserved name built from one.
+ * `definedTool` is what catches a reserved name built from one.
  */
 type NotReserved<Name extends string> = Name extends ReservedToolName ? never : unknown;
-/** Whether `name` is one `tool()` refuses — the set `ReservedToolName` types. */
-declare function isReservedToolName(name: string): name is ReservedToolName;
+
+/**
+ * @demlik/tea/agent — `tool()` + `toolRouter()`: declare a tool once and derive
+ * what a consumer used to hand-write twice — the `toolOf` mapping from a
+ * model's `ToolCall` to an effect Cmd, and the interpret handler that runs it
+ * and settles it.
+ *
+ * A tool is a `Cmd.define`d effect whose input is the model's call —
+ * `{ callId, args }` — with the handler colocated on the constructor. The
+ * router folds a set of them into one `toolOf` and one interpret table; the
+ * handlers settle through the minted `<name>_ok` / `<name>_err` Msgs, errors as
+ * `{ _tag }` data (ADR 0011). `createAgent(...).toMachine({ tools })` folds
+ * those settles into the conversation, so a consumer names nothing twice.
+ */
+
 /**
  * The input a tool Cmd carries: the model's `callId` (the fan-out identity the
  * settle folds back on) and the `args` already parsed against the tool's
@@ -1096,6 +1314,11 @@ type ToolDef<Name extends string, Args, Ok, E extends Tagged, Ctx> = CmdDef<Name
      * neither. `toolRouter` serves it to the agent as `resilienceOf`.
      */
     readonly resilience: ToolResilience | null;
+    /**
+     * The parts the model reads for an `ok` result, or `null` when the tool
+     * declared no `content` and the model reads the result as data.
+     */
+    readonly content: ((result: Ok) => readonly ContentPart[]) | null;
     /**
      * The colocated handler, as an interpret cell: it returns the tool's
      * outcome, and the engine mints `<name>_ok` / `<name>_err` from it.
@@ -1109,6 +1332,7 @@ type AnyToolDef = AnyCmdDef & {
     readonly description: string;
     readonly args: StandardSchemaV1;
     readonly resilience: ToolResilience | null;
+    readonly content: ((result: never) => readonly ContentPart[]) | null;
     readonly interpret: (cmd: never, ctx: never) => Promise<unknown>;
 };
 /**
@@ -1163,6 +1387,16 @@ declare function tool<const Name extends string, Args, Ok, const Tags extends re
      * Omit → the first failure is the outcome.
      */
     readonly retry?: ToolResilience["retry"];
+    /**
+     * What the model SEES of an `ok` result, as content parts. A screenshot
+     * tool whose result is `{ jpeg }` (base64) declares
+     * `content: (r) => [{ type: "image", mediaType: "image/jpeg", source: { type: "base64", data: r.jpeg } }]`.
+     * The parts ride on the `tool` message beside the outcome, so an adapter
+     * sends them instead of stringifying the result. PURE: it runs on every
+     * render, over the result as the `Store` hands it back, and never on a
+     * failure. Omit → the model reads the outcome as data, as before.
+     */
+    readonly content?: (result: Ok) => readonly ContentPart[];
 }, 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
@@ -1264,6 +1498,12 @@ interface ToolRouter<T extends AnyToolDef> {
      * path settles in the reducer and never runs an effect to time out). PURE.
      */
     readonly resilienceOf: (call: ToolCall) => ToolResilience | null;
+    /**
+     * The parts the model reads for one settled call: the called tool's
+     * `content` over an `ok` result. `null` for a failure, for a tool that
+     * declared no `content`, and for a call no tool answers. PURE.
+     */
+    readonly partsOf: (call: ToolCall, outcome: ToolOutcome<unknown>) => readonly ContentPart[] | null;
     /**
      * Read a settled tool off a Msg: `null` when the Msg is not one of this
      * router's `<name>_ok` / `<name>_err`. The one place a `{ _tag }` failure is
@@ -1568,60 +1808,116 @@ type AgentMachineMsg<P extends string, O extends Record<P, unknown>, R> = {
  * or any exported type, so a UI built on `TurnSettled` does not break the day
  * the retry plumbing is renamed.
  *
+ * Every event carries the run's `runId` and the `at` of the transition that
+ * produced it. `runId` is the one the host passed to `agent_start` and it lives
+ * on the durable Model, so a run killed and resumed from its `Store` reports
+ * the same id on both sides of the kill (#331).
+ *
+ *   - `BrainStarted` — a brain call was issued for conversation turn `turn`,
+ *     with the request's `purpose`, `model` and `payload`. Once per turn: a
+ *     retry of the same turn is not a new start, a cold-wake `boot` that
+ *     re-fires it is.
  *   - `TurnSettled` — a brain turn settled (the model produced an `AgentTurn`).
- *     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`.
- *   - `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> = {
+ *     Carries the parsed `turn`, and — when the provider reported one — that
+ *     call's `usage` beside it (#332), so a progress surface reads the context
+ *     size without digging into the turn.
+ *   - `ToolStarted` — a tool call was issued: launched with its batch, a
+ *     queued call backfilling a freed slot, or re-fired by `boot`. A laddered
+ *     retry is not a new start.
+ *   - `ToolSettled` — a tool call settled OK, with the `callId` and `result`.
+ *   - `ToolFailed` — a tool call ended on the failure the model will read: its
+ *     own error, a spent retry budget, or its timeout. `failure` is the
+ *     `{ kind, reason, _tag? }` the conversation keeps.
+ *   - `RunDone` — the run ended, once. `status` says how: `done` with the
+ *     terminal turn, `failed` with the unified failure, or `cancelled`.
+ */
+type AgentEvent<R> = (AgentEventHead & {
+    readonly type: "BrainStarted";
+    readonly turn: number;
+    readonly purpose: string;
+    readonly model: string | null;
+    readonly payload: unknown;
+}) | (AgentEventHead & {
     readonly type: "TurnSettled";
     readonly turn: AgentTurn;
-} | {
+    /** The usage the provider reported for this turn. Absent → none reported. */
+    readonly usage?: TurnUsage;
+}) | (AgentEventHead & {
+    readonly type: "ToolStarted";
+    readonly callId: string;
+    readonly name: string;
+    readonly args: Readonly<Record<string, unknown>>;
+}) | (AgentEventHead & {
     readonly type: "ToolSettled";
     readonly callId: string;
     readonly result: R;
-} | {
+}) | (AgentEventHead & {
+    readonly type: "ToolFailed";
+    readonly callId: string;
+    readonly name: string;
+    readonly failure: ToolFailure;
+}) | (AgentEventHead & {
     readonly type: "RunDone";
-    readonly output: AgentTurn | null;
-};
+    readonly status: AgentEndedStatus;
+});
+/** The two fields every {@link AgentEvent} carries. */
+interface AgentEventHead {
+    /** The run this event belongs to — stable across a kill and resume. */
+    readonly runId: string;
+    /** When the transition that produced it happened. */
+    readonly at: number;
+}
+/**
+ * Every {@link AgentEvent} `type`. A subscriber that wants the whole stream
+ * off `runtime.on` subscribes once per entry. `satisfies` proves each entry is
+ * a real type; a type test proves no real type is missing.
+ */
+declare const AGENT_EVENT_TYPES: readonly ["BrainStarted", "TurnSettled", "ToolStarted", "ToolSettled", "ToolFailed", "RunDone"];
 /**
  * Project one APPLIED agent transition `(msg, state)` to its semantic
  * {@link AgentEvent}s — 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_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
- * arms), so a private name never escapes into `AgentEvent`.
+ * Two sources, in this order:
  *
- * 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_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.
+ *   1. The Msg. `resilient_run_ok` → `TurnSettled`, `agent_tool_ok` (or a
+ *      router's `<name>_ok`) → `ToolSettled`. This is the ONE place the
+ *      agent's PRIVATE Msg names are read; the switch is total over the Msg
+ *      union, so a private name never escapes into `AgentEvent`.
+ *   2. The transition's lifecycle outbox, `state.lifecycle` — what the reducer
+ *      noted as it started a brain call or a tool, failed a tool, or ended the
+ *      run. These cannot be read off `(msg, state)`: a brain call issued after
+ *      a batch drains, a queued tool backfilling a slot, a timeout the ladder
+ *      settled and the transition that ended the run all leave a state that
+ *      looks like the one before (#331).
+ *
+ * So a turn that asks for tools reads `TurnSettled`, then one `ToolStarted`
+ * per launched call; the last tool of a batch reads `ToolSettled` (or
+ * `ToolFailed`), then the next `BrainStarted`; and the final turn reads
+ * `TurnSettled`, then `RunDone`.
  *
  * A `ToolSettled` is gated on `state.refusedCalls` (#145): a call whose public
  * outcome was already a failure — the ladder's `timeout` / `retry_exhausted`,
  * or the tool's own error — never emits a success here, however late its
  * abandoned attempt resolves. Both settle arms read the same list, so a
- * router-wired agent and a fan-out-wired one are silent on the same calls, and
- * the decision is made in the PURE layer rather than filtered at a
- * subscription seam — `runtime.on` and `defineAgent`'s `onEvent` see one
- * stream.
+ * router-wired agent and a fan-out-wired one are silent on the same calls.
+ * A cancelled run's Msg-shaped events are closed the same way — a tool that
+ * was in flight when the abort landed pushes nothing — while the cancel's own
+ * `RunDone` still comes through, because it is noted, not Msg-shaped.
+ *
+ * A run cancelled before it ever started has no `runId`, and projects nothing.
  *
  * A machine wired with `toMachine({ tools })` settles tools through the
  * router's `<name>_ok` Msgs instead of `agent_tool_ok`; pass the same router
  * here so those settles project to `ToolSettled` too.
  *
- * PURE — reads only the passed `(msg, state)`; no clock, no RNG, no throw.
+ * Each outbox is projected once per projector (#355). A host that wires the
+ * verbs by hand and folds a Msg of its own leaves `state.lifecycle` as the
+ * previous agent transition left it, and that transition's notes are not
+ * projected a second time.
+ *
+ * Reads only the passed `(msg, state)` and the set of outboxes it has already
+ * projected; no clock, no RNG, no throw.
  *
  * @typeParam P     Brain-call purposes.
  * @typeParam O     Per-purpose outputs (bound to `AgentTurn`, the agentic shape).
@@ -1661,4 +1957,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 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 };
+export { IMAGE_OMITTED as $, type AgentEvent as A, type AgentConfig as B, type ContentPart as C, type AgentEventHead as D, type AgentFailure as E, type AgentLifecycleNote as F, type AgentLlmErrMsg as G, type AgentLlmOkMsg as H, type AgentLlmRunCmd as I, type AgentSnapshotConfig as J, type AgentStatus as K, type AgentTimerMsg as L, type MessageContent as M, type NotReserved as N, type AgentToMachine as O, type PlainModel as P, type Awaiting as Q, COMPACTION_PURPOSE as R, type StreamingModel as S, type ToolCall as T, type CompactInterpret as U, type CompactionOutputs as V, type WiredToolMsg as W, type CompactionPurpose as X, type CompactionSummary as Y, FILE_OMITTED as Z, type FilePart as _, type ToolOutcome as a, type ImagePart as a0, type Llm as a1, type LlmCall as a2, type LlmErr as a3, type LlmFailMsg as a4, type LlmOk as a5, type LlmRunCmd as a6, type LlmSucceedMsg as a7, type MediaSource as a8, type MessageLoader as a9, type ToolSettlement as aA, type ToolTimedOut as aB, type TurnUsage as aC, type WiredToolCmd as aD, agentBootMsg as aE, agentCancelMsg as aF, agentEvents as aG, agentTurnSchema as aH, compactionSummarySchema as aI, contentParts as aJ, fanOutInterpret as aK, isAgentTurn as aL, isCompactionSummary as aM, isReservedToolName as aN, isStreamingModel as aO, isTurnUsage as aP, liftAgent as aQ, mergeInterpret as aR, omitMedia as aS, plainModel as aT, status as aU, tool as aV, toolErrorReason as aW, toolRouter as aX, type ModelFactory as aa, type ModelPort as ab, type ModelStream as ac, PLAIN_MODEL_MISROUTE_REASON as ad, type ReservedToolName as ae, type Schema as af, type SnapshotInterpret as ag, TOOL_RETRY_EXHAUSTED_TAG as ah, TOOL_TIMEOUT_TAG as ai, type TaggedFailure as aj, type TextPart as ak, type ToolConstructors as al, type ToolError as am, type ToolFail as an, type ToolFailure as ao, type ToolHandler as ap, type ToolInput as aq, type ToolMsg as ar, type ToolOk as as, type ToolRecord as at, type ToolRejectedCmd as au, type ToolRejection as av, type ToolResilience as aw, type ToolResilienceError as ax, type ToolRetryExhausted as ay, type ToolRouter as az, type Conversation as b, type AnyToolDef as c, type ToolsCtx as d, type AgentState as e, type AgentTurn as f, type ToolResult as g, type TurnChunk as h, type AgentMachineMsg as i, type AgentCmd as j, type ToolCmd as k, type ToolFailureOf as l, type AgentTerminalFailure as m, type ToolDef as n, type ToolThrown as o, type AgentEndedStatus as p, type AgentConfigCore as q, type CompactionPolicy as r, type AgentKnob as s, AGENT_EVENT_TYPES as t, type AgentBootMsg as u, type AgentCancelMsg as v, type AgentCompactErrMsg as w, type AgentCompactOkMsg as x, type AgentCompactRunCmd as y, type AgentCompactionConfig as z };

package/dist/machine-viz/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-rDbOaJTN.js';
+import { C as Cmd, c as Sub, M as Machine } from '../core-Ce9ncpuv.js';
 import '@standard-schema/spec';
 
 /**

package/dist/machine-viz/index.js

@@ -1,5 +1,5 @@
-import '../chunk-C4U5D5HP.js';
-import { formOf, subEntriesOf, desiredSub } from '../chunk-K4ETBNKS.js';
+import '../chunk-FNGZMVIT.js';
+import { formOf, subEntriesOf, desiredSub } from '../chunk-AIIXV4XB.js';
 
 // src/machine-viz/mermaid-id.ts
 function safeId(raw) {