@juno-ai/bind 5.0.0 → 7.0.0

package/README.md

@@ -428,6 +428,199 @@ cancellation is never reported as a retriable upstream stall. Call it in the
 (`setTimeout` coerces a non-finite delay to ~1ms — it does not disable the
 timer).
 
+### How to read the arguments of a tool call the model asked for
+
+`JSON.parse(toolCall.function.arguments)` is the obvious implementation and it
+is wrong for the commonest tool there is. Providers send `""` for a
+**zero-argument** call as readily as `"{}"`, so the obvious version kills a
+perfectly good call as a JSON syntax error and burns a recovery turn on a turn
+that was never broken.
+
+```ts
+import { parseToolCallArguments } from "@juno-ai/bind/completion";
+
+const read = parseToolCallArguments(toolCall);
+switch (read.kind) {
+  case "parsed":
+    return dispatch(toolCall.function.name, read.arguments);
+  case "unsupported_type":
+    return toolMessage(toolCall.id, `Unsupported tool call type: ${read.type}`);
+  case "unparseable":
+    // Put `detail` in front of the MODEL, not only in a log — its next turn is
+    // the only thing that can correct the arguments.
+    return toolMessage(toolCall.id, `Invalid tool arguments: ${read.detail}`);
+}
+```
+
+Every outcome is a value, not a throw, because every outcome has to end with a
+`tool` message carrying this call's id — a transcript where an assistant asked
+for a tool and nothing answered it is rejected by the provider on the *next*
+request, so "give up on this call" was never an option.
+
+Valid JSON that is not an object — `null`, `[]`, `42` — is refused rather than
+dispatched. Tool arguments are a named parameter bag by definition, and handing
+a tool an array where it expects fields turns a clear failure here into a
+confusing one inside the tool, after any side effect it performs before its own
+validation.
+
+### How to assemble streamed tool calls
+
+Providers send tool calls as indexed deltas, and the obvious accumulation loop
+is wrong in four ways that all fail silently.
+
+```ts
+import { createToolCallAccumulator } from "@juno-ai/bind/completion";
+
+const toolCalls = createToolCallAccumulator();
+for await (const chunk of stream) {
+  toolCalls.observe(chunk.choices?.[0]?.delta?.tool_calls);
+}
+const assembled = toolCalls.isEmpty ? undefined : toolCalls.assembled();
+```
+
+Key by the provider's `index`, not arrival order — deltas for index 1 can
+precede index 0, and pushing onto an array transposes the calls while leaving
+both parseable. Read `id` on every delta, not just the first for a slot; a
+late one is legal and a call without an id cannot be answered. Concatenate
+`name` as well as `arguments` — providers split it, and assigning keeps only
+the last fragment (`_file` from `read_file`), which surfaces as an unknown-tool
+error naming a tool the model never asked for. Order by index at the end, since
+`Map` iterates in insertion order.
+
+### How to keep a retry from repeating a tool's side effect
+
+A durable runtime retries: a queue redelivers, a workflow step re-runs, a
+reclaimed job starts the turn again. If the turn sent an email, the retry sends
+a second one. A *receipt* is the row that lets the second attempt find out.
+
+```ts
+import {
+  toolCallArgsHash, decideToolCallReceipt, type DigestFn,
+} from "@juno-ai/bind/run";
+
+const sha256: DigestFn = async (s) => {
+  const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+};
+
+const key = { tenantId, runId, toolName, argsHash: await toolCallArgsHash(args, sha256) };
+const decision = decideToolCallReceipt({
+  state: await store.read(key),            // yours — see the shape below
+  effect: tool.resumable ? "resumable" : "opaque",
+});
+
+switch (decision.kind) {
+  case "replay":    return (await store.read(key)).result;
+  case "wait":      return retryLater(decision.reason);
+  case "ambiguous": return surfaceToAHuman(decision.reason);
+  case "execute": {
+    await store.claim(key, decision.attempt);   // BEFORE executing
+    const result = await tool.execute(args);
+    await store.complete(key, decision.attempt, result);
+    return result;
+  }
+}
+```
+
+**Identity is content, not position.** The key is
+`(tenant, run, tool, arguments)`. Keying by position — run + turn + index in the
+batch — looks equivalent and is not: a retried turn is a *fresh completion*, so
+above temperature zero the model may reorder the batch or ask for a different
+tool at the same index. Position-keyed receipts then match calls that are not
+the same call, replay one tool's result as another's, and skip the tool actually
+requested. Content keying fails the other way, which is the safe way: a genuinely
+new call finds no receipt and runs.
+
+**The tenant is part of the key.** Without it the key cannot be partitioned or
+relocated by tenant, and two tenants' runs are not guaranteed to share a database.
+
+**Record before executing, not after.** A receipt claimed but never completed is
+the evidence that a write *may* have landed. Record afterwards and that window is
+invisible.
+
+**"Claimed but not completed" is not automatically ambiguous** — this is the part
+worth getting right. On any at-least-once substrate a lease expires whenever a
+worker dies *or merely stalls*, which is routine. `decideToolCallReceipt` needs a
+lease and an attempt counter to tell the three cases apart:
+
+| Receipt state | Decision |
+|---|---|
+| absent | `execute`, attempt 1 |
+| completed | `replay` |
+| failed | `execute`, attempt n+1 |
+| running, lease **live** | `wait` — another attempt owns it and is alive |
+| running, lease **expired**, effect `resumable` | `execute`, attempt n+1 — reclaim |
+| running, lease **expired**, effect `opaque` | `ambiguous` — refuse, surface it |
+
+`resumable` means the host records each sub-operation as it completes, so a
+reclaimed attempt skips what already happened. `opaque` is one indivisible
+effect with no trail, where reclaiming cannot tell "never sent" from "sent, then
+crashed".
+
+Two obligations the package cannot enforce: **lease times must come from the
+store's clock**, because application clocks drift enough to steal a live lease;
+and **every write must gate on the attempt fence** (`status = 'running' AND
+attempts = <mine>`), inside the same transaction as the side effect where the
+store allows it — fencing only the completion write leaves a window where two
+attempts both believe they own the call.
+
+**Hash the raw parsed arguments**, not the output of a schema parse that coerced
+types. `canonicalJson` throws rather than serializing a value it cannot
+represent faithfully — a `Map`, a `Set`, a class instance, `NaN`, a cycle —
+because a silent collision here reads as "same call" and skips a write that
+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.
+
+| 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` |
+
+**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.
+
+```ts
+attempt: async (candidate, cursor) => {
+  let forwarded = false;
+  try {
+    const value = await callProvider(candidate, {
+      onDelta: (text) => { forwarded = true; sendToClient(text); },
+    });
+    return { kind: "success", value };
+  } catch (error) {
+    return { kind: "failure", error: classify(error, candidate, cursor), producedOutput: forwarded };
+  }
+}
+```
+
+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.
+
 ### How to map your transport errors onto the routing taxonomy
 
 `failureDisposition` decides what the router does with a classified failure, but
@@ -608,10 +801,10 @@ keeps a consumer who only wants routing from pulling in the rest.
 | Import | Owns | Reach for it when |
 |---|---|---|
 | `@juno-ai/bind/routing` | Route plans, the planner, the failure taxonomy and the classifier that maps your errors onto it, the plan executor, the circuit breaker, billing-basis arithmetic, config degradation | You call more than one provider or model, or you want retries and fallback governed by one table |
-| `@juno-ai/bind/completion` | Streaming idle watchdog (time-to-first-token, inter-chunk, absolute cap), completion-defect detection, and the structured-output retry predicates | You read a streamed completion |
+| `@juno-ai/bind/completion` | Streaming idle watchdog (time-to-first-token, inter-chunk, absolute cap), streamed tool-call assembly, completion-defect detection, the tool-call argument read (`parseToolCallArguments`), and the structured-output retry predicates | You read a streamed completion |
 | `@juno-ai/bind/contracts` | Turn vocabulary — `TurnFn`, `ModelTurnResult`, `StopReason`, `RunStats` and its folds | You want one seam between your loop and any LLM client, and comparable per-run metrics |
 | `@juno-ai/bind/loop` | `runToolLoop` — the iteration engine: model turn, two-phase tool batch, activation, compaction, interrupts, suspend | You want the agent loop itself, not just the pieces to build one |
-| `@juno-ai/bind/run` | Wall-clock deadline, failure classification, coalesced heartbeat, tool-batch pooling, child-run lineage and admission, poll backoff | A run must be bounded, observable, and able to say *why* it stopped — or it can spawn runs of its own |
+| `@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 |
@@ -628,6 +821,17 @@ fact (`aborted` / `completion_defect` / `network` / `http` + category);
 propagate. Putting routing logic in a transport is the one way to break the
 guarantee that identical inputs produce identical plans.
 
+**Routing — an attempt that already produced output is never replayed.** Every
+other input to a disposition is a property of the *error*; this one is a
+property of the *attempt*, and only your transport knows it. A transport that
+buffers the whole completion can always replay; one that forwards deltas to a
+live view has already shown someone tokens, and retrying — on the same endpoint
+or another provider — appends a second partial answer to what they are reading.
+Set `producedOutput: true` on the failure outcome and the executor withholds all
+traversal. **If you stream to a UI and do not set it, you have this bug.** The
+breaker still records the failure: the endpoint really did fail, and hiding that
+because it failed late is backwards.
+
 **Routing — a healthy endpoint must not be punished for a bad request.**
 Request-shaped rejections (a 400, a moderation refusal) traverse to another
 provider but record **no** breaker failure. Otherwise one caller's malformed or
@@ -650,6 +854,22 @@ its runs are on the queue is not bounded, it is billed. A rule whose measurement
 is `NaN` or `Infinity` refuses rather than admits — every comparison is false
 against `NaN`, so the naive reading of a broken count is an unbounded chain.
 
+**Run — "could not measure" is an omission, never a sentinel.** The refusal
+above is for a count you *did* supply and that came back broken. A bound you
+could not measure at all — the query threw, the counter was unreachable — is
+expressed by leaving that rule out of the array, which admits. The two are
+opposite answers to opposite questions, and passing `NaN` for "unknown" turns a
+transient database blip into every agent in your system refusing to run. Which
+of the two a given failure is is yours to decide; the harness only judges what
+it was handed.
+
+**Completion — the zero-argument rule has two halves and they must agree.**
+`detectCompletionDefect` decides a tool call with *empty* arguments is
+legitimate and passes it through; `parseToolCallArguments` is what then reads
+it as the zero-argument call it is. Both read one `toolCallArgumentsAbsent`, so
+adopting only the detection half means independently reinventing the matching
+parse — and getting it wrong the way everyone does, with a bare `JSON.parse`.
+
 **Run — chain lineage is "null means me".** A root run's `rootRunId` and
 `parentRunId` are both `null`, because a chain's origin has no id to point at
 until its own row exists. Read any chain's root as `chain.rootRunId ?? runId`;
@@ -1124,13 +1344,15 @@ import { admitChildRun, descendChain, type ChainRule } from "@juno-ai/bind/run";
 const rules: ChainRule[] = [
   { kind: "depth", parentDepth: chain.depth, maxDepth: 5 },
   { kind: "chain_budget", runsInChain: await countRunsInChain(chain), maxRuns: 50 },
+  { kind: "pair_seen", alreadyPaired: await hasPairedInChain(chain, targetId) },
   { kind: "pair_cooldown", msSinceLastSpawn: await msSinceLastSpawn(runId), cooldownMs: 30_000 },
+  { kind: "tenant_rate", runsInWindow: await countRecentRuns(tenantId), maxRuns: 100, windowMs: 30_000 },
   { kind: "tenant_ceiling", activeRuns: await countActiveRuns(tenantId), maxActiveRuns: 200 },
 ];
 
 const admission = admitChildRun(rules);
 if (!admission.admitted) {
-  log.warn("child run refused", { rule: admission.rule });
+  log.warn("child run refused", { rule: admission.rule, retryable: admission.retryable });
   return { success: false, kind: "validation", error: admission.reason };
 }
 ```
@@ -1138,11 +1360,25 @@ if (!admission.admitted) {
 Rules are evaluated in order and the first refusal wins, so you choose which
 reason the model sees. Pick the set against your own cost model: depth caps
 runaway recursion, a chain budget caps a chain that stays shallow but keeps
-fanning out, a pair cooldown stops two runs ping-ponging, and a tenant ceiling
-covers what none of the chain rules can — someone starting a thousand
-independent chains. A broken measurement (`NaN`, `Infinity`) refuses rather
-than admits: every comparison is false against `NaN`, so the naive reading
-would turn a broken count into an unbounded chain.
+fanning out, `pair_seen` allows a given pair to work together once per chain
+and a `pair_cooldown` merely spaces them out, a tenant rate limit bounds a burst
+over a rolling window, and a tenant ceiling bounds what is running *right now* —
+the last two covering what no chain rule can, someone starting a thousand
+independent chains.
+
+A refusal carries `rule` (which bound fired) and `retryable`, which separates a
+bound that clears on its own — a cooldown, a rate window rolling — from one that
+never will, so a caller can choose between waiting and giving up. Only a
+refusal carries them; `retryable === undefined` means there was nothing to
+retry, not "not retryable".
+
+Two failure modes get opposite treatment, and the difference is the part to get
+right. A **broken measurement** (`NaN`, `Infinity`, a negative count) refuses:
+every comparison is false against `NaN`, so the naive reading would turn a
+broken count into an unbounded chain. A bound you **could not measure at all**
+— the count query threw — is expressed by *omitting the rule*, which admits.
+Reaching for `NaN` to mean "unknown" collapses the two and makes a transient
+database blip refuse every child run you have.
 
 `descendChain` handles the lineage arithmetic, including the root-id fallback
 that is easy to get backwards — a first-generation child adopts its parent's
@@ -1220,7 +1456,16 @@ an oversight.
   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; the assistant message itself still arrives whole.
+  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.
 
 ---
 

package/completion/defects.js

@@ -18,6 +18,7 @@
  * any SDK's message class, so a host assembling chunks by hand and a host
  * handing over an `openai` message both fit without a cast.
  */
+import { toolCallArgumentsAbsent } from "./tool-calls.js";
 /**
  * Additional attempts when a structured-output call returns content that will
  * not parse as JSON: the initial call plus this many retries. Providers
@@ -79,10 +80,11 @@ export function detectCompletionDefect(completion, cutByTokenLimit) {
             const args = toolCall?.function?.arguments;
             if (typeof args !== "string")
                 return false;
-            const rawArgs = args.trim();
-            if (rawArgs.length === 0)
+            // The same predicate the dispatcher reads, so the two halves of the
+            // zero-argument rule cannot drift — see `tool-calls.ts`.
+            if (toolCallArgumentsAbsent(args))
                 return cutByTokenLimit;
-            return !jsonParses(rawArgs);
+            return !jsonParses(args.trim());
         });
         if (truncated !== undefined) {
             return { kind: "truncated_tool_call", toolCall: truncated };

package/completion/index.d.ts

@@ -1,2 +1,4 @@
 export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, type ChunkOutput, type StreamStall, type StreamWatchdog, type StreamWatchdogOptions, } from "./watchdog.js";
 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";

package/completion/index.js

@@ -1,2 +1,4 @@
 export { createStreamWatchdog, DEFAULT_TIME_TO_FIRST_TOKEN_MS, DEFAULT_INTER_CHUNK_MS, DEFAULT_MAX_CALL_DURATION_MS, } from "./watchdog.js";
 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";

package/completion/stream-assembly.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Assembling streamed tool calls out of the deltas a provider sends.
+ *
+ * `detectCompletionDefect` and `parseToolCallArguments` both consume a
+ * *finished* tool call, which quietly assumes something turned chunks into one.
+ * That something is this module. Until now every host wrote it, and the loop
+ * looks trivial enough that it usually gets written from memory — which is the
+ * problem, because four of its details are wrong in the obvious version and all
+ * four fail silently:
+ *
+ *  1. **Key by `index`, not by arrival order.** Deltas for index 1 can arrive
+ *     before index 0. Pushing onto an array in arrival order transposes the
+ *     calls, and both still parse, so nothing errors — the model just gets the
+ *     wrong tool's arguments.
+ *  2. **`id` can arrive in any chunk**, not necessarily the first for its
+ *     index. Reading it only when the slot is created leaves the call with an
+ *     empty id, and the `tool` message that answers it then pairs with nothing.
+ *  3. **`name` is concatenated, not assigned.** Providers split it across
+ *     chunks. Assigning keeps only the last fragment (`_file` from
+ *     `read_file`), which surfaces as an unknown-tool error naming a tool the
+ *     model never asked for.
+ *  4. **Order the result by index at the end.** `Map` iterates in insertion
+ *     order, which is arrival order, which is (1) again at the finish line.
+ *
+ * A fifth is this module's own to avoid: **a missing `index` is not a malformed
+ * one.** A provider that omits the field is describing a single call; one that
+ * sends `-1` or `"0"` is unintelligible. Dropping both loses a call the model
+ * asked for, and loses it silently, because the batch still comes back
+ * non-empty and defect detection sees nothing wrong.
+ *
+ * **The accumulator is unbounded by design and the host must bound the stream.**
+ * There is no cap on distinct indices or on accumulated argument bytes — a
+ * provider streaming either without limit will grow this `Map` until the
+ * process dies. That is the host's to prevent, with an inter-chunk watchdog
+ * (`createStreamWatchdog`), a completion-token cap, or a byte budget; a
+ * primitive that guessed a limit would break a legitimate large batch.
+ *
+ * Everything here is pure and structural. The host owns the transport — SSE
+ * framing, byte decoding, `[DONE]` — and passes the per-chunk delta arrays in.
+ */
+/**
+ * One provider's tool-call delta. Structural rather than tied to an SDK: the
+ * fields are those the OpenAI streaming protocol defines, and every field but
+ * `index` is optional because a chunk may carry any subset of them.
+ */
+export interface ToolCallDelta {
+    /**
+     * The call's position in the batch. Optional because a provider describing a
+     * single call may omit it — those fold into one slot rather than being
+     * dropped. A *present* but non-integer or negative value is malformed and is
+     * counted in {@link ToolCallAccumulator.droppedDeltas}.
+     */
+    readonly index?: number | undefined;
+    readonly id?: string | undefined;
+    /**
+     * Carried for structural compatibility and deliberately **not** read:
+     * `assembled()` always emits `"function"`. Every streamed tool call in the
+     * OpenAI protocol is a function call, and a non-function type
+     * (`type: "custom"`) does not arrive as a delta stream — `defects.ts` and
+     * `parseToolCallArguments` handle that shape on the assembled message. If a
+     * provider ever streams one, this is the line to revisit.
+     */
+    readonly type?: string | undefined;
+    readonly function?: {
+        readonly name?: string | undefined;
+        readonly arguments?: string | undefined;
+    } | undefined;
+}
+/** A tool call assembled from its deltas, ready to dispatch or inspect. */
+export interface AssembledToolCall {
+    readonly id: string;
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly arguments: string;
+    };
+}
+/**
+ * Accumulates tool-call deltas across the chunks of one completion.
+ *
+ * Stateful because a stream is: the host calls {@link observe} per chunk and
+ * {@link assembled} once at the end. One accumulator per completion — reusing
+ * one across two calls merges them.
+ */
+export interface ToolCallAccumulator {
+    /** Fold one chunk's deltas in. Safe to call with an empty array. */
+    observe(deltas: readonly ToolCallDelta[] | undefined): void;
+    /** Whether any delta has been seen — cheaper than assembling to find out. */
+    readonly isEmpty: boolean;
+    /**
+     * Deltas discarded because their `index` was present but unusable — not an
+     * integer, or negative. Non-zero means the model asked for a call that is
+     * **not** in {@link assembled}, and nothing downstream can tell: the batch
+     * comes back non-empty, so defect detection sees no defect and no retry
+     * fires. Log it at minimum; a host that would rather fail the turn than
+     * answer a partial batch has to decide that here.
+     *
+     * A delta with **no** `index` is not counted — that is a provider describing
+     * a single call, and it is assembled rather than dropped.
+     */
+    readonly droppedDeltas: number;
+    /**
+     * The calls so far, ordered by the provider's `index`. Returns a fresh array
+     * each call and does not end accumulation, so it is safe to inspect mid-stream.
+     */
+    assembled(): AssembledToolCall[];
+}
+export declare function createToolCallAccumulator(): ToolCallAccumulator;

package/completion/stream-assembly.js

@@ -0,0 +1,117 @@
+/**
+ * Assembling streamed tool calls out of the deltas a provider sends.
+ *
+ * `detectCompletionDefect` and `parseToolCallArguments` both consume a
+ * *finished* tool call, which quietly assumes something turned chunks into one.
+ * That something is this module. Until now every host wrote it, and the loop
+ * looks trivial enough that it usually gets written from memory — which is the
+ * problem, because four of its details are wrong in the obvious version and all
+ * four fail silently:
+ *
+ *  1. **Key by `index`, not by arrival order.** Deltas for index 1 can arrive
+ *     before index 0. Pushing onto an array in arrival order transposes the
+ *     calls, and both still parse, so nothing errors — the model just gets the
+ *     wrong tool's arguments.
+ *  2. **`id` can arrive in any chunk**, not necessarily the first for its
+ *     index. Reading it only when the slot is created leaves the call with an
+ *     empty id, and the `tool` message that answers it then pairs with nothing.
+ *  3. **`name` is concatenated, not assigned.** Providers split it across
+ *     chunks. Assigning keeps only the last fragment (`_file` from
+ *     `read_file`), which surfaces as an unknown-tool error naming a tool the
+ *     model never asked for.
+ *  4. **Order the result by index at the end.** `Map` iterates in insertion
+ *     order, which is arrival order, which is (1) again at the finish line.
+ *
+ * A fifth is this module's own to avoid: **a missing `index` is not a malformed
+ * one.** A provider that omits the field is describing a single call; one that
+ * sends `-1` or `"0"` is unintelligible. Dropping both loses a call the model
+ * asked for, and loses it silently, because the batch still comes back
+ * non-empty and defect detection sees nothing wrong.
+ *
+ * **The accumulator is unbounded by design and the host must bound the stream.**
+ * There is no cap on distinct indices or on accumulated argument bytes — a
+ * provider streaming either without limit will grow this `Map` until the
+ * process dies. That is the host's to prevent, with an inter-chunk watchdog
+ * (`createStreamWatchdog`), a completion-token cap, or a byte budget; a
+ * primitive that guessed a limit would break a legitimate large batch.
+ *
+ * Everything here is pure and structural. The host owns the transport — SSE
+ * framing, byte decoding, `[DONE]` — and passes the per-chunk delta arrays in.
+ */
+export function createToolCallAccumulator() {
+    const byIndex = new Map();
+    // Deltas carrying no `index` at all fold together here, in their OWN
+    // variable rather than a reserved key in `byIndex`. A sentinel index would
+    // share a keyspace with real ones — `Number.MAX_SAFE_INTEGER` is a legal
+    // index — and an explicit delta at that index would merge with the implicit
+    // call, concatenating two tools' names into one. That is footgun 3 of this
+    // module's own header, re-created by the fix for footgun 5.
+    //
+    // A missing index is distinct from a MALFORMED one and they must not be
+    // treated alike: a provider that omits the field is describing a single call
+    // and is intelligible, while one that sends `-1` or `"0"` is not.
+    let implicit = null;
+    let dropped = 0;
+    const upsert = (existing) => existing ?? { id: "", name: "", args: "" };
+    const fold = (call, delta) => {
+        // Read `id` on EVERY delta, not just the first: providers are free to send
+        // it late, and a call assembled without one cannot be answered.
+        if (typeof delta.id === "string" && delta.id !== "")
+            call.id = delta.id;
+        // Both are concatenated. `arguments` is obviously chunked; `name` is less
+        // obviously so, and assigning it keeps only the final fragment.
+        if (delta.function?.name)
+            call.name += delta.function.name;
+        if (delta.function?.arguments)
+            call.args += delta.function.arguments;
+    };
+    return {
+        observe(deltas) {
+            // `== null` rather than `=== undefined`: a transport that sets the field
+            // to `null` would otherwise reach `for...of` and throw.
+            if (deltas == null)
+                return;
+            for (const delta of deltas) {
+                const index = delta.index;
+                if (index === undefined || index === null) {
+                    implicit = upsert(implicit);
+                    fold(implicit, delta);
+                    continue;
+                }
+                // A malformed index cannot be placed. Dropping loses that call;
+                // guessing a slot corrupts a different one, which is worse — a lost
+                // call reads as missing, a misfiled one reads as valid. The drop is
+                // counted rather than silent, because the host is the only layer that
+                // can decide whether a lost call is worth failing the turn over.
+                if (!Number.isInteger(index) || index < 0) {
+                    dropped += 1;
+                    continue;
+                }
+                const call = upsert(byIndex.get(index));
+                byIndex.set(index, call);
+                fold(call, delta);
+            }
+        },
+        get isEmpty() {
+            return byIndex.size === 0 && implicit === null;
+        },
+        get droppedDeltas() {
+            return dropped;
+        },
+        assembled() {
+            const ordered = [...byIndex.entries()]
+                .sort(([left], [right]) => left - right)
+                .map(([, call]) => call);
+            // The implicit call sorts last: it has no index to place it by, and a
+            // provider that mixes indexed and index-less deltas has told us nothing
+            // about where it belongs.
+            if (implicit !== null)
+                ordered.push(implicit);
+            return ordered.map((call) => ({
+                id: call.id,
+                type: "function",
+                function: { name: call.name, arguments: call.args },
+            }));
+        },
+    };
+}