@juno-ai/bind 9.0.0 → 10.0.0

package/loop/tool-loop.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type RunStats, type StopReason } from "../contracts/turn.js";
 /**
  * The agent iteration engine: call the model, run the tools it asked for,
  * repeat until it stops asking. Everything that *happens* as a result — status
@@ -19,11 +20,13 @@ import type OpenAI from "openai";
  *    than thrown. Without it they are invisible — the model sees them, your
  *    logs do not.
  *
- * Turn accounting is deliberately the flat usage the loop needs to run
- * (`ToolLoopTurn`), not the richer `ModelTurnResult` in `@juno-ai/bind/contracts`
- * with its timings. The two describe the same event at different resolutions
- * and converge when the loop learns to accumulate `RunStats` directly; until
- * then a host that wants throughput metrics folds them alongside.
+ * Turn accounting is the flat usage a host's `callModel` returns
+ * (`ToolLoopTurn`), not the richer `ModelTurnResult` in
+ * `@juno-ai/bind/contracts` with its timings. The loop bridges them: it
+ * measures each `callModel` with an injectable `now` and folds the pair
+ * through `accumulateTurn`, so `runToolLoop` returns a full `RunStats`
+ * without a host changing the shape it already returns. `ttftMs` is the one
+ * field that cannot cross — only the transport sees the first byte.
  */
 /** One model completion's message + the provider usage the loop accounts for. */
 export interface ToolLoopTurn {
@@ -31,6 +34,12 @@ export interface ToolLoopTurn {
     inputTokens: number;
     outputTokens: number;
     costCents: number;
+    /**
+     * Provider-reported cached input tokens, when the transport can report them.
+     * Optional — omit it (or pass `null`) and the run's `cachedInputTokens` total
+     * simply does not count this turn, rather than counting it as a zero.
+     */
+    cachedInputTokens?: number | null;
 }
 /**
  * Outcome of running one tool call inside an assistant `tool_calls` batch.
@@ -82,6 +91,8 @@ export interface CompactionApplied {
     inputTokens: number;
     outputTokens: number;
     costCents: number;
+    /** Provider-reported cached input tokens for the compaction call, if known. */
+    cachedInputTokens?: number | null;
     /** Persist the compacted session + activity row. Runs after accounting. */
     persist: () => Promise<void>;
 }
@@ -123,10 +134,79 @@ export interface ToolLoopState {
     };
 }
 export type RunStatus = "thinking" | "thinking_with_tools" | "executing_tools";
+/**
+ * A tool asked the loop to activate a plugin or an instruction module, and the
+ * port that would do it was not wired.
+ *
+ * Reported through `onToolCallRejected` rather than thrown: the call itself
+ * succeeded and its tool message is already correct, so failing the run would
+ * be worse than the missing activation. But it must not be silent — before
+ * these ports were optional this was a compile error, and the runtime symptom
+ * (an agent that keeps loading a plugin it never receives) points nowhere near
+ * the cause.
+ *
+ * Match on `error.name === "MissingActivationPortError"` rather than
+ * `instanceof` if you consume this package from a projected or re-bundled copy
+ * — two copies of a class in one module graph make `instanceof` silently
+ * false, and this package is Copybara-projected and republished.
+ */
+export declare class MissingActivationPortError extends Error {
+    readonly port: "activatePlugins" | "activateSkills";
+    readonly name = "MissingActivationPortError";
+    constructor(port: "activatePlugins" | "activateSkills");
+}
+/**
+ * What a completed loop reports back.
+ *
+ * Returned rather than folded into `ToolLoopState` because these are the run's
+ * *conclusion*, not its live progress: a caller reads `state` mid-run for a
+ * heartbeat, and reads this once, after. Before it existed every host
+ * re-derived the outcome from three flags and an iteration count, and each got
+ * a slightly different answer.
+ */
+export interface ToolLoopResult {
+    /**
+     * Why the loop stopped. See {@link StopReason} — `deadline` arrives as a
+     * thrown error rather than a value, and is never returned here.
+     *
+     * `aborted` means only "the batch signal was set, or `shouldStop` said so".
+     * It does not say *which*, because a combined signal cannot. A host that
+     * needs timeout-vs-cancellation reaches for its own `RunDeadline` (and
+     * `classifyRunFailure`), not for this value.
+     */
+    readonly stopReason: StopReason;
+    /**
+     * Cumulative accounting for the run: turns, dispatched tool calls, tokens
+     * (including provider-reported cached input), cost, and the model-time vs
+     * tool-time split with a per-tool breakdown.
+     *
+     * **`stats` is this invocation's contribution alone**; `state` is whatever
+     * the caller seeded plus that. They match only when the caller seeded zeros
+     * — a host resuming a run seeds `state` from the stored totals, and then
+     * `state.costCents` is the run's lifetime cost while `stats.costCents` is
+     * this leg's. Bill from whichever you mean, and do not substitute one for
+     * the other.
+     *
+     * They also differ on tool calls on purpose: `state.toolCalls` counts what
+     * the model *requested* (it drives a live progress indicator, so it has to
+     * rise the moment a batch is dispatched), while `stats.toolCalls` counts
+     * what actually *ran*. An aborted batch is exactly the gap between them.
+     *
+     * Both are lost if the loop throws — a deadline, a cancellation, or a fatal
+     * tool error leaves no return value, so `state` (which is mutated in place)
+     * is the only accounting that survives those exits.
+     */
+    readonly stats: RunStats;
+}
 export interface ToolLoopParams {
     state: ToolLoopState;
-    /** Active plugin set — read to build tool defs, grown by `activatePlugins`. */
-    activePlugins: Set<string>;
+    /**
+     * Active plugin set. The loop does not read it — `buildTools` and
+     * `activatePlugins` are the host's own closures over it — so it is optional
+     * and passing one is purely a convenience for a host that likes threading it
+     * through explicitly.
+     */
+    activePlugins?: Set<string>;
     maxIterations: number;
     /** Call the model with the current transcript + tool defs. `onOutputProgress`
      *  (optional) receives a running estimate of THIS call's output tokens as the
@@ -137,15 +217,38 @@ export interface ToolLoopParams {
     buildTools: () => OpenAI.ChatCompletionTool[];
     /** Execute one tool call → the `tool` message + control signals. */
     runToolCall: (toolCall: OpenAI.ChatCompletionMessageToolCall) => Promise<ToolCallOutcome>;
-    /** Activate newly loaded plugins (mutate the catalog/active set). */
-    activatePlugins: (pluginNames: string[]) => void;
+    /**
+     * Activate newly loaded plugins (mutate the catalog/active set). Optional:
+     * a host with a fixed tool surface has nothing to activate, and requiring an
+     * empty function from it bought nothing.
+     */
+    activatePlugins?: (pluginNames: string[]) => void;
     /**
      * Activate newly loaded skills: inject their bodies into the system prompt's
      * instructions section and refresh the catalog. Async because a host may
      * re-read the module body from storage. Expected to no-op for a ref the agent
-     * cannot access — the loop does not pre-validate them.
+     * cannot access — the loop does not pre-validate them. Optional, as above.
+     */
+    activateSkills?: (skillRefs: string[]) => Promise<void> | void;
+    /**
+     * Clock for the model-time and tool-time measurements in
+     * {@link ToolLoopResult.stats}. Defaults to `Date.now`, the package's one
+     * sanctioned ambient-clock exception; inject a fake to make timing
+     * assertions deterministic.
+     *
+     * **Must be a real monotonic clock when tools can run concurrently.** Each
+     * call records `now()` at dispatch and again when it settles, so a shared
+     * counter that only advances when some *other* call asks it to will charge
+     * one tool for another's time. A cooperatively-advanced fake is fine for a
+     * serial batch (`runsSerially`), and fine for the model-time figures always.
+     *
+     * Measured *around* `callModel`, so the number includes whatever that
+     * function does internally — a defect retry, a fallback provider, a routing
+     * hop. That is the honest figure for cost-and-latency accounting: it is what
+     * the turn actually took. A host that wants the successful attempt's
+     * generation time alone already has it, inside its own transport.
      */
-    activateSkills: (skillRefs: string[]) => Promise<void> | void;
+    now?: () => number;
     /**
      * Must this call run on its own, before the rest of its batch?
      *
@@ -270,5 +373,7 @@ export interface ToolLoopParams {
  * Mutates `state` (messages + token accumulators) in place. That is deliberate
  * rather than a return value: a caller's heartbeat reads live totals off it
  * mid-loop, which a returned result could not provide until the run ended.
+ * The {@link ToolLoopResult} it *returns* is the complementary half — the
+ * run's conclusion, which only exists once the loop is over.
  */
-export declare function runToolLoop(params: ToolLoopParams): Promise<void>;
+export declare function runToolLoop(params: ToolLoopParams): Promise<ToolLoopResult>;

package/loop/tool-loop.js

@@ -1,4 +1,56 @@
 import { runToolCallsPooledByTool, AbortedToolCallError, } from "../run/tool-batch.js";
+import { accumulateAuxiliarySpend, accumulateToolCall, accumulateTurn, emptyRunStats, } from "../contracts/turn.js";
+import { toolResultMessage } from "../plugins/tool-message.js";
+// Imported from the module, not the `tools` barrel: this subpath's runtime
+// graph is deliberately free of `zod`, which the barrel's siblings pull in.
+import { stripControlChars } from "../tools/control-chars.js";
+/**
+ * A tool asked the loop to activate a plugin or an instruction module, and the
+ * port that would do it was not wired.
+ *
+ * Reported through `onToolCallRejected` rather than thrown: the call itself
+ * succeeded and its tool message is already correct, so failing the run would
+ * be worse than the missing activation. But it must not be silent — before
+ * these ports were optional this was a compile error, and the runtime symptom
+ * (an agent that keeps loading a plugin it never receives) points nowhere near
+ * the cause.
+ *
+ * Match on `error.name === "MissingActivationPortError"` rather than
+ * `instanceof` if you consume this package from a projected or re-bundled copy
+ * — two copies of a class in one module graph make `instanceof` silently
+ * false, and this package is Copybara-projected and republished.
+ */
+export class MissingActivationPortError extends Error {
+    port;
+    name = "MissingActivationPortError";
+    constructor(port) {
+        super(`A tool outcome asked the loop to activate, but no \`${port}\` was supplied. ` +
+            `Wire the port, or stop returning activation fields from \`runToolCall\`.`);
+        this.port = port;
+    }
+}
+/**
+ * The key a tool call is measured under in {@link RunStats.toolTimeBreakdownMs}.
+ *
+ * Mirrors the batch's pooling key rather than reading `tc.function.name`: the
+ * wire union has a `custom` member with its name on a different field, and a
+ * host may assemble a call with no `function` at all. Synthetic keys are
+ * fenced with `__` so they cannot collide with a real tool called `custom`.
+ */
+function toolCallStatsKey(tc) {
+    switch (tc.type) {
+        case "function":
+            return tc.function?.name ?? "__unnamed__";
+        case "custom":
+            return `__custom__:${tc.custom?.name ?? "unnamed"}`;
+        default: {
+            // Not `never`: this union is a third party's, and a member it grows
+            // later must not become a type error in a consumer that never sees one.
+            const unknownCall = tc;
+            return `__${unknownCall.type ?? "unknown"}__`;
+        }
+    }
+}
 /**
  * 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
@@ -11,9 +63,48 @@ import { runToolCallsPooledByTool, AbortedToolCallError, } from "../run/tool-bat
  * Mutates `state` (messages + token accumulators) in place. That is deliberate
  * rather than a return value: a caller's heartbeat reads live totals off it
  * mid-loop, which a returned result could not provide until the run ended.
+ * The {@link ToolLoopResult} it *returns* is the complementary half — the
+ * run's conclusion, which only exists once the loop is over.
  */
 export async function runToolLoop(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;
+    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, now = Date.now, ensureNotCancelled, throwIfTimedOut, onStatus, signal, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
+    let stats = emptyRunStats();
+    // The default is the outcome of falling out of the `for` — every other exit
+    // assigns before it breaks. Seeding it here rather than at each `break` means
+    // a future exit path that forgets to set one reports "we ran out of
+    // iterations", which is the conservative lie: it says the run did NOT finish.
+    let stopReason = "iteration_limit";
+    /**
+     * Run one tool call, recording its duration against its tool name.
+     *
+     * Wrapped rather than measured at the two call sites because the serial and
+     * pooled phases both dispatch, and a call that *throws* still consumed the
+     * time — a `finally` is the only way to catch both halves of that in one
+     * place. Refused calls never reach here (the pool rejects them at claim
+     * time), which is exactly why `stats.toolCalls` counts dispatches.
+     */
+    const dispatchToolCall = async (tc) => {
+        const startedAt = now();
+        try {
+            return await runToolCall(tc);
+        }
+        finally {
+            // A throw in a `finally` REPLACES the value the `try` produced, so
+            // measuring a call must never be able to fail. It once could: reading
+            // `tc.function.name` unguarded turned a tool that ran — side effect and
+            // all — into a synthesized "it failed" the model then acted on. The
+            // wire type says `function` is always there; this repo knows better
+            // (`completion/tool-calls.ts` types it optional, and the host's own
+            // dispatcher reads it with an `in` check for exactly this reason).
+            try {
+                stats = accumulateToolCall(stats, toolCallStatsKey(tc), now() - startedAt);
+            }
+            catch {
+                // Accounting is observability. Losing a measurement is survivable;
+                // losing the call's outcome is not.
+            }
+        }
+    };
     // 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.
@@ -29,15 +120,36 @@ export async function runToolLoop(params) {
     // provider count no longer reflects the compacted array, so drop it — the
     // auto-compaction check skips while it's 0 (preventing an immediate
     // re-trigger), and the next turn records a fresh real count.
-    const applyCompactionResult = (result) => {
+    const applyCompactionResult = (result, modelTimeMs) => {
         state.inputTokens += result.inputTokens;
         state.outputTokens += result.outputTokens;
         state.costCents += result.costCents;
+        // Real spend, but not an agent turn — a compaction is the harness talking
+        // to itself. Counting it in `stats.turns` would make that number
+        // incomparable with `maxIterations`.
+        stats = accumulateAuxiliarySpend(stats, {
+            inputTokens: result.inputTokens,
+            outputTokens: result.outputTokens,
+            costCents: result.costCents,
+            cachedInputTokens: result.cachedInputTokens ?? null,
+            modelTimeMs,
+        });
         state.messages.length = 0;
         state.messages.push(...result.messages);
         state.lastPromptTokens = 0;
         state.lastOutputTokens = 0;
     };
+    // Compact, account, then persist — in that order, and timing only the model
+    // pass. `persist` is host I/O; folding it into `modelTimeMs` would inflate
+    // the one number that exists to isolate the provider's contribution.
+    // `compact` is passed in rather than read from the closure so each call site
+    // narrows the optional itself and no non-null assertion is needed.
+    const compactNow = async (compact, trigger) => {
+        const startedAt = now();
+        const compacted = await compact(trigger, state.messages);
+        applyCompactionResult(compacted, now() - startedAt);
+        await compacted.persist();
+    };
     for (let iteration = 0; iteration < maxIterations; iteration++) {
         throwIfTimedOut?.();
         await ensureNotCancelled?.();
@@ -57,6 +169,7 @@ export async function runToolLoop(params) {
         // the real total below is free to correct downward.
         const baseOutputTokens = state.outputTokens;
         let progressHighWater = baseOutputTokens;
+        const turnStartedAt = now();
         const result = await callModel(state.messages, tools.length > 0 ? tools : undefined, 
         // Carry the cumulative tool count alongside the streamed token estimate so
         // the pill shows both; no tools run *during* a model call, so the count is
@@ -67,6 +180,28 @@ export async function runToolLoop(params) {
                 onProgressUpdate(progressHighWater, state.toolCalls);
             }
             : undefined);
+        // Folded through the shared `accumulateTurn` rather than incremented
+        // field-by-field, so `stats` and every other producer of `RunStats` (child
+        // runs, a host's own transport) agree on what a turn contributes — notably
+        // the derived `outputTokensPerSecond`, which is recomputed from totals
+        // rather than averaged.
+        stats = accumulateTurn(stats, {
+            message: result.message,
+            usage: {
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                // `null` when the transport did not report one — `accumulateTurn`
+                // then contributes nothing for this turn rather than counting a zero,
+                // which is why the total reads as a floor.
+                cachedInputTokens: result.cachedInputTokens ?? null,
+                costCents: result.costCents,
+            },
+            timings: {
+                // Only the transport sees the first byte. The loop sees the call.
+                ttftMs: null,
+                generationMs: now() - turnStartedAt,
+            },
+        });
         state.inputTokens += result.inputTokens;
         state.outputTokens += result.outputTokens;
         state.costCents += result.costCents;
@@ -87,10 +222,16 @@ export async function runToolLoop(params) {
         }
         // Force-flush progress so each iteration bumps the heartbeat at least once.
         await flushProgress?.();
-        // Mid-run stop (e.g. the agent was disabled while running). Emit the
-        // iteration's final progress (the real cumulative token total) before bailing.
-        if (await shouldStop?.()) {
+        // Mid-run stop (e.g. the agent was disabled while running). Asked once and
+        // held, because *whether* to stop and *what to call it* are answered at two
+        // different points below, and asking a host predicate twice could get two
+        // answers.
+        const stopRequested = (await shouldStop?.()) ?? false;
+        if (stopRequested && assistantMessage.tool_calls?.length) {
+            // Still mid-task, and the batch has not run. Emit the iteration's final
+            // progress (the real cumulative token total) before bailing.
             onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            stopReason = "aborted";
             break;
         }
         // Count this iteration's tool batch (a single iteration can request several
@@ -110,9 +251,26 @@ export async function runToolLoop(params) {
             // spin forever.
             const nudge = await onTurnWouldEnd?.(assistantMessage, state.toolCalls);
             if (nudge && nudge.trim()) {
+                // The host's own hook says this turn was NOT a finished answer — it
+                // was a stall worth pushing past. If the host also asked to stop, that
+                // wins, but the outcome is an abort: calling it `done` would report a
+                // run the host itself judged unfinished as a successful answer.
+                if (stopRequested) {
+                    onProgressUpdate?.(state.outputTokens, state.toolCalls);
+                    stopReason = "aborted";
+                    break;
+                }
                 state.messages.push({ role: "user", content: nudge });
                 continue;
             }
+            // A tool-less turn no hook wanted to push past is a finished answer: it
+            // is already in `state.messages` and has already gone out through
+            // `onAssistantMessage`. `done` even when the host asked to stop in the
+            // same breath — reporting `aborted` would have a host badge a delivered
+            // answer as cancelled, or suppress it.
+            if (stopRequested)
+                onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            stopReason = "done";
             break;
         }
         onStatus?.("executing_tools");
@@ -141,15 +299,11 @@ export async function runToolLoop(params) {
                         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,
-                            }),
-                        },
+                        toolMessage: toolResultMessage(tc.id, {
+                            success: false,
+                            kind: "not_run",
+                            error: aborted.message,
+                        }),
                     };
                     continue;
                 }
@@ -157,18 +311,39 @@ export async function runToolLoop(params) {
                 // activation call (transient network/DB/timeout) doesn't crash the
                 // run — but let a fatal error propagate for an immediate abort.
                 try {
-                    const outcome = await runToolCall(tc);
+                    const outcome = await dispatchToolCall(tc);
                     outcomes[i] = outcome;
                     if (outcome.loadedPluginName) {
-                        activatePlugins([outcome.loadedPluginName]);
+                        if (activatePlugins) {
+                            activatePlugins([outcome.loadedPluginName]);
+                        }
+                        else {
+                            // The port is optional, but silence here is not. An outcome
+                            // carrying `loadedPluginName` is proof this host's tools DO
+                            // reshape the tool surface, so the port's absence is a wiring
+                            // bug, not a host that doesn't need it. Dropped quietly, the
+                            // model gets a success for `load_plugin`, never sees the tools,
+                            // and re-calls it every iteration until the budget is gone.
+                            reportRejection(tc.id, new MissingActivationPortError("activatePlugins"));
+                        }
                     }
                     if (outcome.loadedSkillRef) {
                         // Auto-load the module's owner plugin first so its tools are active
                         // by the time the agent follows the freshly-injected instructions.
                         if (outcome.autoLoadedPlugins?.length) {
-                            activatePlugins(outcome.autoLoadedPlugins);
+                            if (activatePlugins) {
+                                activatePlugins(outcome.autoLoadedPlugins);
+                            }
+                            else {
+                                reportRejection(tc.id, new MissingActivationPortError("activatePlugins"));
+                            }
+                        }
+                        if (activateSkills) {
+                            await activateSkills([outcome.loadedSkillRef]);
+                        }
+                        else {
+                            reportRejection(tc.id, new MissingActivationPortError("activateSkills"));
                         }
-                        await activateSkills([outcome.loadedSkillRef]);
                     }
                 }
                 catch (err) {
@@ -176,14 +351,10 @@ export async function runToolLoop(params) {
                         throw err;
                     reportRejection(tc.id, err);
                     outcomes[i] = {
-                        toolMessage: {
-                            role: "tool",
-                            tool_call_id: tc.id,
-                            content: JSON.stringify({
-                                success: false,
-                                error: err instanceof Error ? err.message : String(err),
-                            }),
-                        },
+                        toolMessage: toolResultMessage(tc.id, {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        }),
                     };
                 }
                 continue;
@@ -191,9 +362,7 @@ export async function runToolLoop(params) {
             deferredIndices.push(i);
             deferredCalls.push(tc);
         }
-        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall, {
-            signal,
-        });
+        const settled = await runToolCallsPooledByTool(deferredCalls, dispatchToolCall, { signal });
         for (let j = 0; j < deferredCalls.length; j++) {
             const origIndex = deferredIndices[j];
             const call = deferredCalls[j];
@@ -210,24 +379,20 @@ export async function runToolLoop(params) {
                     throw settledResult.reason;
                 reportRejection(call.id, settledResult.reason);
                 outcomes[origIndex] = {
-                    toolMessage: {
-                        role: "tool",
-                        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),
-                        }),
-                    },
+                    toolMessage: toolResultMessage(call.id, {
+                        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),
+                    }),
                 };
             }
         }
@@ -249,16 +414,20 @@ export async function runToolLoop(params) {
                         state.suspended = { ...outcome.suspend, resumeKind: "answer" };
                         continue; // withhold this call's tool message
                     }
-                    state.messages.push({
-                        role: "tool",
-                        tool_call_id: outcome.suspend.toolCallId,
-                        content: JSON.stringify({
-                            success: false,
-                            error: "You already have one question waiting for an answer, so this " +
-                                "one was not asked. Wait for the pending answer and then ask " +
-                                "this, or finish the turn with what you have.",
-                        }),
-                    });
+                    // Through the shared encoder, and carrying a `kind`, like every
+                    // other synthesized failure. It was the last hand-rolled envelope in
+                    // this file, which meant the harness itself emitted two error shapes
+                    // in one transcript — the exact thing `toolResultMessage` exists to
+                    // prevent. `conflict` because it is a concurrency loss: the call was
+                    // refused only because another question is already open.
+                    state.messages.push(toolResultMessage(outcome.suspend.toolCallId, {
+                        success: false,
+                        kind: "conflict",
+                        error: "This question was not asked — you already have one waiting " +
+                            "for an answer, and only one can be open at a time. When that " +
+                            "answer arrives, ask this one then, or finish the turn with " +
+                            "what you have.",
+                    }));
                     continue;
                 }
                 // `wake` (e.g. sleep_until): fall through and push the tool message, then
@@ -292,6 +461,12 @@ export async function runToolLoop(params) {
             // 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.
+            //
+            // `aborted`, not `deadline`, even when the signal IS a deadline: by the
+            // time a wall-clock budget and a cancellation are combined into one
+            // `AbortSignal` the loop cannot tell them apart, and `throwIfTimedOut`
+            // above has already had its chance to name a timeout by throwing.
+            stopReason = "aborted";
             break;
         }
         // A tool asked to end the run (it scheduled its own resume, or recorded an
@@ -304,11 +479,14 @@ export async function runToolLoop(params) {
         // suspended call, and that pair must survive verbatim to be resumable.
         if (suspendRequested) {
             if (compactionRequested && applyCompaction && !state.suspended) {
-                const compacted = await applyCompaction("manual", state.messages);
-                applyCompactionResult(compacted);
-                await compacted.persist();
+                await compactNow(applyCompaction, "manual");
             }
             state.endedTurnViaTool = true;
+            // `state.suspended` is set only by the `answer` branch, so its presence
+            // IS the discriminant between "a person has to reply" and "this comes
+            // back on its own". Reading it here, once, is what saves every host
+            // from reading it themselves.
+            stopReason = state.suspended ? "waiting_for_reply" : "resuming_later";
             break;
         }
         await ensureNotCancelled?.();
@@ -317,9 +495,7 @@ export async function runToolLoop(params) {
         // compaction usage BEFORE persisting so a persist failure can't drop the
         // tokens it already consumed.
         if (compactionRequested && applyCompaction) {
-            const compacted = await applyCompaction("manual", state.messages);
-            applyCompactionResult(compacted);
-            await compacted.persist();
+            await compactNow(applyCompaction, "manual");
         }
         // Drain human interrupts queued while the agent was working.
         for (const interrupt of drainInterrupts?.() ?? []) {
@@ -327,7 +503,7 @@ export async function runToolLoop(params) {
             // `[Interrupt from user …]` header line and inject transcript structure.
             // (Internal-only sources today, but a future external caller could surface
             // user-supplied ids.)
-            const safeUserId = interrupt.userId.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "");
+            const safeUserId = stripControlChars(interrupt.userId);
             state.messages.push({
                 role: "user",
                 content: `[Interrupt from user ${safeUserId}]\n${interrupt.content}`,
@@ -341,9 +517,8 @@ export async function runToolLoop(params) {
         if (state.lastPromptTokens > 0 &&
             needsCompaction?.(currentTokens) &&
             applyCompaction) {
-            const compacted = await applyCompaction("auto", state.messages);
-            applyCompactionResult(compacted);
-            await compacted.persist();
+            await compactNow(applyCompaction, "auto");
         }
     }
+    return { stopReason, stats };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "9.0.0",
+  "version": "10.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",
@@ -42,6 +42,10 @@
     "./plugins": {
       "types": "./plugins/index.d.ts",
       "import": "./plugins/index.js"
+    },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing/index.js"
     }
   },
   "peerDependencies": {