@juno-ai/bind 8.0.0 → 10.0.0

package/README.md

@@ -29,6 +29,86 @@ constraints that will fail CI if you break them.
 
 ---
 
+## Changelog
+
+### Unreleased
+
+**Breaking**
+
+- `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
+  of `void`. A caller that ignores the return value is unchanged, but a
+  wrapper *annotated* `Promise<void>` no longer typechecks — widen it to
+  `Promise<ToolLoopResult>`.
+- `RunStats` gained `cachedInputTokens`. `emptyRunStats()` and the folds set it;
+  code that hand-builds a `RunStats` literal must add the field. `ToolLoopTurn`
+  and `CompactionApplied` gained a matching optional `cachedInputTokens`, so
+  the loop can actually populate it — return it from `callModel` if your
+  transport reports one.
+- `MissingActivationPortError` — a tool outcome that asks the loop to activate
+  a plugin or skill while the matching port is unwired is now reported through
+  `onToolCallRejected` instead of being dropped in silence. The run still
+  completes; the wiring bug is no longer invisible.
+- `defineTool` no longer applies `normalizeArgs` inside `execute`.
+  Normalization is the dispatcher's step (it runs before the idempotency
+  hash), and applying it in both places applied it twice.
+- **`StopReason` no longer has `suspended`.** It split into
+  `waiting_for_reply` (a tool asked a human a question; nothing happens until
+  someone answers) and `resuming_later` (a tool scheduled its own resume).
+  Removing a union member breaks any exhaustive `switch`, so map both new
+  values wherever you handled `suspended` — and note that the old single value
+  could not tell them apart at all, which is why it was split.
+- **`@juno-ai/bind/plugins` now loads `zod` at runtime.** The barrel re-exports
+  `defineTool` / `pluginFromTools`, and `toolWireDefinition` needs
+  `z.toJSONSchema`. Every other module in the subpath was previously
+  runtime-zod-free, so a consumer importing only `createToolRegistry` while
+  ignoring the peer-dependency warning now fails to resolve. `zod` is a
+  required (non-optional) peer, so a correctly-installed consumer is
+  unaffected. `@juno-ai/bind/loop` is deliberately still zod-free — which is
+  why `toolResultMessage` lives in its own type-only module.
+
+**Added**
+
+- `ToolLoopResult.stopReason` — `done` / `waiting_for_reply` / `resuming_later`
+  / `iteration_limit` / `aborted`, one per exit, replacing the two or three
+  loop-state flags every host was combining differently. The two pause reasons
+  are separate values on purpose: one needs a person to act and the other does
+  not, and that is the distinction a host most needs to surface. `deadline` stays in the `StopReason` union
+  for a host classifying a thrown `RunTimeoutError`; the loop cannot return it,
+  and the type's doc comment says why.
+- `ToolLoopResult.stats` — a `RunStats` the loop folds itself: turns,
+  dispatched tool calls, tokens, cost, and the model-time/tool-time split with
+  a per-tool breakdown. A compaction contributes its spend but not a turn
+  (`accumulateAuxiliarySpend`, also new), so `stats.turns` stays comparable
+  with `maxIterations`. `ToolLoopParams.now` injects the clock.
+- `@juno-ai/bind/testing` — the scripted-model fixtures this package's own
+  cross-module suites use: `loopHarness`, `scriptedModel`, `toolCallTurn`,
+  `finalAnswer`, `toolCall`, `freshState`, `recordingSink`, `steppingClock`.
+  Credential-free multi-turn, multi-tool tests without mocking a chat client.
+- `defineTool` / `pluginFromTools` (`@juno-ai/bind/plugins`) — author a tool as
+  `{ name, description, schema, execute }` and get argument parsing, a
+  `validation` failure the model can act on, and typed `args` in `execute`.
+  Plus `toolWireDefinition` (zod → sanitized JSON Schema) and
+  `toolResultMessage` (the `role:"tool"` encoding the loop itself uses).
+- `ToolLoopParams.activePlugins`, `activatePlugins` and `activateSkills` are
+  now optional. A host with a fixed tool surface had been required to supply
+  empty functions; `activePlugins` was never read by the loop at all.
+
+- `runToolCallsPooledByTool` accepts an optional `signal`, and
+  `AbortedToolCallError` / `ToolBatchOptions` are exported from
+  `@juno-ai/bind/run`. Additive — a caller that passes nothing is unchanged, and
+  a test pins that. A batch that *is* given one stops claiming queued calls once
+  it aborts, and those come back `rejected` with an `AbortedToolCallError`
+  (`kind: "not_run"` once the loop synthesizes them), so a caller relying on
+  every call always executing simply does not pass a signal.
+
+- `createTurnTextStream` (`@juno-ai/bind/completion`) — streams a turn's
+  assistant text to a live surface and repairs it across routing retries. A
+  retractable surface keeps the whole fallback chain; a permanent one clamps as
+  before. See "How to stream tokens to a user without breaking fallback".
+- `ToolLoopParams.signal` — bounds the tool batch. Without it the deadline and
+  cancellation ports are only consulted between iterations, so a budget that
+  expired during the model call still let the batch run its side effects.
+
 ## Explanation
 
 *Understanding-oriented. Read this to know why the package is shaped the way it
@@ -275,26 +355,165 @@ const state: ToolLoopState = {
   toolCalls: 0,
 };
 
-await runToolLoop({
+const { stopReason, stats } = await runToolLoop({
   state,
-  activePlugins,
   maxIterations: 30,
 
   callModel: (messages, tools) => llm.complete({ messages, tools }),
   buildTools: () => registry.toolDefinitions([...activePlugins]),
   runToolCall: (call) => dispatch(call),
+
+  // Only if your tools can change the tool surface mid-run:
   activatePlugins: (names) => names.forEach((n) => activePlugins.add(n)),
   activateSkills: (refs) => loadInstructions(refs),
 });
 
-// `state` is mutated in place — read totals off it after, or mid-run from a
-// heartbeat.
+// `state` is mutated in place — read totals off it mid-run from a heartbeat.
 console.log(state.inputTokens, state.outputTokens, state.toolCalls);
+
+// The result is the run's conclusion, which only exists once it is over.
+await persistRun({ stopReason, ...stats });
 ```
 
-`state` is mutated rather than returned so a heartbeat can read live totals while
-the run is still going; a returned result could not report anything until the
-run ended.
+The two halves are deliberate. `state` is mutated rather than returned so a
+heartbeat can read live totals while the run is still going; `ToolLoopResult`
+is what could not exist until the run ended.
+
+`stopReason` is the whole outcome, in one word:
+
+| Reason | The model | What a host should say |
+|---|---|---|
+| `done` | Stopped calling tools | It answered |
+| `waiting_for_reply` | A tool asked a human a question | It needs you to answer — nothing happens until you do |
+| `resuming_later` | A tool scheduled its own resume | It paused on purpose and will come back |
+| `iteration_limit` | Still calling tools at the ceiling | It ran out of room, mid-task |
+| `aborted` | Cut off by `shouldStop` or the batch `signal` | It was stopped |
+
+The two pause reasons are separate values because their consequences differ
+more than any other pair: one needs a person to act, the other needs nobody to.
+Collapsed into one `suspended`, a host that wanted to say which had to go back
+and read `state.suspended` — the loop-state-flag reconstruction this return
+value exists to replace.
+
+`deadline` is in the `StopReason` union but never returned: the wall-clock port
+(`throwIfTimedOut`) is throw-based, so an expired budget leaves the loop as a
+`RunTimeoutError` your catch block maps — `classifyRunFailure` recognises the
+same condition. The loop returns `aborted` for a fired signal because once a
+deadline and a cancellation are combined into one `AbortSignal` it genuinely
+cannot tell which one fired.
+
+`stats` is a `RunStats`: turns, dispatched tool calls, tokens (including
+provider-reported cached input, when your `callModel` returns a
+`cachedInputTokens`), cost, and model time vs tool time with a per-tool
+breakdown. Three things are worth reading carefully:
+
+- **`stats` is this invocation's contribution; `state` is whatever you seeded
+  plus that.** They match only if you seeded zeros. A host resuming a run seeds
+  `state` from the stored totals, and then `state.costCents` is the run's
+  lifetime cost while `stats.costCents` is this leg's — bill from whichever you
+  mean, and don't substitute one for the other.
+
+- **`stats.toolCalls` counts calls that *ran*; `state.toolCalls` counts calls
+  the model *requested*.** They differ by exactly the work an aborted batch
+  prevented, which is why they are two numbers.
+- **A compaction contributes tokens, cost and model time but not a turn**, so
+  `stats.turns` stays comparable with `maxIterations`.
+
+Both are lost if the loop throws: a deadline, a cancellation, or a fatal tool
+error leaves no return value, so `state` — mutated in place — is the only
+accounting that survives those exits.
+
+Pass `now` to make either measurement deterministic in a test; it defaults to
+`Date.now`.
+
+### How to test an agent without a provider
+
+`@juno-ai/bind/testing` ships the fixtures this package's own cross-module
+suites use. A scripted model is a queue of prepared turns, so a multi-turn,
+multi-tool test needs no credential, no network, and no mocked chat client.
+
+```ts
+import { runToolLoop } from "@juno-ai/bind/loop";
+import {
+  loopHarness, toolCall, toolCallTurn, finalAnswer,
+} from "@juno-ai/bind/testing";
+
+const h = loopHarness([
+  toolCallTurn([toolCall("search", { q: "bind" }), toolCall("read_file")]),
+  toolCallTurn([toolCall("write_file", { path: "out.md" })]),
+  finalAnswer("Done."),
+]);
+
+const { stopReason, stats } = await runToolLoop(h.params);
+
+expect(stopReason).toBe("done");
+expect(stats.turns).toBe(3);
+expect(h.ran).toEqual(["search", "read_file", "write_file"]);
+```
+
+Every field of `h.params` is overridable, which is how you reach the
+interesting states — `{ runToolCall }` to make one tool fail, `{ signal }` to
+abort mid-batch, `{ now }` to make the timing figures deterministic
+(`steppingClock()` for a fixed tick, or your own closure advanced inside
+`runToolCall` when you want to *choose* each interval).
+`h.ran` records what the loop *dispatched* and `h.sideEffects` what actually
+*completed*; the gap between them is the answer to every cancellation question.
+
+Two failure modes are deliberate. A script that runs out throws rather than
+returning an empty turn — otherwise `maxIterations` absorbs the mistake and the
+test passes while describing a run that never happened. And a duplicate
+tool-call id throws at construction, rather than producing a transcript the
+provider rejects ten frames deep in the loop.
+
+### How to author a tool without writing dispatch by hand
+
+A `ToolPlugin` dispatches by tool name, which is right for a bundle with shared
+setup and pure ceremony for a flat list of independent tools. `defineTool` does
+the mechanical half — parse the arguments, turn a parse failure into something
+the model can act on — and `pluginFromTools` bundles the result.
+
+```ts
+import { defineTool, pluginFromTools } from "@juno-ai/bind/plugins";
+
+const search = defineTool({
+  name: "search",
+  description: "Search the corpus.",
+  schema: z.object({ query: z.string().min(1), limit: z.number().default(10) }),
+  // `args` is typed from the schema; `limit` has already defaulted.
+  execute: async (args, ctx: Ctx) => ({
+    success: true,
+    data: await corpus.search(args.query, args.limit, ctx.tenantId),
+  }),
+});
+
+const plugin = pluginFromTools<Ctx>({
+  name: "corpus",
+  description: "Corpus tools.",
+  tools: [search],
+});
+```
+
+The schema is the single source of truth: it is converted to JSON Schema for
+the model *and* used to validate what comes back, so the two cannot drift.
+
+Bad arguments come back as `{ success: false, kind: "validation", error }`
+naming the offending path — **returned, not thrown**. That distinction is the
+bug this replaces: a thrown parse error turns a recoverable "you passed the
+wrong field" into a dead run. An unknown tool name is likewise a returned
+`not_found`, because a resumed session's history can reference a tool you have
+since retired.
+
+The validation lives on the tool, not on the bundle, so a host with its own
+dispatcher can call `search.execute(rawArgs, ctx)` directly and get the same
+guarantee — `pluginFromTools` only resolves names.
+
+Two encoders come with it. `toolWireDefinition(tool, wireName?)` converts a
+tool to what the provider is shown, through `sanitizeToolSchema` — `wireName`
+because tool naming is host policy (Monad encodes `plugin__tool` to route a
+call back to its plugin). `toolResultMessage(callId, result)` produces the
+`role:"tool"` message, using the same encoding the loop synthesizes for a
+failed or refused call — so a model never has to learn two error formats in one
+transcript.
 
 ### How to make a tool take effect mid-batch
 
@@ -572,54 +791,160 @@ never happened.
 
 ### How to stream tokens to a user without breaking fallback
 
-Content never passes through this package — `callModel` and `AttemptFn` are
-*your* functions, so forwarding deltas from inside them is already supported and
-needs nothing from here. What the package gives you is three granularities and
-one rule.
+Three granularities reach you, and the third is the one with a retry problem.
 
 | You want | Use |
 |---|---|
 | Each assistant message as it lands | `onAssistantMessage(content)` on the loop — fires per message, including text emitted alongside tool calls, rather than batching at turn end |
 | A live "N tokens so far" indicator | `onOutputProgress` into `callModel` → `onProgressUpdate(outputTokens, toolCalls)` — a count, never content |
-| Individual tokens in a UI | Forward them yourself, inside `callModel` / `AttemptFn` |
+| Individual tokens in a UI | `createTurnTextStream` from `@juno-ai/bind/completion`, driven from inside your `AttemptFn` |
 
-**The rule, if you take the third option: set `producedOutput: true` on the
-failure outcome the moment you have forwarded anything.** Routing will otherwise
-retry the same endpoint or traverse to another provider, and re-render a turn
-your user is already reading.
+The problem the third one has: routing's answer to a mid-stream failure is to
+try again — same endpoint, next provider, fallback model — and each of those
+re-renders a turn your user is already reading. `createTurnTextStream` solves it
+by asking one question about your surface. **Can it be told to discard what it
+rendered?**
 
 ```ts
-attempt: async (candidate, cursor) => {
-  let forwarded = false;
+const stream = createTurnTextStream({
+  turnId: messageId,
+  sink: { retractable: true, emit: (event) => socket.send(JSON.stringify(event)) },
+});
+
+const attempt = async (candidate, cursor) => {
+  stream.beginAttempt();                       // once per attempt, including the first
   try {
     const value = await callProvider(candidate, {
-      onDelta: (text) => { forwarded = true; sendToClient(text); },
+      onDelta: (text) => stream.observe(text), // content only — see below
     });
     return { kind: "success", value };
   } catch (error) {
-    return { kind: "failure", error: classify(error, candidate, cursor), producedOutput: forwarded };
+    return {
+      kind: "failure",
+      error: classify(error, candidate, cursor),
+      producedOutput: stream.producedOutput,   // never hand-rolled again
+    };
   }
-}
+};
+
+const result = await executeRoutePlan({ plan, attempt, breaker });
+stream.finish(result.ok ? "succeeded" : "failed");
+return result;
+```
+
+Two lifetime rules, and neither is enforceable from inside the package:
+
+**Construct it once per turn** — outside the executor and outside your
+structured-output retry loop. One per *attempt* never sees a second attempt, so
+it never resets and `producedOutput` is never true; the single-attempt path is
+indistinguishable from correct, and the bug shows up only under fallback, as two
+partial answers glued together.
+
+**Always call `finish()`, and tell it how the turn ended.** A reset still armed
+at the finish line means an earlier attempt's text is on screen, and the two
+outcomes want opposite things. `finish("succeeded")` flushes it — the retry
+succeeded with `content: null` plus tool calls, so nothing triggered the lazy
+reset and that narration belongs to a turn that never said it.
+`finish("failed")` drops it — every attempt failed, so the partial text is the
+best thing the reader is going to get, and wiping it hands them a blank space
+plus an error instead.
+
+With `retractable: true`, `producedOutput` stays `false`, so the plan keeps
+every stage. On the retry's first byte the sink receives
+`{ kind: "reset", epoch, seq, reason }` and re-renders from scratch. With
+`retractable: false` — a message already posted through a third-party API, an
+email, a webhook, an append-only row — it latches on the first byte and routing
+clamps to propagate-only, which is the old behaviour and the right one.
+
+Your client needs three lines to be correct under a transport that can reorder or
+duplicate, because an in-flight delta from attempt 1 can arrive *after* attempt
+2's reset and text alone cannot be told apart from stale text:
+
+```ts
+// Per turn: { lastSeq: -1, newestEpoch: -1, rendered: "", held: new Map() }
+// `lastSeq` starts at -1 — `seq` starts at 0, so seeding it to 0 silently drops
+// the first delta of every turn, on the single-attempt path that is almost all
+// traffic.
+const turn = state.getOrCreate(event.turnId);  // scope everything to the turn
+if (event.seq <= turn.lastSeq) return;         // replay or duplicate, drop
+if (event.seq > turn.lastSeq + 1) return buffer(turn, event);  // arrived early
+turn.lastSeq = event.seq;
+if (event.epoch < turn.newestEpoch) return;    // stale attempt, drop
+turn.newestEpoch = event.epoch;
+if (event.kind === "reset") turn.rendered = "";
+else turn.rendered += event.text;
+drainBuffered(turn);                           // apply anything that was early
 ```
 
-This costs less fallback than it looks. Retriable failures split cleanly:
-connection refused, a 429, a 5xx at the header, a time-to-first-token stall —
-none has forwarded anything, so `forwarded` is false and traversal is
-unaffected. What the flag removes is the mid-stream retry, which was never safe
-to replay in the first place.
-
-Two edges are yours to decide, because the answer is a product judgement rather
-than a routing one:
-
-- **Structured-output retries need the same care.** `structuredOutputParses`
-  retries a completion whose JSON will not parse — but if you forwarded that
-  JSON, the user has already seen it. Either withhold structured output from the
-  stream, or clamp the retry.
-- **Reasoning deltas are ambiguous.** The watchdog gates its tight budget on the
-  first *answer* token, so reasoning can flow well before one. A UI rendering
-  "thinking…" has emitted *something*, but discarding it on retry usually
-  confuses nobody. Decide whether reasoning counts as output for you; the
-  package deliberately does not decide it.
+Both keys are load-bearing and they do different jobs. **`seq`** is monotonic
+within the turn and never restarts, so it is what makes the stream tolerant of a
+transport that duplicates or reorders — drop anything at or below the last seq
+applied, hold anything that arrives ahead of it. **`epoch`** identifies the
+attempt, so it is what tells a *fresh* delta from a stale one after a reset.
+Neither substitutes for the other: without `seq` a duplicated text event appends
+twice and same-epoch chunks concatenate in arrival order; without `epoch` a
+delta from the wiped attempt is indistinguishable from the retry's.
+
+**Bound the hold buffer, and define when a turn ends.** The rule above holds an
+early event until its gap fills — and on a reconnect the gap never fills, because
+the events that would have closed it were dropped. Left alone, the surface then
+freezes on whatever the *retracted* attempt rendered, which is the exact outcome
+this module exists to prevent, and the buffer grows one entry per token. So: cap
+the buffer (a count or a timeout), and on overflow resync from the persisted
+message rather than continuing to hold. For the same reason the client needs a
+turn-final signal — `onAssistantMessage`, or the persisted row landing — at which
+it drops the turn's state entirely. Nothing on this wire tells it; that is the
+host's to define.
+
+If your transport already guarantees ordered exactly-once delivery to the client
+(a single WebSocket with no replay window, say), the `seq` half collapses to a
+no-op and the two `epoch` lines are enough — but say so deliberately rather than
+discovering it under load.
+
+**In React**, the recipe above mutates in place. Dropped into a store as written,
+`getSnapshot` returns an identity-stable object and `useSyncExternalStore` never
+re-renders — the stream looks dead. Publish a fresh snapshot per applied event.
+And key the rendered element by `turnId`, never by `epoch`: keying by epoch turns
+every reset into an unmount, discarding focus, selection and scroll position when
+the contract only ever needed a content update.
+
+**`turnId` is not decoration either.** `epoch` and `seq` both restart each turn,
+so a client that carried "newest epoch" across turns drops every event after the
+first turn that retried, and a later turn's reset tells it to wipe an earlier,
+committed message.
+
+Three things stay yours:
+
+- **Reasoning deltas.** The watchdog gates its tight budget on the first
+  *answer* token, so reasoning can flow well before one. Whether "thinking…"
+  counts as output the user has seen is a product call — express it by choosing
+  what you pass to `observe`.
+- **Tool-call deltas are not output** and should not go through `observe`. A
+  tool call is not a side effect until it is *dispatched*, which happens after
+  the turn — so a turn that dies having streamed only tool-call bytes changed
+  nothing anyone can see, and clamping it forfeits a fallback for free. If you
+  have a genuine mid-attempt effect, call `stream.markProducedOutput()`.
+- **How much flicker is acceptable.** A wipe is not only a flicker — it collapses
+  the message's height mid-stream, so an auto-scrolled transcript lurches, and it
+  destroys any text selection inside that message. If the body is an `aria-live`
+  region, every wipe re-announces the whole answer from the top; keep it
+  `aria-busy` while streaming and announce once at the end instead.
+  `maxResets` is opt-in with no default: a
+  plan with three stages, three candidates and two defect retries can legally
+  wipe the screen more than twenty times. Spending the budget latches
+  `producedOutput` so routing stops traversing — it does *not* stop emission,
+  because an attempt already in flight may be the one that succeeds and its
+  answer still has to reach the reader. Note the budget therefore also shapes how
+  many endpoints record a failure against the circuit breaker for one turn.
+
+- **Which surface gets which callback.** `onAssistantMessage` on the loop fires
+  once per completed assistant message; these events stream one attempt of one
+  message. Wiring both to the same UI element delivers the text twice. Deltas
+  drive the live view; `onAssistantMessage` drives the permanent record.
+
+Structured-output retries run in your loop, outside the executor, and get the
+same treatment — open them with `stream.beginAttempt("structured_output_retry")`
+so the user sees the re-ask replace the malformed JSON rather than follow it.
 
 ### How to map your transport errors onto the routing taxonomy
 
@@ -795,7 +1120,9 @@ client error), call `releaseProbe` so the slot cannot stick.
 your editor. This section covers what the types cannot say: which entry point
 to reach for, and the contracts that hold between calls.*
 
-Every export is re-exported from the package root, but prefer the subpath — it
+Every export is re-exported from the package root **except `@juno-ai/bind/testing`,
+which is subpath-only so fixtures never reach a production bundle** — but prefer
+the subpath either way, since it
 keeps a consumer who only wants routing from pulling in the rest.
 
 | Import | Owns | Reach for it when |
@@ -807,7 +1134,8 @@ keeps a consumer who only wants routing from pulling in the rest.
 | `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff, tool-call receipts for retry-safe side effects | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
 | `@juno-ai/bind/transcript` | `validateAndHealMessages` | You send transcripts to more than one provider, or you build them across turns |
 | `@juno-ai/bind/tools` | `sanitizeToolSchema` | Any tool schema reaches a provider — especially third-party ones |
-| `@juno-ai/bind/plugins` | Tool/plugin vocabulary, the registry factory, progressive-disclosure activation | You have more tools than fit comfortably in one prompt |
+| `@juno-ai/bind/plugins` | Tool/plugin vocabulary, `defineTool` / `pluginFromTools`, the wire-definition and tool-result encoders, the registry factory, progressive-disclosure activation | You are authoring tools, or you have more of them than fit comfortably in one prompt |
+| `@juno-ai/bind/testing` | Scripted-model fixtures — `loopHarness`, `scriptedModel`, `toolCallTurn`, `finalAnswer`, `freshState`, `recordingSink`, `steppingClock` | You want multi-turn, multi-tool tests without a credential or a mocked chat client |
 
 ### Contracts the types do not carry
 
@@ -1160,8 +1488,14 @@ const turn: TurnFn = async (messages, tools, signal) => {
 
 ### Accumulating run statistics
 
+**If you use `runToolLoop`, you do not need this** — it folds `RunStats` itself
+and returns it. This is the shape for a host driving turns by hand.
+
 Fold each turn and each tool call as they complete; `RunStats` keeps model time
-and tool time separate so a slow tool never looks like a slow model.
+and tool time separate so a slow tool never looks like a slow model. Model
+calls that are not agent turns — a compaction pass — go through
+`accumulateAuxiliarySpend` instead, which charges the tokens and the time
+without counting a turn.
 
 ```ts
 let stats = emptyRunStats();
@@ -1273,7 +1607,13 @@ try {
     stats = accumulateTurn(stats, result);
     await heartbeat.beat();
     if (!result.message.tool_calls?.length) break;
-    if (await runToolBatch(result.message.tool_calls)) { stopReason = "suspended"; break; }
+    const suspend = await runToolBatch(result.message.tool_calls);
+    if (suspend) {
+      // The two pause reasons are separate values — see the stop-reason table.
+      stopReason =
+        suspend.resumeKind === "answer" ? "waiting_for_reply" : "resuming_later";
+      break;
+    }
   }
 } catch (error) {
   stopReason = classifyRunFailure(deadline, error) === "timed_out" ? "deadline" : "aborted";
@@ -1451,21 +1791,28 @@ two rates weights a 10-token run like a 10,000-token one.
 Named, not scheduled. Listed so a consumer can tell a deliberate omission from
 an oversight.
 
-- **One `RunStats` per turn.** The loop accounts usage with `ToolLoopTurn`
-  (tokens and cost) while `ModelTurnResult` carries timings too. They converge
-  when the loop folds `RunStats` directly; today a host that wants throughput
-  metrics accumulates them alongside.
-- **A streaming turn contract.** `callModel` reports an output-token estimate
-  mid-stream and `onAssistantMessage` fires per message, but the message itself
-  still arrives whole — no token-level content crosses this boundary. Hosts
-  stream inside their own `callModel` / `AttemptFn` today
-  ([how-to](#how-to-stream-tokens-to-a-user-without-breaking-fallback)), which
-  works and keeps the package content-blind. Moving emission *in* would mean
-  owning the emit/retry interaction rather than delegating it: forwarding the
-  first delta would have to arm the `producedOutput` clamp automatically, and
-  the structured-output retry budget would need the same treatment. Deferred
-  because the host's transport is a better place for a hot-path content
-  callback, not because the design is unclear.
+- **Time-to-first-token in `RunStats`.** The loop now folds `RunStats` itself,
+  so `modelTimeMs`, `toolTimeMs` and the per-tool breakdown come for free — but
+  `ttftMs` lives on `TurnTimings` and only the transport can see the first byte.
+  A `callModel` that reported its own timings back would close the gap;
+  `ToolLoopTurn` would have to grow, which is a change to the shape every host
+  already implements.
+- **A streaming turn contract.** Half of this landed:
+  `createTurnTextStream` owns the emit/retry interaction for assistant *text*,
+  arms `producedOutput` itself, and repairs a retractable surface between
+  attempts ([how-to](#how-to-stream-tokens-to-a-user-without-breaking-fallback)).
+  What has not landed is the *contract*: `TurnFn` still returns one finished
+  `ModelTurnResult`, so `runToolLoop` cannot see the stream and a host must
+  thread it through its own `AttemptFn`. A loop-level streaming turn — where the
+  kernel wires the stream and the reset lands without host cooperation — needs
+  `TurnFn` to grow a streaming variant, and that is a breaking change to the
+  package's central type. Deferred for that reason, not for lack of a design.
+- **Streaming for tool calls and reasoning.** `createTurnTextStream` handles
+  text only, deliberately. Reasoning is a product judgement the host expresses
+  by what it forwards; tool-call deltas are not output at all until dispatch.
+  Neither has a natural primitive yet, and a host that renders a tool call as it
+  is being assembled reads `assembled()` off `createToolCallAccumulator`
+  mid-stream today, which works.
 
 ---
 

package/completion/index.d.ts

@@ -2,3 +2,4 @@ export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHU
 export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, type AssembledCompletion, type CompletionDefect, type CompletionOutputs, type ResponseFormatShape, type StreamedToolCall, } from "./defects.js";
 export { parseToolCallArguments, toolCallArgumentsAbsent, type DispatchableToolCall, type ToolCallArguments, } from "./tool-calls.js";
 export { createToolCallAccumulator, type ToolCallDelta, type AssembledToolCall, type ToolCallAccumulator, } from "./stream-assembly.js";
+export { createTurnTextStream, type TurnResetReason, type TurnStreamEvent, type TurnStreamSink, type TurnTextStream, type TurnTextStreamOptions, } from "./text-stream.js";

package/completion/index.js

@@ -2,3 +2,4 @@ export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHU
 export { detectCompletionDefect, expectsJsonOutput, jsonParses, structuredOutputParses, DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES, DEFAULT_COMPLETION_DEFECT_MAX_RETRIES, } from "./defects.js";
 export { parseToolCallArguments, toolCallArgumentsAbsent, } from "./tool-calls.js";
 export { createToolCallAccumulator, } from "./stream-assembly.js";
+export { createTurnTextStream, } from "./text-stream.js";