@juno-ai/bind 7.0.0 → 9.0.0

package/README.md

@@ -29,6 +29,28 @@ constraints that will fail CI if you break them.
 
 ---
 
+## Changelog
+
+### Unreleased
+
+**Added**
+
+- `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
@@ -572,54 +594,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
 
@@ -1455,17 +1583,22 @@ an oversight.
   (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.
+- **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";

package/completion/text-stream.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Streaming a turn's assistant text to a live surface, safely across retries.
+ *
+ * Forwarding deltas is one line in a host's transport. What is not one line —
+ * and what every host that streams has to get right independently — is what
+ * happens when the attempt that produced those deltas *fails*. The routing
+ * executor's answer to a failure is to try again: same endpoint, then the next
+ * provider, then the fallback model. Each of those re-renders a turn the user is
+ * already reading.
+ *
+ * Until now the package's only answer was to refuse: a transport that had
+ * streamed set `producedOutput` on its failure outcome and the executor clamped
+ * to propagate-only (`propagateOnly`). That trades a recoverable failure for a
+ * visible one — a 500 on the first provider becomes an error the user sees,
+ * purely because the first token had left.
+ *
+ * There is a better answer whenever the surface can be *retracted*: tell it to
+ * discard what it has, then stream the retry cleanly. That is this module. It
+ * turns `producedOutput` from "did we emit" into what its own contract already
+ * said — **"did we emit somewhere the caller cannot take it back"** — and lets a
+ * retractable surface keep the whole fallback chain.
+ *
+ * ## Lifetime: one stream per turn, and you must call `finish()`
+ *
+ * Construct it in the function that owns the turn — outside the executor and
+ * outside any structured-output retry loop — and call {@link
+ * TurnTextStream.finish} when the turn is over, whichever way it ended.
+ *
+ * Both halves are load-bearing and neither is enforceable from in here. A stream
+ * built *inside* the `AttemptFn` never sees a second attempt, so it never resets
+ * and `producedOutput` is never true; the single-attempt path — almost all
+ * traffic — looks identical to a correct one, and the bug appears only under
+ * fallback, as two partial answers glued together. Skipping `finish()` leaves an
+ * armed reset undelivered whenever the attempt that *succeeds* emits no text,
+ * which is the ordinary shape of a tool-calling turn (`content: null` plus
+ * `tool_calls`): the discarded attempt's narration then stays on screen as if it
+ * belonged to the turn that replaced it.
+ *
+ * ## What the host still owns
+ *
+ * The sink, and the judgement of what goes into it. In particular **reasoning
+ * deltas are not decided here**: whether a model's thinking counts as output the
+ * user has seen is a product call, and the host expresses it by choosing what it
+ * passes to {@link TurnTextStream.observe}.
+ *
+ * **Tool-call deltas are deliberately not output.** It is tempting to latch on
+ * the first byte of any kind, and a host streaming raw chunks may already do
+ * that. But a tool call is not a side effect until it is *dispatched*, which
+ * happens after the turn completes — so a turn that dies mid-stream having
+ * emitted only tool-call bytes has changed nothing the user or a third party can
+ * see, and refusing to retry it forfeits a fallback for free. A host with a
+ * genuine mid-attempt effect of its own says so with
+ * {@link TurnTextStream.markProducedOutput} rather than by widening what counts
+ * as text.
+ *
+ * **`onAssistantMessage` on the turn kernel is a different surface.** It fires
+ * once per completed assistant message; these events stream one attempt of one
+ * message. Wiring both to the same UI element delivers the same text twice. The
+ * division that works: deltas drive the live view, `onAssistantMessage` drives
+ * the permanent record (the transcript row, the notification, the third-party
+ * post). If they must share one element, treat the persisted message as
+ * authoritative and let it supersede the streamed epochs for its `turnId`.
+ *
+ * ## The race this exists to make survivable
+ *
+ * On any real transport — a WebSocket through a Durable Object, an SSE relay, a
+ * fan-out to several tabs — an in-flight delta from attempt 1 can be *delivered
+ * after* attempt 2's reset. A client that renders every text event it receives
+ * will then show the wiped attempt's tail glued onto the retry. Every event
+ * therefore carries a `turnId`, an `epoch` (which attempt produced it) and a
+ * `seq` (monotonic within the turn), and a correct client uses all three:
+ *
+ *  - scope everything to `turnId` — `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;
+ *  - **apply events in `seq` order**: drop anything at or below the last `seq`
+ *    applied, and hold anything that arrives ahead of it until the gap fills;
+ *  - then drop any event whose `epoch` is older than the newest seen, and clear
+ *    what is rendered on a `reset`.
+ *
+ * The `seq` step is not optional decoration on the `epoch` step — it is what
+ * makes the epoch step *sound*. Ordering by epoch alone loses a same-epoch
+ * reorder: a retry's text arriving before its own reset is accepted and then
+ * cleared by the reset that follows, leaving the surface blank. A transport that
+ * already guarantees ordered exactly-once delivery collapses the `seq` step to a
+ * no-op, but that is a property to assert deliberately rather than assume.
+ *
+ * ## Why the reset is lazy
+ *
+ * It fires on the retry's **first byte**, not when the previous attempt failed.
+ * A retry that dies before producing anything — no viable endpoint, an immediate
+ * 401 — would otherwise have wiped the screen to show nothing. Partial text plus
+ * an error is strictly more useful to a reader than a blank space plus an error.
+ * A turn where no attempt ever emits therefore emits no events at all.
+ *
+ * The one thing that must not be lazy is a reset still armed when the turn ends
+ * — hence `finish()`, which flushes it. By then the text it retracts is known to
+ * have come from an attempt that was thrown away.
+ */
+/** Why the surface is being told to discard what it has rendered. */
+export type TurnResetReason = 
+/** The previous attempt failed and routing moved on (retry, provider, model). */
+"attempt_failed"
+/** The previous attempt succeeded but its output was rejected and re-asked. */
+ | "structured_output_retry";
+/**
+ * One event bound for the user's surface.
+ *
+ * `turnId` is the host's identifier for the turn and scopes everything else:
+ * `seq` is monotonic within it and never restarts, so it doubles as an ordering
+ * and de-duplication key on a transport that can do neither, and `epoch`
+ * identifies the attempt and only ever increases. Both restart on the next turn,
+ * which is why the `turnId` is on the wire.
+ */
+export type TurnStreamEvent = Readonly<{
+    kind: "text";
+    turnId: string;
+    epoch: number;
+    seq: number;
+    text: string;
+}> | Readonly<{
+    kind: "reset";
+    turnId: string;
+    epoch: number;
+    seq: number;
+    reason: TurnResetReason;
+}>;
+/**
+ * Where a turn's text goes.
+ *
+ * `retractable` is the whole decision. It is a property of the *surface*, not of
+ * the transport that writes to it: a view that re-renders from the events it is
+ * sent is retractable; a chat message already posted through a third-party API,
+ * an email, a webhook delivery, and an append-only transcript row are not.
+ *
+ * **Wire only retractable surfaces here.** A host that must also deliver
+ * somewhere permanent should do that from the *completed* turn rather than from
+ * the deltas — that composes correctly, whereas declaring a permanent surface
+ * retractable silently re-enables the duplication this module exists to prevent.
+ * If one sink genuinely fans out to a mix, declare it `false`; the conservative
+ * answer costs a fallback, the optimistic one costs the user's trust.
+ *
+ * **`retractable` is read once, when the stream is created**, and a `readonly`
+ * field is no barrier to a getter. Re-reading it would make `producedOutput`
+ * non-monotonic: a sink that flipped after the first byte could un-clamp routing
+ * *after* the executor had already been told the turn was replayable, and the
+ * permanent surface would then get the turn twice.
+ *
+ * A sink that **buffers** — coalescing deltas over a byte or time window before
+ * releasing them — is free to drop a `reset` whose epoch never left that buffer,
+ * along with the text it would have wiped. Nothing was rendered, so nothing
+ * needs retracting, and the client is spared a no-op flicker. This module cannot
+ * do that for the sink because only the sink knows what it has released.
+ */
+export interface TurnStreamSink {
+    readonly retractable: boolean;
+    /**
+     * Deliver one event. May throw — a closed socket is ordinary, not
+     * exceptional. See {@link TurnTextStream.sinkErrors} for what a throw means.
+     */
+    emit(event: TurnStreamEvent): void;
+}
+export interface TurnTextStreamOptions {
+    readonly sink: TurnStreamSink;
+    /**
+     * Identifies the turn on the wire. Any value the client can compare for
+     * equality and that is unique among the turns it may see concurrently — a
+     * message id, a run id plus a turn ordinal. Required rather than defaulted
+     * because a client cannot scope `epoch` and `seq` without it, and every
+     * plausible default would be wrong for someone.
+     *
+     * **It is a correlation label, never an authorization boundary.** The client
+     * rule says "scope everything to `turnId`", which is about *ordering*, not
+     * about deciding whether an event is yours to render. The sink must already be
+     * scoped to the intended recipient before anything is emitted — a client that
+     * treats a matching `turnId` as evidence an event belongs to it will render
+     * whatever arrives on a shared topic, including a `reset` that wipes a
+     * committed message.
+     */
+    readonly turnId: string;
+    /**
+     * Cap on how many times the surface may be wiped in one turn. Reaching it
+     * does not throw and does not stop emission: it makes
+     * {@link TurnTextStream.producedOutput} true, so the *next* failure clamps
+     * routing and the traversal stops. Emission continues so that an attempt
+     * already in flight still reaches the user.
+     *
+     * There is **no default cap** — a plan with three stages, three candidates and
+     * two defect retries can legally wipe the screen more than twenty times, and
+     * that is worth bounding, but the tolerable number is a product judgement
+     * about flicker that this module cannot make for a host. Guessing one would
+     * break a host for whom a rare double-wipe is entirely fine.
+     *
+     * Because the value gates routing, it also shapes how many endpoints record a
+     * failure against the circuit breaker for one user turn. That is a real
+     * coupling between a UI judgement and shared telemetry; it is the price of
+     * letting the UI decide.
+     */
+    readonly maxResets?: number | undefined;
+}
+export interface TurnTextStream {
+    /**
+     * Open a new attempt. Call this at the **top of every attempt**, including the
+     * first — that is once per `AttemptFn` invocation, which covers same-endpoint
+     * defect retries, provider traversal and model fallback in one place, plus
+     * once per structured-output retry, which happens outside the executor and is
+     * the caller's loop to instrument.
+     *
+     * On any attempt following one that produced text, this arms a reset; the
+     * reset itself is emitted lazily, when that attempt first produces text (or by
+     * {@link finish}, if it never does).
+     *
+     * An explicitly passed `reason` **sticks** until the reset is delivered, and a
+     * later call that omits one will not overwrite it. Without that, the
+     * structured-output arm of {@link TurnResetReason} would be unreachable in the
+     * composition this module prescribes: the caller's retry loop opens the
+     * attempt with a reason, then re-enters the executor, whose `AttemptFn` opens
+     * the same pending reset again with the default.
+     */
+    beginAttempt(reason?: TurnResetReason): void;
+    /**
+     * Forward one content delta. `null`, `undefined` and `""` are no-ops and do
+     * not count as output — a provider sending an empty content field has shown
+     * the user nothing.
+     */
+    observe(text: string | null | undefined): void;
+    /**
+     * End the turn. **Call it however the turn ended**, including on the success
+     * path and on a throw — and tell it which, because the two do opposite things
+     * with a reset that is still armed.
+     *
+     * - `"succeeded"` **flushes** it. An attempt streamed text and failed, the
+     *   retry succeeded with tool calls and no text at all, so nothing triggered
+     *   the lazy reset. Without the flush the failed attempt's narration stays on
+     *   the surface attributed to a turn that never said it, and vanishes only on
+     *   reload. `content: null` plus `tool_calls` is the ordinary shape of an
+     *   agent turn, so this is the common case rather than an edge.
+     * - `"failed"` **drops** it. Every attempt failed, and the last one died
+     *   before producing a byte. Flushing here would wipe the screen to show
+     *   nothing — the reader would get a blank space plus an error where they
+     *   could have had partial text plus an error, which is the same trade the
+     *   lazy reset exists to make and must not be undone at the finish line.
+     *
+     * Idempotent. Afterwards every method is a no-op.
+     */
+    finish(outcome: "succeeded" | "failed"): void;
+    /**
+     * Latch {@link producedOutput} for a reason this module cannot see — a
+     * provider-side effect, a write a replay would repeat, a second surface the
+     * host wrote to itself. Irreversible, and a no-op after {@link finish}: the
+     * flag exists for the executor to read on a failure outcome, and once the turn
+     * is over there is no outcome left to clamp.
+     *
+     * It does **not** stop emission. If the attempt that reported the effect goes
+     * on to succeed, its text is still the user's answer and must reach them; if
+     * it fails, the clamp has already told the executor to stop, so there is no
+     * later attempt to suppress.
+     *
+     * This is the seam for a host migrating off a hand-rolled "any byte arrived"
+     * flag. Keep the flag for the effects it genuinely tracks and call this;
+     * do not widen {@link observe}.
+     */
+    markProducedOutput(): void;
+    /**
+     * Whether output has reached a surface the caller **cannot take back**, which
+     * is exactly the flag the routing executor clamps on. Put it straight onto the
+     * failure outcome:
+     *
+     * ```ts
+     * return { kind: "failure", error, producedOutput: stream.producedOutput };
+     * ```
+     *
+     * For a retractable sink this stays `false` while a wipe is still available,
+     * so routing keeps its whole fallback chain. It latches `true` when the reset
+     * budget is spent, when a reset failed to reach the sink, or when the host
+     * reports an out-of-band effect. Monotonic: never true then false.
+     *
+     * **It answers "may routing replay this turn", not "is the reader looking at
+     * output".** The executor only reads it on a failure outcome, so the two
+     * questions never diverge where it is consumed — but they do diverge off-label:
+     * a turn that spent its flicker budget and then *succeeded* reads `true` even
+     * though the text it emitted was retracted. Do not source a "did the user see
+     * anything" metric from this.
+     */
+    readonly producedOutput: boolean;
+    /** The current attempt's epoch. `-1` before the first {@link beginAttempt}. */
+    readonly epoch: number;
+    /**
+     * Resets *handed to the sink* so far. A reset whose `emit` threw is counted —
+     * it consumed the flicker budget, and whether the client saw it is exactly
+     * what this module cannot know. See {@link sinkErrors}.
+     */
+    readonly resetCount: number;
+    /**
+     * Events whose `emit` threw. Emission continues after a throw rather than
+     * tearing down — a momentarily closed socket should not end a model turn that
+     * is otherwise fine.
+     *
+     * Two consequences. On a **non-retractable** surface a throw still counts as
+     * output: the sink got far enough to fail, and whether the bytes left first is
+     * not knowable from here, so the conservative reading is that they did. On a
+     * **retractable** one a failed *text* event leaves the turn replayable, but a
+     * failed *reset* does not — the wipe instruction is the one event whose loss
+     * cannot be repaired by sending more, so it latches
+     * {@link producedOutput} rather than letting a second epoch stack onto a
+     * surface that never cleared the first.
+     */
+    readonly sinkErrors: number;
+}
+export declare function createTurnTextStream(options: TurnTextStreamOptions): TurnTextStream;

package/completion/text-stream.js

@@ -0,0 +1,273 @@
+/**
+ * Streaming a turn's assistant text to a live surface, safely across retries.
+ *
+ * Forwarding deltas is one line in a host's transport. What is not one line —
+ * and what every host that streams has to get right independently — is what
+ * happens when the attempt that produced those deltas *fails*. The routing
+ * executor's answer to a failure is to try again: same endpoint, then the next
+ * provider, then the fallback model. Each of those re-renders a turn the user is
+ * already reading.
+ *
+ * Until now the package's only answer was to refuse: a transport that had
+ * streamed set `producedOutput` on its failure outcome and the executor clamped
+ * to propagate-only (`propagateOnly`). That trades a recoverable failure for a
+ * visible one — a 500 on the first provider becomes an error the user sees,
+ * purely because the first token had left.
+ *
+ * There is a better answer whenever the surface can be *retracted*: tell it to
+ * discard what it has, then stream the retry cleanly. That is this module. It
+ * turns `producedOutput` from "did we emit" into what its own contract already
+ * said — **"did we emit somewhere the caller cannot take it back"** — and lets a
+ * retractable surface keep the whole fallback chain.
+ *
+ * ## Lifetime: one stream per turn, and you must call `finish()`
+ *
+ * Construct it in the function that owns the turn — outside the executor and
+ * outside any structured-output retry loop — and call {@link
+ * TurnTextStream.finish} when the turn is over, whichever way it ended.
+ *
+ * Both halves are load-bearing and neither is enforceable from in here. A stream
+ * built *inside* the `AttemptFn` never sees a second attempt, so it never resets
+ * and `producedOutput` is never true; the single-attempt path — almost all
+ * traffic — looks identical to a correct one, and the bug appears only under
+ * fallback, as two partial answers glued together. Skipping `finish()` leaves an
+ * armed reset undelivered whenever the attempt that *succeeds* emits no text,
+ * which is the ordinary shape of a tool-calling turn (`content: null` plus
+ * `tool_calls`): the discarded attempt's narration then stays on screen as if it
+ * belonged to the turn that replaced it.
+ *
+ * ## What the host still owns
+ *
+ * The sink, and the judgement of what goes into it. In particular **reasoning
+ * deltas are not decided here**: whether a model's thinking counts as output the
+ * user has seen is a product call, and the host expresses it by choosing what it
+ * passes to {@link TurnTextStream.observe}.
+ *
+ * **Tool-call deltas are deliberately not output.** It is tempting to latch on
+ * the first byte of any kind, and a host streaming raw chunks may already do
+ * that. But a tool call is not a side effect until it is *dispatched*, which
+ * happens after the turn completes — so a turn that dies mid-stream having
+ * emitted only tool-call bytes has changed nothing the user or a third party can
+ * see, and refusing to retry it forfeits a fallback for free. A host with a
+ * genuine mid-attempt effect of its own says so with
+ * {@link TurnTextStream.markProducedOutput} rather than by widening what counts
+ * as text.
+ *
+ * **`onAssistantMessage` on the turn kernel is a different surface.** It fires
+ * once per completed assistant message; these events stream one attempt of one
+ * message. Wiring both to the same UI element delivers the same text twice. The
+ * division that works: deltas drive the live view, `onAssistantMessage` drives
+ * the permanent record (the transcript row, the notification, the third-party
+ * post). If they must share one element, treat the persisted message as
+ * authoritative and let it supersede the streamed epochs for its `turnId`.
+ *
+ * ## The race this exists to make survivable
+ *
+ * On any real transport — a WebSocket through a Durable Object, an SSE relay, a
+ * fan-out to several tabs — an in-flight delta from attempt 1 can be *delivered
+ * after* attempt 2's reset. A client that renders every text event it receives
+ * will then show the wiped attempt's tail glued onto the retry. Every event
+ * therefore carries a `turnId`, an `epoch` (which attempt produced it) and a
+ * `seq` (monotonic within the turn), and a correct client uses all three:
+ *
+ *  - scope everything to `turnId` — `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;
+ *  - **apply events in `seq` order**: drop anything at or below the last `seq`
+ *    applied, and hold anything that arrives ahead of it until the gap fills;
+ *  - then drop any event whose `epoch` is older than the newest seen, and clear
+ *    what is rendered on a `reset`.
+ *
+ * The `seq` step is not optional decoration on the `epoch` step — it is what
+ * makes the epoch step *sound*. Ordering by epoch alone loses a same-epoch
+ * reorder: a retry's text arriving before its own reset is accepted and then
+ * cleared by the reset that follows, leaving the surface blank. A transport that
+ * already guarantees ordered exactly-once delivery collapses the `seq` step to a
+ * no-op, but that is a property to assert deliberately rather than assume.
+ *
+ * ## Why the reset is lazy
+ *
+ * It fires on the retry's **first byte**, not when the previous attempt failed.
+ * A retry that dies before producing anything — no viable endpoint, an immediate
+ * 401 — would otherwise have wiped the screen to show nothing. Partial text plus
+ * an error is strictly more useful to a reader than a blank space plus an error.
+ * A turn where no attempt ever emits therefore emits no events at all.
+ *
+ * The one thing that must not be lazy is a reset still armed when the turn ends
+ * — hence `finish()`, which flushes it. By then the text it retracts is known to
+ * have come from an attempt that was thrown away.
+ */
+export function createTurnTextStream(options) {
+    const { sink, turnId } = options;
+    const maxResets = options.maxResets;
+    if (maxResets !== undefined &&
+        (!Number.isInteger(maxResets) || maxResets < 0)) {
+        // `NaN` compares false against everything, so an unvalidated non-finite cap
+        // reads as "unbounded" — the exact opposite of the safe failure, on the one
+        // option whose whole purpose is to bound something.
+        throw new TypeError(`createTurnTextStream: maxResets must be a non-negative integer, got ${String(maxResets)}`);
+    }
+    if (typeof turnId !== "string" || turnId === "") {
+        // Every plausible way to get here — `turnId: obj?.id ?? ""` — collapses
+        // every turn of a run into one scope on the client, which is the bug the
+        // field was added to prevent.
+        throw new TypeError(`createTurnTextStream: turnId must be a non-empty string, got ${JSON.stringify(turnId)}`);
+    }
+    // Snapshotted, never re-read — see `TurnStreamSink.retractable`.
+    const retractable = sink.retractable;
+    let epoch = -1;
+    let seq = 0;
+    let resetCount = 0;
+    let sinkErrors = 0;
+    let finished = false;
+    // Text has reached the sink at least once this turn. Distinct from
+    // `producedOutput`, which additionally asks whether it can be taken back.
+    let emitted = false;
+    // Held rather than sent immediately so an attempt that dies before producing
+    // anything leaves the previous text on screen.
+    let resetPending = null;
+    // The surface is showing an epoch it will never be told to clear — either a
+    // reset was refused, or the flicker budget ran out before one could be armed.
+    // Both mean the same thing and must behave the same way: stop writing to it.
+    // They did not, and the asymmetry spliced two answers together — the budget
+    // path armed no reset and then happily appended the next attempt's text on top
+    // of the abandoned one.
+    let staleSurface = false;
+    // Whether a reset was EVER lost. Separate from `staleSurface` because that one
+    // clears when a later reset lands, and `producedOutput` must not un-latch.
+    let everLostReset = false;
+    let externalEffect = false;
+    const budgetSpent = () => maxResets !== undefined && resetCount >= maxResets;
+    const deliver = (event) => {
+        try {
+            // Frozen because the type says `Readonly` and a sink that fans out to two
+            // consumers would otherwise let the first mutate what the second sees.
+            sink.emit(Object.freeze(event));
+            return true;
+        }
+        catch {
+            sinkErrors += 1;
+            return false;
+        }
+    };
+    const flushReset = () => {
+        const reason = resetPending;
+        if (reason === null)
+            return;
+        resetPending = null;
+        resetCount += 1;
+        const stamp = epoch;
+        if (deliver({ kind: "reset", turnId, epoch: stamp, seq: seq++, reason })) {
+            // The wipe landed, so whatever was stranded on the surface is gone and it
+            // is safe to write again.
+            staleSurface = false;
+        }
+        else {
+            staleSurface = true;
+            everLostReset = true;
+        }
+    };
+    return {
+        beginAttempt(reason) {
+            if (finished)
+                return;
+            // The epoch advances on every attempt, whether or not a reset is owed:
+            // it identifies the attempt, and a host correlating logs on it should not
+            // see it stall because an earlier attempt happened to stay silent.
+            epoch += 1;
+            // Nothing on screen yet, so nothing to retract.
+            if (!emitted)
+                return;
+            // A permanent surface cannot honour a retraction, and telling it to is
+            // worse than not: a defensive sink reads it as a protocol error and a
+            // naive one may delete a message it already posted. Its `producedOutput`
+            // latched on the first byte, so routing has already stopped.
+            if (!retractable)
+                return;
+            // No wipe left, so this attempt's text would land on top of the last one
+            // rather than replacing it. The executor has already been told to stop
+            // (`producedOutput` is true), so anything still driving attempts is a
+            // caller-owned loop — a structured-output retry — and appending its output
+            // to an abandoned answer is the splice this module exists to prevent.
+            if (budgetSpent()) {
+                staleSurface = true;
+                return;
+            }
+            // An explicit reason outranks a later default — see `beginAttempt`. Spelt
+            // out rather than as a `??` chain: the chain reads as "reason wins" and
+            // hides that the middle term is what preserves an EARLIER explicit reason
+            // through a later defaulted call, which is the whole point.
+            if (reason !== undefined) {
+                resetPending = reason;
+            }
+            else {
+                resetPending ??= "attempt_failed";
+            }
+        },
+        observe(text) {
+            if (finished)
+                return;
+            // Checked before the empty-text short-circuit: this guard catches a host
+            // that never opened an attempt, and a host whose first chunk happens to be
+            // empty must not ship green and then produce indistinguishable retries.
+            if (epoch < 0) {
+                throw new Error("createTurnTextStream: observe() before beginAttempt() — every attempt must open one, or a retry cannot be told apart from the turn it replaces");
+            }
+            if (text === null || text === undefined || text === "")
+                return;
+            // Checked BEFORE the flush, not after: once the surface is stranded,
+            // sending it more — including another reset — only compounds the problem.
+            // A reset delivered now would clear text the reader is relying on and then
+            // be followed by nothing, leaving them with a blank message on a turn that
+            // may well succeed. One coherent (if stale) answer beats both a spliced
+            // one and an empty one; `sinkErrors` is the host's cue to force a resync.
+            if (staleSurface)
+                return;
+            flushReset();
+            // Re-checked: the flush above may have just failed, in which case the
+            // surface still shows the epoch it was told to clear and this attempt's
+            // text would be glued onto it.
+            if (staleSurface)
+                return;
+            emitted = true;
+            // Stamped before `deliver`, so a re-entrant sink that opens another
+            // attempt from inside `emit` cannot back-date this delta to a newer one.
+            const stamp = epoch;
+            deliver({ kind: "text", turnId, epoch: stamp, seq: seq++, text });
+        },
+        finish(outcome) {
+            if (finished)
+                return;
+            finished = true;
+            // A pending reset means an earlier attempt's text is still on screen. On
+            // success it has been superseded and must go; on failure it is the best
+            // thing the reader has, and wiping it is strictly worse than leaving it.
+            if (outcome === "succeeded")
+                flushReset();
+            else
+                resetPending = null;
+        },
+        markProducedOutput() {
+            if (finished)
+                return;
+            externalEffect = true;
+        },
+        get producedOutput() {
+            if (externalEffect)
+                return true;
+            if (!emitted)
+                return false;
+            return !retractable || everLostReset || budgetSpent();
+        },
+        get epoch() {
+            return epoch;
+        },
+        get resetCount() {
+            return resetCount;
+        },
+        get sinkErrors() {
+            return sinkErrors;
+        },
+    };
+}

package/loop/tool-loop.d.ts

@@ -235,6 +235,20 @@ export interface ToolLoopParams {
         userId: string;
         content: string;
     }) => Promise<void> | void;
+    /**
+     * Bounds the tool batch. Combine the run's deadline with any cancellation
+     * signal (`deadline.withExternal(cancelSignal)`) and pass the result.
+     *
+     * Without it, `throwIfTimedOut` and `ensureNotCancelled` are only consulted
+     * between iterations, so a deadline that fires while the model is being
+     * called still lets the whole batch execute its side effects, and a hung tool
+     * holds the run open for as long as it runs. Those are throw-based ports and
+     * cannot express "stop claiming new work" to a pool already in flight — only
+     * a signal can.
+     *
+     * Optional so an existing host is unchanged until it opts in.
+     */
+    signal?: AbortSignal | undefined;
     /** Decide whether the live context (token count) needs auto-compaction. */
     needsCompaction?: (currentTokens: number) => boolean;
     /**

package/loop/tool-loop.js

@@ -1,4 +1,4 @@
-import { runToolCallsPooledByTool } from "../run/tool-batch.js";
+import { runToolCallsPooledByTool, AbortedToolCallError, } from "../run/tool-batch.js";
 /**
  * Repeatedly call the model and execute the tools it requests, until it stops
  * requesting them, a caller stops the loop, a tool suspends the run, or
@@ -13,7 +13,7 @@ import { runToolCallsPooledByTool } from "../run/tool-batch.js";
  * mid-loop, which a returned result could not provide until the run ended.
  */
 export async function runToolLoop(params) {
-    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, ensureNotCancelled, throwIfTimedOut, onStatus, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
+    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, ensureNotCancelled, throwIfTimedOut, onStatus, signal, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
     // An observer must not be able to change control flow: a host logger that
     // throws while reporting a tool failure would otherwise turn a *reported*
     // failure into a fatal one, which is the opposite of what the report is for.
@@ -128,6 +128,31 @@ export async function runToolLoop(params) {
         for (let i = 0; i < toolCalls.length; i++) {
             const tc = toolCalls[i];
             if (runsSerially?.(tc)) {
+                // The serial phase runs before the pool and is a loop of its own, so it
+                // needs the same claim-time check — otherwise an aborted batch still
+                // executes every activation call ahead of the pool that refuses to.
+                if (signal?.aborted === true) {
+                    const aborted = new AbortedToolCallError(tc.id);
+                    // Routed through the same three seams as a pooled refusal — fatal
+                    // classification, the rejection observer, and the synthesized answer.
+                    // The serial phase used to do none of them, so one condition produced
+                    // two behaviours depending on which half of the batch a call landed in.
+                    if (isFatalToolError?.(aborted))
+                        throw aborted;
+                    reportRejection(tc.id, aborted);
+                    outcomes[i] = {
+                        toolMessage: {
+                            role: "tool",
+                            tool_call_id: tc.id,
+                            content: JSON.stringify({
+                                success: false,
+                                kind: "not_run",
+                                error: aborted.message,
+                            }),
+                        },
+                    };
+                    continue;
+                }
                 // Mirror the concurrent batch's graceful error synthesis so a failing
                 // activation call (transient network/DB/timeout) doesn't crash the
                 // run — but let a fatal error propagate for an immediate abort.
@@ -166,7 +191,9 @@ export async function runToolLoop(params) {
             deferredIndices.push(i);
             deferredCalls.push(tc);
         }
-        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall);
+        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall, {
+            signal,
+        });
         for (let j = 0; j < deferredCalls.length; j++) {
             const origIndex = deferredIndices[j];
             const call = deferredCalls[j];
@@ -188,6 +215,14 @@ export async function runToolLoop(params) {
                         tool_call_id: call.id,
                         content: JSON.stringify({
                             success: false,
+                            // A refused call is not a failed one, and the envelope alone
+                            // cannot say so — `success: false` plus a sentence is exactly what
+                            // a tool that ran and failed produces. The discriminant is what
+                            // lets a model (or a host) tell them apart without matching on
+                            // prose. See `ToolFailureKind`.
+                            ...(settledResult.reason instanceof AbortedToolCallError
+                                ? { kind: "not_run" }
+                                : {}),
                             error: settledResult.reason instanceof Error
                                 ? settledResult.reason.message
                                 : String(settledResult.reason),
@@ -233,6 +268,32 @@ export async function runToolLoop(params) {
             if (outcome.requestCompaction)
                 compactionRequested = true;
         }
+        // An aborted batch ends the run HERE — after every refused call has been
+        // answered in the transcript (so nothing dangles), and before the suspend,
+        // compaction and persist arms below. Two reasons, and the second is the sharp one:
+        //
+        //  - The transcript now contains a synthesized result for every refused
+        //    call. Reaching `saveSession` durably records "these tools failed" for
+        //    work that was never dispatched, and a resumed run reads that as fact —
+        //    the same lie `isFatalToolError` already refuses to tell for a write it
+        //    could not record. The suspend arm `break`s BEFORE the cancellation
+        //    boundary below, so without this check that path persists it.
+        //  - A host whose `signal` is not also reflected by `throwIfTimedOut` /
+        //    `ensureNotCancelled` would otherwise refuse the batch, loop, and pay
+        //    for another model call — every iteration to `maxIterations`.
+        //
+        // Delegating to the throw ports rather than throwing directly keeps the
+        // terminal error the host's to name (a timeout and a cancellation are
+        // different outcomes, and only the host knows which fired).
+        if (signal?.aborted === true) {
+            throwIfTimedOut?.();
+            await ensureNotCancelled?.();
+            // Neither port is required, and a host that wired only `signal` would
+            // otherwise refuse every batch and pay for a fresh model call each
+            // iteration until `maxIterations`. Break so the abort ends the run on its
+            // own, rather than only when some other port happens to agree.
+            break;
+        }
         // A tool asked to end the run (it scheduled its own resume, or recorded an
         // open call awaiting an answer). The tool results are already in
         // state.messages above; stop now so the run doesn't keep going. Mark it as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",

package/plugins/tool.d.ts

@@ -80,7 +80,7 @@ export interface ToolDef {
  * status, a retry decision — without matching on the error string, which is
  * brittle and locale-dependent. Plugins should set it explicitly.
  */
-export type ToolFailureKind = "authz" | "validation" | "not_found" | "conflict" | "external" | "system";
+export type ToolFailureKind = "authz" | "validation" | "not_found" | "conflict" | "external" | "not_run" | "system";
 /**
  * Human-in-the-loop suspend directive. A first-party tool returns this on a
  * successful result to **end the run** and record its open tool-call as

package/run/index.d.ts

@@ -1,4 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
-export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { runToolCallsPooledByTool, AbortedToolCallError, ABORTED_TOOL_CALL_MESSAGE, type ToolBatchOptions, } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, type ChainRef, type ChainRule, type ChildAdmission, type PollStep, type PollSchedule, type PollScheduleOptions, } from "./children.js";
 export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, type ToolCallReceiptKey, type DigestFn, type ReceiptState, type EffectResumability, type ReceiptDecision, } from "./receipts.js";

package/run/index.js

@@ -1,4 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
-export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { runToolCallsPooledByTool, AbortedToolCallError, ABORTED_TOOL_CALL_MESSAGE, } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, } from "./children.js";
 export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, } from "./receipts.js";

package/run/tool-batch.d.ts

@@ -12,5 +12,55 @@ import type OpenAI from "openai";
  * harness-owned, while the shape a host derives from a completed call (which
  * plugin activated, whether the run should compact, a suspend directive, …)
  * stays with the host.
+ *
+ * **`signal` bounds the batch, and bounding it is the point.** A batch of many
+ * calls to one tool runs five at a time, so the rest sit queued — and without a
+ * signal the pool claims every one of them however long ago the run's deadline
+ * fired or the user pressed stop. Each queued call is a side effect nobody
+ * wants any more: a write, an email, a third-party POST. Once the signal
+ * aborts, workers stop claiming new work.
+ *
+ * Calls that never ran still come back — as `rejected` with an
+ * {@link AbortedToolCallError} — because every `tool_call_id` in the assistant
+ * message needs a response either way, and a caller that received a shorter
+ * array than it passed would silently mispair the rest. A call already in
+ * flight is left alone: this cannot reach inside a host's tool, and cancelling
+ * one mid-write is the host's problem to solve with the same signal.
+ */
+/**
+ * The message a refused call carries into the transcript, and therefore **into
+ * the model's next turn**. Shared by both refusal sites — the pool and the
+ * loop's serial phase — because to the only reader they are the same fact, and
+ * two literals for one fact drift.
+ *
+ * Three things it deliberately does *not* do. It does not name the batch, the
+ * worker, or the claim: those are this module's internals, the model cannot act
+ * on them, and they appear nowhere else in its context. It does not interpolate
+ * the call id, which the `tool` message's own `tool_call_id` already carries —
+ * restating it spends the sentence's most-attended position on something the
+ * reader has. And it does not lead with the cause: the actionable fact is that
+ * *nothing happened*, and a model skimming a batch of results reads the first
+ * clause.
+ */
+export declare const ABORTED_TOOL_CALL_MESSAGE: string;
+/**
+ * A call the batch refused because it was aborted before any worker claimed it.
+ *
+ * Carries the id as a **field** rather than in the message, so a host's
+ * rejection observer and operator log can filter on it (`CLAUDE.md`: identifying
+ * context is a field, not string interpolation).
  */
-export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>): Promise<PromiseSettledResult<TOutcome>[]>;
+export declare class AbortedToolCallError extends Error {
+    readonly toolCallId: string;
+    readonly name = "AbortedToolCallError";
+    constructor(toolCallId: string);
+}
+export interface ToolBatchOptions {
+    /**
+     * Stop claiming queued calls once this aborts. Combine a run deadline with a
+     * cancellation signal (`AbortSignal.any`) before passing it — the pool does
+     * not care which one fired, only that no further work should start.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>, options?: ToolBatchOptions): Promise<PromiseSettledResult<TOutcome>[]>;

package/run/tool-batch.js

@@ -36,10 +36,57 @@ function poolKey(call) {
  * harness-owned, while the shape a host derives from a completed call (which
  * plugin activated, whether the run should compact, a suspend directive, …)
  * stays with the host.
+ *
+ * **`signal` bounds the batch, and bounding it is the point.** A batch of many
+ * calls to one tool runs five at a time, so the rest sit queued — and without a
+ * signal the pool claims every one of them however long ago the run's deadline
+ * fired or the user pressed stop. Each queued call is a side effect nobody
+ * wants any more: a write, an email, a third-party POST. Once the signal
+ * aborts, workers stop claiming new work.
+ *
+ * Calls that never ran still come back — as `rejected` with an
+ * {@link AbortedToolCallError} — because every `tool_call_id` in the assistant
+ * message needs a response either way, and a caller that received a shorter
+ * array than it passed would silently mispair the rest. A call already in
+ * flight is left alone: this cannot reach inside a host's tool, and cancelling
+ * one mid-write is the host's problem to solve with the same signal.
+ */
+/**
+ * The message a refused call carries into the transcript, and therefore **into
+ * the model's next turn**. Shared by both refusal sites — the pool and the
+ * loop's serial phase — because to the only reader they are the same fact, and
+ * two literals for one fact drift.
+ *
+ * Three things it deliberately does *not* do. It does not name the batch, the
+ * worker, or the claim: those are this module's internals, the model cannot act
+ * on them, and they appear nowhere else in its context. It does not interpolate
+ * the call id, which the `tool` message's own `tool_call_id` already carries —
+ * restating it spends the sentence's most-attended position on something the
+ * reader has. And it does not lead with the cause: the actionable fact is that
+ * *nothing happened*, and a model skimming a batch of results reads the first
+ * clause.
  */
-export async function runToolCallsPooledByTool(calls, run) {
+export const ABORTED_TOOL_CALL_MESSAGE = "This call was never started, so nothing happened and nothing changed. " +
+    "The run is ending — do not retry it and do not report it as a failure.";
+/**
+ * A call the batch refused because it was aborted before any worker claimed it.
+ *
+ * Carries the id as a **field** rather than in the message, so a host's
+ * rejection observer and operator log can filter on it (`CLAUDE.md`: identifying
+ * context is a field, not string interpolation).
+ */
+export class AbortedToolCallError extends Error {
+    toolCallId;
+    name = "AbortedToolCallError";
+    constructor(toolCallId) {
+        super(ABORTED_TOOL_CALL_MESSAGE);
+        this.toolCallId = toolCallId;
+    }
+}
+export async function runToolCallsPooledByTool(calls, run, options = {}) {
     if (calls.length === 0)
         return [];
+    const signal = options.signal;
     const results = new Array(calls.length);
     const groups = new Map();
     for (let i = 0; i < calls.length; i++) {
@@ -69,6 +116,17 @@ export async function runToolCallsPooledByTool(calls, run) {
                 if (pos >= indices.length)
                     return;
                 const callIdx = indices[pos];
+                // Checked at claim time rather than before the loop: a batch that
+                // was fine when it started can be aborted while its first workers
+                // are in flight, and that is the ordinary case — the deadline fires
+                // or the user hits stop DURING the batch, not before it.
+                if (signal?.aborted === true) {
+                    results[callIdx] = {
+                        status: "rejected",
+                        reason: new AbortedToolCallError(calls[callIdx].id),
+                    };
+                    continue;
+                }
                 try {
                     const value = await run(calls[callIdx]);
                     results[callIdx] = { status: "fulfilled", value };