@demlik/tea 0.17.0 → 0.19.0

package/dist/{chunk-XBZQT2TD.js → chunk-PCJA2HTZ.js}

@@ -1,11 +1,10 @@
-import { describeError } from './chunk-G5E74IJB.js';
-import { createMonitoredRun } from './chunk-4PXNZ5UY.js';
+import { createMonitoredRun } from './chunk-XVIKSRCK.js';
 import { createFanOut, initFanOut } from './chunk-QNGYQMZB.js';
-import { createResilientCall } from './chunk-6XBEYZME.js';
+import { createResilientCall } from './chunk-WTSOW2MD.js';
+import { deadlinesSub, subscribeDeadline } from './chunk-C3G2QFEZ.js';
 import { rejectAll, unchecked } from './chunk-4LPY67E4.js';
-import { deadlinesSub, subscribeDeadline } from './chunk-GWWCCSDH.js';
-import { run, driveToDone } from './chunk-QWIPH4YH.js';
-import { Cmd, Outcome, cmdEdgeOf, detachWorkOf, absurd, defineMachine, validateSync, malformedResult } from './chunk-K4ETBNKS.js';
+import { run, driveToDone } from './chunk-H2ELKHI6.js';
+import { Cmd, absurd, Outcome, cmdEdgeOf, detachWorkOf, defineMachine, validateSync, malformedResult, describeError, DriveFailedError } from './chunk-AIIXV4XB.js';
 
 // src/internal/llm-call/index.ts
 function createLlmCall(config, rng = Math.random) {
@@ -145,12 +144,47 @@ function isCompactionSummary(value) {
 var compactionSummarySchema = schemaFromGuard(isCompactionSummary, "a CompactionSummary");
 
 // src/agent/internal.ts
+var NO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function freshConversation() {
   return {
     turns: [],
     toolRecords: [],
     turnCount: 0,
-    awaiting: { kind: "llm" }
+    awaiting: { kind: "llm" },
+    contextTokens: null
+  };
+}
+function addUsage(total, turn) {
+  const optional = (key) => total[key] === void 0 && turn[key] === void 0 ? {} : { [key]: (total[key] ?? 0) + (turn[key] ?? 0) };
+  return {
+    inputTokens: total.inputTokens + turn.inputTokens,
+    outputTokens: total.outputTokens + turn.outputTokens,
+    ...optional("reasoningTokens"),
+    ...optional("cachedInputTokens")
+  };
+}
+function withTurnUsage(s, conv, turn) {
+  const { usage } = turn;
+  if (usage === void 0) return [s.usage, { ...conv, contextTokens: null }];
+  return [
+    addUsage(s.usage, usage),
+    { ...conv, contextTokens: usage.inputTokens + usage.outputTokens }
+  ];
+}
+function withUsageDefaults(s) {
+  const persisted = s;
+  const conv = s.conversation;
+  const current = persisted.usage !== void 0 && (conv === null || conv.usage === void 0 && conv.contextTokens !== void 0);
+  if (current) return s;
+  let conversation = null;
+  if (conv !== null) {
+    const { usage: _lifted, ...rest } = conv;
+    conversation = { ...rest, contextTokens: rest.contextTokens ?? null };
+  }
+  return {
+    ...s,
+    usage: persisted.usage ?? conv?.usage ?? NO_USAGE,
+    conversation
   };
 }
 function dedupeByCallId(calls) {
@@ -171,7 +205,8 @@ function foldSummary(conv, folding, summaryTurn) {
     ...conv,
     turns: [summaryTurn, ...survivingTurns],
     toolRecords: survivingRecords,
-    awaiting: { kind: "llm" }
+    awaiting: { kind: "llm" },
+    contextTokens: null
   };
 }
 function currentStage(s) {
@@ -194,6 +229,70 @@ function toCompactRunCmd(cmd) {
   };
 }
 
+// src/agent/types.ts
+function isTokenCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isTurnUsage(value) {
+  if (value === null || typeof value !== "object") return false;
+  const u = value;
+  return isTokenCount(u.inputTokens) && isTokenCount(u.outputTokens) && (u.reasoningTokens === void 0 || isTokenCount(u.reasoningTokens)) && (u.cachedInputTokens === void 0 || isTokenCount(u.cachedInputTokens));
+}
+function isStreamingModel(model) {
+  return model.length >= 2;
+}
+function isToolCall(value) {
+  if (value === null || typeof value !== "object") return false;
+  const t = value;
+  return typeof t.callId === "string" && typeof t.name === "string" && t.args !== null && typeof t.args === "object";
+}
+function isAgentTurn(value) {
+  if (value === null || typeof value !== "object") return false;
+  const t = value;
+  return typeof t.content === "string" && Array.isArray(t.toolCalls) && t.toolCalls.every(isToolCall) && (t.usage === void 0 || isTurnUsage(t.usage));
+}
+var agentTurnSchema = schemaFromGuard(
+  isAgentTurn,
+  "an AgentTurn"
+);
+var TOOL_TIMEOUT_TAG = "timeout";
+var TOOL_RETRY_EXHAUSTED_TAG = "retry_exhausted";
+function status(s) {
+  if (s.failure !== null) {
+    return { kind: "failed", failure: s.failure };
+  }
+  const run2 = s.run;
+  switch (run2.phase) {
+    // 2) Never started — monitored-run's `idle` phase is exactly the "has this
+    //    actually started?" guard, and the status channel keeps that distinction.
+    case "idle":
+      return { kind: "idle" };
+    // 3) The monitored-run terminal failure (deadline / stage). `run.failure`
+    //    rides ONLY the `failed` arm of the discriminated union, so narrowing on
+    //    `phase === "failed"` surfaces it with no nullable side field and no
+    //    fabricated fallback — the old "failed-yet-failure-null" state is
+    //    unrepresentable.
+    case "failed":
+      return { kind: "failed", failure: run2.failure };
+    // 4) The pipeline finished — the terminal output landed on `state.output`.
+    case "done":
+      return { kind: "done", output: s.output, usage: s.usage ?? NO_USAGE };
+    // 5) Stopped from outside. Terminal, and deliberately NOT folded into
+    //    `failed`: the unified failure channel answers "what went wrong", and
+    //    nothing did.
+    case "cancelled":
+      return { kind: "cancelled", at: run2.at };
+    // 6) Live. Awaiting tools is the resumable shape — the outstanding calls are
+    //    the in-flight fan-out batch (`tools.running`); anything else is plain
+    //    `running`, which is also where `stale` reads (a soft mark the next
+    //    progress clears, not an outcome).
+    case "running":
+    case "stale":
+      return s.conversation !== null && s.conversation.awaiting.kind === "tools" ? { kind: "suspended", pending: s.tools.running } : { kind: "running" };
+  }
+  return absurd(run2);
+}
+
 // src/agent/machine.ts
 function agentBootMsg(at) {
   return { type: MsgType.AgentBoot, at };
@@ -201,39 +300,108 @@ function agentBootMsg(at) {
 function agentCancelMsg(at) {
   return { type: MsgType.AgentCancel, at };
 }
+var AGENT_EVENT_TYPES = [
+  "BrainStarted",
+  "TurnSettled",
+  "ToolStarted",
+  "ToolSettled",
+  "ToolFailed",
+  "RunDone"
+];
 function agentEvents(opts) {
   const tools = opts?.tools;
+  const projected = /* @__PURE__ */ new WeakSet();
   return (msg, state) => {
     const events = [];
-    if (state.run.phase === "cancelled") return events;
-    const refused = new Set(state.refusedCalls ?? []);
-    const routed = tools === void 0 ? null : tools.outcomeOf(msg);
-    if (routed !== null) {
-      if (routed.outcome.kind === "ok" && !refused.has(routed.callId)) {
-        events.push({
-          type: "ToolSettled",
-          callId: routed.callId,
-          result: routed.outcome.result
-        });
+    const run2 = state.run;
+    const runId = run2.phase === "idle" ? null : run2.runId;
+    if (runId === null) return events;
+    if (run2.phase !== "cancelled") {
+      const refused = new Set(state.refusedCalls ?? []);
+      const routed = tools === void 0 ? null : tools.outcomeOf(msg);
+      if (routed !== null) {
+        if (routed.outcome.kind === "ok" && !refused.has(routed.callId)) {
+          events.push({
+            type: "ToolSettled",
+            runId,
+            // The router claimed it, so it is one of its settled Msgs.
+            at: msg.at,
+            callId: routed.callId,
+            result: routed.outcome.result
+          });
+        }
+      } else {
+        projectOwn(msg, runId, events, refused);
       }
-    } else {
-      projectOwn(msg, events, refused);
     }
-    if (state.run.phase === "done") {
-      events.push({ type: "RunDone", output: state.output });
+    const outbox = state.lifecycle ?? [];
+    if (outbox.length === 0 || projected.has(outbox)) return events;
+    projected.add(outbox);
+    for (const note of outbox) {
+      const event = projectNote(note, runId, state);
+      if (event !== null) events.push(event);
     }
     return events;
   };
 }
-function projectOwn(msg, events, refused) {
+function turnSettled(turn, runId, at) {
+  return turn.usage === void 0 ? { type: "TurnSettled", runId, at, turn } : { type: "TurnSettled", runId, at, turn, usage: turn.usage };
+}
+function projectNote(note, runId, state) {
+  switch (note.kind) {
+    case "brain_started":
+      return {
+        type: "BrainStarted",
+        runId,
+        at: note.at,
+        turn: note.turn,
+        purpose: note.purpose,
+        model: note.model,
+        payload: inFlightPayload(state, note.purpose)
+      };
+    case "tool_started":
+      return {
+        type: "ToolStarted",
+        runId,
+        at: note.at,
+        callId: note.call.callId,
+        name: note.call.name,
+        args: note.call.args
+      };
+    case "tool_failed":
+      return {
+        type: "ToolFailed",
+        runId,
+        at: note.at,
+        callId: note.call.callId,
+        name: note.call.name,
+        failure: note.failure
+      };
+    case "run_ended": {
+      const status2 = ended(state);
+      return status2 === null ? null : { type: "RunDone", runId, at: note.at, status: status2 };
+    }
+  }
+}
+function inFlightPayload(state, key) {
+  const call = state.resilience.calls[key];
+  return call?.phase === "running" || call?.phase === "waiting_retry" ? call.input.payload : null;
+}
+function ended(state) {
+  const s = status(state);
+  return s.kind === "done" || s.kind === "failed" || s.kind === "cancelled" ? s : null;
+}
+function projectOwn(msg, runId, events, refused) {
   switch (msg.type) {
     case MsgType.ResilientOk:
-      events.push({ type: "TurnSettled", turn: msg.value.output });
+      events.push(turnSettled(msg.value.output, runId, msg.at));
       break;
     case MsgType.AgentToolOk:
       if (!refused.has(msg.callId)) {
         events.push({
           type: "ToolSettled",
+          runId,
+          at: msg.at,
           callId: msg.callId,
           result: msg.result
         });
@@ -290,7 +458,7 @@ function brainHandler(llm, ports) {
   };
 }
 
-// src/agent/tool.ts
+// src/agent/tool-cell.ts
 var REJECTED_TYPE = "tool_rejected";
 var SNAPSHOT_WRITE_TYPE = "snapshot_write";
 var SETTLE_SUFFIX = /_(?:ok|err|run)$/;
@@ -306,31 +474,22 @@ var reservedToolNames = /* @__PURE__ */ new Set([
 function isReservedToolName(name) {
   return reservedToolNames.has(name);
 }
-function tool(name, spec, handler) {
+function definedTool(door, name, spec, declaredTags, cell) {
   if (isReservedToolName(name)) {
     throw new Error(
-      `tool: "${name}" is reserved \u2014 it is an agent-owned Msg prefix`
+      `${door}: "${name}" is reserved \u2014 it is an agent-owned Msg prefix`
     );
   }
   const def = Cmd.define(name, {
-    // The router parses `args` against `spec.input` before it builds the Cmd,
-    // so the Cmd's own input schema only names the type.
     input: unchecked(),
     ok: spec.ok,
-    err: [...spec.err, "thrown"]
+    err: [...declaredTags, "thrown"]
   });
-  const declared = new Set(spec.err);
-  const settle = {
-    ok: Outcome.ok,
-    fail: Outcome.err
-  };
-  const asDeclared = (thrown) => {
-    if (isTagged(thrown) && declared.has(thrown._tag)) return thrown;
-    return { _tag: "thrown", message: describeError(thrown) };
-  };
+  const declared = new Set(declaredTags);
+  const asDeclared = (thrown) => isTagged(thrown) && declared.has(thrown._tag) ? thrown : { _tag: "thrown", message: describeError(thrown) };
   const interpret = async (cmd, ctx) => {
     try {
-      return await handler(cmd.args, ctx, settle);
+      return await cell(cmd, ctx);
     } catch (thrown) {
       return Outcome.err(asDeclared(thrown));
     }
@@ -339,6 +498,7 @@ function tool(name, spec, handler) {
     description: spec.description,
     args: spec.input,
     resilience: resilienceOf(spec),
+    content: spec.content ?? null,
     interpret
   });
 }
@@ -352,6 +512,21 @@ function resilienceOf(spec) {
 function isTagged(value) {
   return typeof value === "object" && value !== null && typeof value._tag === "string";
 }
+
+// src/agent/tool.ts
+function tool(name, spec, handler) {
+  const settle = {
+    ok: Outcome.ok,
+    fail: Outcome.err
+  };
+  return definedTool(
+    "tool",
+    name,
+    spec,
+    spec.err,
+    (cmd, ctx) => handler(cmd.args, ctx, settle)
+  );
+}
 var rejected = Cmd.define(REJECTED_TYPE, {
   input: unchecked(),
   ok: rejectAll,
@@ -426,7 +601,14 @@ function toolRouter(tools) {
     return null;
   };
   const resilienceOf2 = (call) => byName.get(call.name)?.resilience ?? null;
-  return { defs, toolOf, interpret, outcomeOf, resilienceOf: resilienceOf2 };
+  const partsOf = (call, outcome) => {
+    const content = byName.get(call.name)?.content ?? null;
+    if (content === null || outcome.kind !== "ok") return null;
+    return content(
+      outcome.result
+    );
+  };
+  return { defs, toolOf, interpret, outcomeOf, resilienceOf: resilienceOf2, partsOf };
 }
 function fanOutInterpret(interpret) {
   let release = Promise.resolve();
@@ -459,62 +641,6 @@ function toolErrorReason(error) {
   return Object.keys(detail).length === 0 ? _tag : `${_tag} ${JSON.stringify(detail)}`;
 }
 
-// src/agent/types.ts
-function isStreamingModel(model) {
-  return model.length >= 2;
-}
-function isToolCall(value) {
-  if (value === null || typeof value !== "object") return false;
-  const t = value;
-  return typeof t.callId === "string" && typeof t.name === "string" && t.args !== null && typeof t.args === "object";
-}
-function isAgentTurn(value) {
-  if (value === null || typeof value !== "object") return false;
-  const t = value;
-  return typeof t.content === "string" && Array.isArray(t.toolCalls) && t.toolCalls.every(isToolCall);
-}
-var agentTurnSchema = schemaFromGuard(
-  isAgentTurn,
-  "an AgentTurn"
-);
-var TOOL_TIMEOUT_TAG = "timeout";
-var TOOL_RETRY_EXHAUSTED_TAG = "retry_exhausted";
-function status(s) {
-  if (s.failure !== null) {
-    return { kind: "failed", failure: s.failure };
-  }
-  const run2 = s.run;
-  switch (run2.phase) {
-    // 2) Never started — monitored-run's `idle` phase is exactly the "has this
-    //    actually started?" guard, and the status channel keeps that distinction.
-    case "idle":
-      return { kind: "idle" };
-    // 3) The monitored-run terminal failure (deadline / stage). `run.failure`
-    //    rides ONLY the `failed` arm of the discriminated union, so narrowing on
-    //    `phase === "failed"` surfaces it with no nullable side field and no
-    //    fabricated fallback — the old "failed-yet-failure-null" state is
-    //    unrepresentable.
-    case "failed":
-      return { kind: "failed", failure: run2.failure };
-    // 4) The pipeline finished — the terminal output landed on `state.output`.
-    case "done":
-      return { kind: "done", output: s.output };
-    // 5) Stopped from outside. Terminal, and deliberately NOT folded into
-    //    `failed`: the unified failure channel answers "what went wrong", and
-    //    nothing did.
-    case "cancelled":
-      return { kind: "cancelled", at: run2.at };
-    // 6) Live. Awaiting tools is the resumable shape — the outstanding calls are
-    //    the in-flight fan-out batch (`tools.running`); anything else is plain
-    //    `running`, which is also where `stale` reads (a soft mark the next
-    //    progress clears, not an outcome).
-    case "running":
-    case "stale":
-      return s.conversation !== null && s.conversation.awaiting.kind === "tools" ? { kind: "suspended", pending: s.tools.running } : { kind: "running" };
-  }
-  return absurd(run2);
-}
-
 // src/agent/tool-resilience.ts
 var TOOL_KEY_PREFIX = "$tool:";
 var NAME_CALL_SEP = "#";
@@ -718,6 +844,75 @@ function taggedFailure(tagged) {
   return { ...tagged, reason: toolErrorReason(tagged), kind: "error" };
 }
 
+// src/agent/agent-tool.ts
+var AGENT_TOOL_TAGS = [
+  "child_failed",
+  "child_cancelled"
+];
+function agentTool(name, spec) {
+  const runChild = spec.agent.run;
+  const childCtx = spec.childCtx;
+  return definedTool(
+    "agentTool",
+    name,
+    { description: spec.description, input: spec.input, ok: spec.ok },
+    AGENT_TOOL_TAGS,
+    async (cmd, ctx) => {
+      const childRunId = `${spec.namespace(ctx)}/${cmd.callId}`;
+      const opts = {
+        store: spec.store(childRunId, ctx),
+        runId: childRunId,
+        ...childCtx === void 0 ? {} : { ctx: childCtx(ctx) }
+      };
+      let final;
+      try {
+        final = await runChild(spec.prompt(cmd.args), opts);
+      } catch (error) {
+        if (!(error instanceof DriveFailedError)) throw error;
+        return Outcome.err(childFailed(childRunId, error.state));
+      }
+      if (final.run.phase === "cancelled") {
+        return Outcome.err({ _tag: "child_cancelled", childRunId });
+      }
+      if (final.output === null) {
+        throw new Error(
+          `agentTool: child run "${childRunId}" ended done with no output`
+        );
+      }
+      return Outcome.ok(spec.result(final.output));
+    }
+  );
+}
+function childFailed(childRunId, state) {
+  const s = status(state);
+  if (s.kind !== "failed") {
+    throw new Error(
+      `agentTool: child run "${childRunId}" rejected on a ${s.kind} Model`
+    );
+  }
+  return { _tag: "child_failed", childRunId, failure: s.failure.reason };
+}
+
+// src/agent/content.ts
+function contentParts(content) {
+  return typeof content === "string" ? [{ type: "text", text: content }] : content;
+}
+var IMAGE_OMITTED = "[image omitted]";
+var FILE_OMITTED = "[file omitted]";
+function omitMedia(parts) {
+  return parts.map(placeholderOf);
+}
+function placeholderOf(part) {
+  switch (part.type) {
+    case "text":
+      return part;
+    case "image":
+      return { type: "text", text: IMAGE_OMITTED };
+    case "file":
+      return { type: "text", text: FILE_OMITTED };
+  }
+}
+
 // src/agent/define-agent.ts
 function defineAgent(config) {
   const router = toolRouter(config.tools);
@@ -737,7 +932,7 @@ function definedAgent(config, wiring, overlays) {
       model: brain,
       instructions: config.instructions,
       payloadOf: promptOf,
-      loadMessages: messagesOf,
+      loadMessages: messagesOf(tools.partsOf),
       toolOf: tools.toolOf,
       // The per-tool timeout / retry knob (#117). The lid grows no option for
       // it: the policy is declared on the `tool()` that needs it, and the
@@ -797,9 +992,9 @@ function definedAgent(config, wiring, overlays) {
     };
     const signal = opts.signal;
     if (signal === void 0) {
-      return ended(driveToDone(handle, begin, isEnded, { failed: isFailed }));
+      return ended2(driveToDone(handle, begin, isEnded, { failed: isFailed }));
     }
-    return ended(
+    return ended2(
       driveToDone(handle, begin, isEnded, {
         failed: isFailed,
         signal,
@@ -855,7 +1050,7 @@ function compactingMachine(core, knob, brain, tools) {
   const agent = createAgent({ ...core, compaction: compactionPolicyOf(knob) });
   const wiring = {
     tools,
-    toolInterpret: { compact_run: summarizeWith(brain) }
+    toolInterpret: { compact_run: summarizeWith(brain, tools.partsOf) }
   };
   return agent.toMachine(
     wiring
@@ -865,7 +1060,7 @@ var SUMMARIZE_INSTRUCTION = "Summarize the conversation so far. Preserve the fac
 function compactionPolicyOf(knob) {
   const keep = knob.keepTurns ?? 0;
   return {
-    planCompaction: (conversation) => conversation.turns.length >= knob.afterTurns ? Math.max(0, conversation.turns.length - keep) : 0,
+    planCompaction: (conversation) => isCompactionDue(knob, conversation) ? Math.max(0, conversation.turns.length - keep) : 0,
     payloadOf: (conversation, folding) => ({
       instructions: SUMMARIZE_INSTRUCTION,
       input: null,
@@ -877,10 +1072,15 @@ function compactionPolicyOf(knob) {
     })
   };
 }
-function summarizeWith(model) {
+function isCompactionDue(knob, conversation) {
+  const { afterTurns, afterContextTokens } = knob;
+  const { contextTokens } = conversation;
+  return afterTurns !== void 0 && conversation.turns.length >= afterTurns || afterContextTokens !== void 0 && contextTokens !== null && contextTokens >= afterContextTokens;
+}
+function summarizeWith(model, partsOf) {
   return async (cmd) => {
     const payload = cmd.input.payload;
-    const turn = await model(renderPrompt(payload));
+    const turn = await model(renderPrompt(payload, partsOf).map(withoutMedia));
     return {
       type: MsgType.CompactOk,
       key: COMPACTION_PURPOSE,
@@ -896,8 +1096,10 @@ function summarizeWith(model) {
 function promptOf(stage, conversation, instructions) {
   return { instructions, input: stage ?? null, conversation };
 }
-var messagesOf = async (call) => renderPrompt(call.payload);
-function renderPrompt(prompt) {
+function messagesOf(partsOf) {
+  return async (call) => renderPrompt(call.payload, partsOf);
+}
+function renderPrompt(prompt, partsOf = noParts) {
   const head = [];
   if (prompt.instructions !== null) {
     head.push({ role: "system", content: prompt.instructions });
@@ -908,15 +1110,32 @@ function renderPrompt(prompt) {
   const { turns, toolRecords } = prompt.conversation;
   const transcript2 = turns.flatMap((turn, i) => [
     assistantOf(turn),
-    ...toolRecords.filter((r) => r.turn === i).map((r) => ({
-      role: "tool",
-      callId: r.call.callId,
-      name: r.call.name,
-      outcome: r.outcome
-    }))
+    ...toolRecords.filter((r) => r.turn === i).map((r) => {
+      const message = {
+        role: "tool",
+        callId: r.call.callId,
+        name: r.call.name,
+        outcome: r.outcome
+      };
+      const parts = partsOf(r.call, r.outcome);
+      return parts === null ? message : { ...message, parts };
+    })
   ]);
   return [...head, ...transcript2];
 }
+function noParts() {
+  return null;
+}
+function withoutMedia(message) {
+  switch (message.role) {
+    case "user":
+      return typeof message.content === "string" ? message : { ...message, content: omitMedia(message.content) };
+    case "tool":
+      return message.parts === void 0 ? message : { ...message, parts: omitMedia(message.parts) };
+    default:
+      return message;
+  }
+}
 function assistantOf(turn) {
   const { content, toolCalls } = turn;
   return "provider" in turn ? { role: "assistant", content, toolCalls, provider: turn.provider } : { role: "assistant", content, toolCalls };
@@ -924,7 +1143,6 @@ function assistantOf(turn) {
 function noHost() {
   return {};
 }
-var AGENT_EVENT_TYPES = ["TurnSettled", "ToolSettled", "RunDone"];
 function forwardEvents(handle, onEvent) {
   const deliver = contained("onEvent", onEvent);
   for (const type of AGENT_EVENT_TYPES) {
@@ -997,7 +1215,7 @@ function isMidRun(s) {
 function isEnded(s) {
   return s.run.phase === "done" || s.run.phase === "cancelled";
 }
-function ended(drive) {
+function ended2(drive) {
   return drive;
 }
 function isFailed(s) {
@@ -1021,7 +1239,13 @@ function transcript(seed) {
           tools.push({ callId: event.callId, result: event.result });
           return;
         case "RunDone":
-          outcome = { kind: "done", output: event.output };
+          outcome = event.status;
+          return;
+        // The started and failed events add nothing a transcript keeps: a
+        // turn is kept once it settles, and a failed call is `onToolError`'s.
+        case "BrainStarted":
+        case "ToolStarted":
+        case "ToolFailed":
           return;
       }
     },
@@ -1065,9 +1289,11 @@ function createAgent(config) {
       resilience: llm.init(),
       tools: initFanOut(),
       conversation: null,
+      usage: NO_USAGE,
       compaction: compactRc.init(),
       toolResilience: ladder.init(),
       refusedCalls: [],
+      lifecycle: [],
       failure: null,
       output: null,
       instructions: config.instructions ?? null
@@ -1086,7 +1312,21 @@ function createAgent(config) {
   function fireBrainCall(s, at) {
     const call = brainCall(s);
     const [resilience, cmds] = llm.attempt(s.resilience, call, at);
-    return [{ ...s, resilience }, cmds];
+    const started = noted(s, {
+      kind: "brain_started",
+      turn: s.conversation?.turnCount ?? 0,
+      purpose: call.purpose,
+      model: call.model,
+      at
+    });
+    return [{ ...started, resilience }, cmds];
+  }
+  function noted(s, ...notes) {
+    if (notes.length === 0) return s;
+    return { ...s, lifecycle: [...s.lifecycle ?? [], ...notes] };
+  }
+  function toolsStarted(calls, at) {
+    return calls.map((call) => ({ kind: "tool_started", call, at }));
   }
   function compactionCall(conv, folding) {
     const payloadOf = config.compaction?.payloadOf;
@@ -1115,6 +1355,8 @@ function createAgent(config) {
       ...s,
       run: runSlice,
       conversation,
+      // A new run has cost nothing yet (#332).
+      usage: NO_USAGE,
       failure: null,
       // A restart clears the prior run's terminal output — `result()` reads
       // `undefined` again until THIS run finishes (#46).
@@ -1132,12 +1374,14 @@ function createAgent(config) {
   function turn(s, result, at) {
     const conv = requireAwaiting(s, "llm");
     if (conv === null) return [s, []];
+    const [usage, measured] = withTurnUsage(s, conv, result);
     const withTurn = {
-      ...conv,
+      ...measured,
       turns: [...conv.turns, result]
     };
+    const counted = { ...s, usage };
     if (result.toolCalls.length === 0) {
-      return advanceStage({ ...s, conversation: withTurn }, result, at);
+      return advanceStage({ ...counted, conversation: withTurn }, result, at);
     }
     const batch = dedupeByCallId(result.toolCalls);
     const [tools] = fan.scatter(initFanOut(), batch);
@@ -1146,9 +1390,23 @@ function createAgent(config) {
       awaiting: { kind: "tools", batchTurn: withTurn.turnCount }
     };
     const [runSlice] = run2.progress(s.run, void 0, at);
-    const [toolResilience, launchCmds] = armLaunch(s, [], tools.running, at);
+    const [toolResilience, launchCmds, launched] = armLaunch(
+      s,
+      [],
+      tools.running,
+      at
+    );
     return [
-      { ...s, run: runSlice, tools, toolResilience, conversation: nextConv },
+      noted(
+        {
+          ...counted,
+          run: runSlice,
+          tools,
+          toolResilience,
+          conversation: nextConv
+        },
+        ...toolsStarted(launched, at)
+      ),
       launchCmds
     ];
   }
@@ -1205,11 +1463,9 @@ function createAgent(config) {
   }
   function armLaunch(s, before, after, at) {
     const known = new Set(before.map((c) => c.callId));
-    return ladder.launch(
-      toolSlice(s),
-      after.filter((c) => !known.has(c.callId)),
-      at
-    );
+    const launched = after.filter((c) => !known.has(c.callId));
+    const [slice, cmds] = ladder.launch(toolSlice(s), launched, at);
+    return [slice, cmds, launched];
   }
   function settleTool(prev, callId, outcome, at) {
     const conv = requireAwaiting(prev, "tools");
@@ -1217,14 +1473,18 @@ function createAgent(config) {
     const call = prev.tools.running.find((c) => c.callId === callId);
     if (call === void 0) return [prev, []];
     const [tools] = outcome.kind === "ok" ? fan.itemOk(prev.tools, callId, outcome) : fan.itemErr(prev.tools, callId, outcome);
-    const [toolResilience, launchCmds] = armLaunch(
+    const [toolResilience, launchCmds, launched] = armLaunch(
       prev,
       prev.tools.running,
       tools.running,
       at
     );
     const refusedCalls = outcome.kind === "ok" ? refusedOf(prev) : [...refusedOf(prev), callId];
-    const s = { ...prev, toolResilience, refusedCalls };
+    const s = noted(
+      { ...prev, toolResilience, refusedCalls },
+      ...outcome.kind === "ok" ? [] : [{ kind: "tool_failed", call, failure: outcome, at }],
+      ...toolsStarted(launched, at)
+    );
     const foldedConv = {
       ...conv,
       // Stamp the producing-turn index on the record (#85, A1). At settle time
@@ -1383,29 +1643,34 @@ function createAgent(config) {
   }
   function boot(s, at) {
     const [runSlice] = run2.boot(s.run, at);
-    const rebooted = { ...s, run: runSlice };
-    if (isSettled(rebooted)) return [rebooted, []];
-    const conv = rebooted.conversation;
-    if (conv === null) return [rebooted, []];
+    const resumed = { ...s, run: runSlice };
+    if (isSettled(resumed)) return [resumed, []];
+    const conv = resumed.conversation;
+    if (conv === null) return [resumed, []];
     if (conv.awaiting.kind === "llm") {
-      return fireBrainCall(rebooted, at);
+      return fireBrainCall(resumed, at);
     }
     if (conv.awaiting.kind === "compacting") {
       const input = compactionCall(conv, conv.awaiting.folding);
       const [compaction, cmds] = compact.attempt(
-        rebooted.compaction,
+        resumed.compaction,
         COMPACTION_PURPOSE,
         input,
         at
       );
-      return [{ ...rebooted, compaction }, cmds];
+      return [{ ...resumed, compaction }, cmds];
     }
     const [toolResilience, outcome] = ladder.boot(
-      toolSlice(rebooted),
-      rebooted.tools.running,
+      toolSlice(resumed),
+      resumed.tools.running,
+      at
+    );
+    return applyLadder(
+      noted(resumed, ...toolsStarted(resumed.tools.running, at)),
+      toolResilience,
+      outcome,
       at
     );
-    return applyLadder(rebooted, toolResilience, outcome, at);
   }
   function cancel(s, at) {
     const [runSlice] = run2.cancel(s.run, at);
@@ -1435,31 +1700,32 @@ function createAgent(config) {
       if (settled === void 0 || settled === null) return [s, []];
       return settled.outcome.kind === "ok" ? toolOk(s, settled.callId, settled.outcome.result, m.at) : toolErr(s, settled.callId, settled.outcome, m.at);
     };
+    const toolCell = (s, m) => transition(s, m.at, (entered) => foldTool(entered, m));
     const toolCells = {};
     for (const def of tools?.defs ?? []) {
-      toolCells[def.okType] = foldTool;
-      toolCells[def.errType] = foldTool;
+      toolCells[def.okType] = toolCell;
+      toolCells[def.errType] = toolCell;
     }
     const ownUpdate = {
-      [MsgType.AgentStart]: (s, m) => start(s, m.runId, m.at),
-      [MsgType.AgentToolOk]: (s, m) => toolOk(s, m.callId, m.result, m.at),
+      [MsgType.AgentStart]: (s, m) => door.start(s, m.runId, m.at),
+      [MsgType.AgentToolOk]: (s, m) => door.toolOk(s, m.callId, m.result, m.at),
       // `agent_tool_err` is `createAgent`'s own raw settle Msg and its wire
       // shape is a bare `reason` string — a consumer routing their own interpret
       // through it never declared a tag, so the failure it mints carries none.
-      [MsgType.AgentToolErr]: (s, m) => toolErr(s, m.callId, m.reason, m.at),
+      [MsgType.AgentToolErr]: (s, m) => door.toolErr(s, m.callId, m.reason, m.at),
       // The engine-minted brain-call settle Msgs (from `brainHandlers`' outcome):
       // success runs `succeed` (reset retry + fold the turn), failure runs `fail`.
-      [MsgType.ResilientOk]: (s, m) => succeed(s, m, m.at),
-      [MsgType.ResilientErr]: (s, m) => fail(s, m, m.at),
+      [MsgType.ResilientOk]: (s, m) => door.succeed(s, m, m.at),
+      [MsgType.ResilientErr]: (s, m) => door.fail(s, m, m.at),
       // The re-entered compaction settle Msgs (from the consumer's `compact_run`
       // cell, #85): `compact_ok` folds the summary back (drop oldest turns +
       // their records, fire the next brain call), `compact_err` backs off via the
       // compaction retry or proceeds without compacting.
-      [MsgType.CompactOk]: (s, m) => compactOk(s, m.key, m, m.at),
-      [MsgType.CompactErr]: (s, m) => compactErr(s, m.key, m, m.at),
-      deadline_exceeded: (s, m) => onTimer(s, m),
-      [MsgType.AgentBoot]: (s, m) => boot(s, m.at),
-      [MsgType.AgentCancel]: (s, m) => cancel(s, m.at)
+      [MsgType.CompactOk]: (s, m) => door.compactOk(s, m.key, m, m.at),
+      [MsgType.CompactErr]: (s, m) => door.compactErr(s, m.key, m, m.at),
+      deadline_exceeded: (s, m) => door.onTimer(s, m),
+      [MsgType.AgentBoot]: (s, m) => door.boot(s, m.at),
+      [MsgType.AgentCancel]: (s, m) => transition(s, m.at, (entered) => cancel(entered, m.at))
     };
     const update = { ...ownUpdate, ...toolCells };
     const machine = {
@@ -1477,18 +1743,27 @@ function createAgent(config) {
       subscribe: { deadline: subscribeDeadline }
     };
   }
+  function transition(s, at, verb) {
+    const current = withUsageDefaults(s);
+    const entered = (current.lifecycle ?? []).length === 0 ? current : { ...current, lifecycle: [] };
+    const [next, cmds] = verb(entered);
+    return !isSettled(entered) && isSettled(next) ? [noted(next, { kind: "run_ended", at }), cmds] : [next, cmds];
+  }
+  const door = {
+    start: (s, runId, at) => transition(s, at, (e) => start(e, runId, at)),
+    turn: (s, result, at) => transition(s, at, (e) => turn(e, result, at)),
+    toolOk: (s, callId, result, at) => transition(s, at, (e) => toolOk(e, callId, result, at)),
+    toolErr: (s, callId, failure, at) => transition(s, at, (e) => toolErr(e, callId, failure, at)),
+    succeed: (s, msg, at) => transition(s, at, (e) => succeed(e, msg, at)),
+    fail: (s, msg, at) => transition(s, at, (e) => fail(e, msg, at)),
+    compactOk: (s, key, msg, at) => transition(s, at, (e) => compactOk(e, key, msg, at)),
+    compactErr: (s, key, msg, at) => transition(s, at, (e) => compactErr(e, key, msg, at)),
+    onTimer: (s, msg) => transition(s, msg.atMs, (e) => onTimer(e, msg)),
+    boot: (s, at) => transition(s, at, (e) => boot(e, at))
+  };
   return {
     init,
-    start,
-    turn,
-    toolOk,
-    toolErr,
-    succeed,
-    fail,
-    compactOk,
-    compactErr,
-    onTimer,
-    boot,
+    ...door,
     isSettled,
     currentStage,
     brainCall,
@@ -1501,6 +1776,6 @@ function createAgent(config) {
   };
 }
 
-export { COMPACTION_PURPOSE, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTurnSchema, compactionSummarySchema, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, liftAgent, mergeInterpret, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript };
-//# sourceMappingURL=chunk-XBZQT2TD.js.map
-//# sourceMappingURL=chunk-XBZQT2TD.js.map
+export { AGENT_EVENT_TYPES, COMPACTION_PURPOSE, FILE_OMITTED, IMAGE_OMITTED, PLAIN_MODEL_MISROUTE_REASON, TOOL_RETRY_EXHAUSTED_TAG, TOOL_TIMEOUT_TAG, agentBootMsg, agentCancelMsg, agentEvents, agentTool, agentTurnSchema, compactionSummarySchema, contentParts, createAgent, defineAgent, fanOutInterpret, isAgentTurn, isCompactionSummary, isReservedToolName, isStreamingModel, isTurnUsage, liftAgent, mergeInterpret, omitMedia, plainModel, renderPrompt, status, tool, toolErrorReason, toolRouter, transcript };
+//# sourceMappingURL=chunk-PCJA2HTZ.js.map
+//# sourceMappingURL=chunk-PCJA2HTZ.js.map