@juno-ai/bind 3.0.0 → 5.0.0

package/index.js

@@ -5,17 +5,23 @@
  * completion into tool effects into the next turn's context. This package is
  * the harness that runs that chain.
  *
- * Current surface: the deterministic LLM provider-routing core, the turn
- * vocabulary, the run mechanics (deadline, coalesced heartbeat, failure
- * classification, tool-batch pooling), transcript validation/healing, provider
- * tool-schema sanitization, and the plugin/tool vocabulary with its registry
- * and progressive-disclosure activation (`src/plugins/`, generic over the
- * host's invocation context). The turn kernel arrives in a later phase; see
- * the README for what is deliberately not here yet.
+ * Current surface: the tool-calling turn kernel (`src/loop/` — the iteration
+ * engine itself), the deterministic LLM provider-routing core with its
+ * transport-error classifier, the turn vocabulary, the run mechanics (deadline,
+ * coalesced heartbeat, failure classification, tool-batch pooling, child-run
+ * lineage and admission), the streaming-completion watchdog and completion
+ * defect detection (`src/completion/`), transcript validation/healing, provider
+ * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * progressive-disclosure activation — generic over the host's invocation
+ * context. What is NOT here is
+ * the run driver: starting a run, recording what it did, and delivering its
+ * output. See the README for the rest of what is deliberately absent.
  */
 export * from "./routing/index.js";
+export * from "./completion/index.js";
 export * from "./contracts/index.js";
 export * from "./run/index.js";
 export * from "./transcript/index.js";
 export * from "./tools/index.js";
 export * from "./plugins/index.js";
+export * from "./loop/index.js";

package/loop/index.d.ts

@@ -0,0 +1 @@
+export { runToolLoop, type ToolLoopParams, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type CompactionApplied, type RunStatus, } from "./tool-loop.js";

package/loop/index.js

@@ -0,0 +1 @@
+export { runToolLoop, } from "./tool-loop.js";

package/loop/tool-loop.d.ts

@@ -0,0 +1,260 @@
+import type OpenAI from "openai";
+/**
+ * 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
+ * updates, heartbeats, activity rows, persistence, cancellation — is injected,
+ * so the loop itself does no I/O and holds no host vocabulary.
+ *
+ * Three ports are worth understanding before wiring this up, because each
+ * replaced something the loop previously hardcoded:
+ *
+ *  - **`runsSerially`** decides which calls in a batch must run one at a time,
+ *    ahead of the rest. Not a performance knob: a call that changes what tools
+ *    exist has to take effect before a later call in the same batch tries to
+ *    use them.
+ *  - **`isFatalToolError`** decides which thrown errors abort the run instead
+ *    of becoming a tool error the model can read. Cancellation and "we failed
+ *    to record the result" belong here; a tool that simply failed does not.
+ *  - **`onToolCallRejected`** observes the errors that were synthesized rather
+ *    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.
+ */
+/** One model completion's message + the provider usage the loop accounts for. */
+export interface ToolLoopTurn {
+    message: OpenAI.ChatCompletionMessage;
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+}
+/**
+ * Outcome of running one tool call inside an assistant `tool_calls` batch.
+ *
+ * Every optional field is a **control signal**: the loop branches on it. They
+ * are not host payload passing through — `loadedPluginName` grows the active
+ * set, `requestCompaction` triggers a compaction at the batch boundary, and
+ * `suspend` ends the run. A host's own per-call data belongs inside
+ * `toolMessage`, which the loop only appends.
+ */
+export type ToolCallOutcome = {
+    toolMessage: OpenAI.ChatCompletionToolMessageParam;
+    /**
+     * A plugin this call activated; the loop adds it to the active set at once —
+     * but ONLY from the serial phase. A call that reaches the concurrent phase
+     * has already missed its window (a later call in the same batch could
+     * already be running), so this field is ignored there rather than applied
+     * late. Return it from a call your `runsSerially` selects, or it is dropped.
+     */
+    loadedPluginName?: string;
+    /** An instruction module this call loaded, passed to `activateSkills`. Serial phase only, as above. */
+    loadedSkillRef?: string;
+    /** Plugins the loaded module needs, activated before it. Serial phase only, as above. */
+    autoLoadedPlugins?: string[];
+    /** Compact the transcript at this batch's boundary. */
+    requestCompaction?: boolean;
+    /**
+     * End the run. `answer` records the open call and WITHHOLDS its tool message
+     * — the result is a human's future answer, threaded back on resume — so at
+     * most one may be open at a time; a second in the same batch is answered with
+     * an error rather than left unpaired. `wake` keeps its tool message and
+     * re-enters through a fresh prompt.
+     */
+    suspend?: {
+        toolCallId: string;
+        reason: string;
+        resumeKind: "answer" | "wake";
+        request?: unknown;
+    };
+};
+/**
+ * Result of compacting: the new transcript + the compaction call's own usage,
+ * plus a deferred `persist` step. The loop applies accounting + swaps the
+ * transcript BEFORE calling `persist`, so a persistence failure can't drop the
+ * tokens the compaction LLM call already consumed.
+ */
+export interface CompactionApplied {
+    messages: OpenAI.ChatCompletionMessageParam[];
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+    /** Persist the compacted session + activity row. Runs after accounting. */
+    persist: () => Promise<void>;
+}
+/**
+ * Mutable accumulator threaded through the loop. The caller seeds it and reads
+ * it back after; a shared object (rather than return values) lets the caller's
+ * coalesced heartbeat read live token totals mid-loop. `messages` is mutated in
+ * place (assistant + tool turns appended; replaced wholesale on compaction).
+ */
+export interface ToolLoopState {
+    messages: OpenAI.ChatCompletionMessageParam[];
+    inputTokens: number;
+    outputTokens: number;
+    costCents: number;
+    /** Provider prompt/completion tokens from the most recent turn (0 right after a compaction). */
+    lastPromptTokens: number;
+    lastOutputTokens: number;
+    /** True once any turn has produced a real provider count this run. */
+    hasFreshTokenCount: boolean;
+    /** Cumulative tool calls dispatched this run — the count only, never names or
+     *  results. Feeds a live progress indicator via `onProgressUpdate`. */
+    toolCalls: number;
+    /** True when the loop ended because a tool suspended the run (asked a human a
+     *  question, or scheduled its own resume). Distinguishes an intentional pause
+     *  from an iteration-limit cutoff — without it a caller reports "couldn't
+     *  finish" over a run that stopped exactly where it meant to. */
+    endedTurnViaTool?: boolean;
+    /** Set when a tool suspended the run awaiting an answer: the open tool-call is
+     *  waiting on a human or an external system. The loop withholds that call's
+     *  `tool` message — its result IS the future answer — and ends the run; a
+     *  resume threads the answer back as the matching `role:"tool"` result. At
+     *  most one may be open at a time; extras in the same batch are answered with
+     *  a synthesized error so no second slot is left unpaired. */
+    suspended?: {
+        toolCallId: string;
+        reason: string;
+        resumeKind: "answer";
+        request?: unknown;
+    };
+}
+export type RunStatus = "thinking" | "thinking_with_tools" | "executing_tools";
+export interface ToolLoopParams {
+    state: ToolLoopState;
+    /** Active plugin set — read to build tool defs, grown by `activatePlugins`. */
+    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
+     *  stream flows (throttled ~1 Hz inside the model call); the loop adds the
+     *  prior cumulative before forwarding to `onProgressUpdate`. */
+    callModel: (messages: OpenAI.ChatCompletionMessageParam[], tools: OpenAI.ChatCompletionTool[] | undefined, onOutputProgress?: (estimatedOutputTokens: number) => void) => Promise<ToolLoopTurn>;
+    /** Build the tool definitions for the current active-plugin set (+ MCP). */
+    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 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.
+     */
+    activateSkills: (skillRefs: string[]) => Promise<void> | void;
+    /**
+     * Must this call run on its own, before the rest of its batch?
+     *
+     * True for any call that changes what the later calls can do — activating a
+     * plugin, loading an instruction module. The loop runs those one at a time
+     * and applies each outcome immediately, so a dependent call in the SAME batch
+     * sees the effect. Everything else fans out concurrently, pooled per tool
+     * name.
+     *
+     * Unwired, nothing is serial: every call runs in the concurrent phase, which
+     * is correct for a host whose tools do not reshape the tool surface.
+     */
+    runsSerially?: (toolCall: OpenAI.ChatCompletionMessageToolCall) => boolean;
+    /**
+     * Should this thrown error abort the run rather than become a tool error the
+     * model reads?
+     *
+     * Two things belong here: **cancellation**, which must propagate even when no
+     * `ensureNotCancelled` observer is wired, and a failure to *record* an
+     * outcome — synthesizing "the tool failed" over a persistence failure tells
+     * the model a lie about work that may well have happened.
+     *
+     * Unwired, nothing is fatal: every failure is synthesized into a tool error
+     * and the run continues. That is the safe default for an isolated tool, and
+     * the wrong one as soon as your tools write anything.
+     */
+    isFatalToolError?: (error: unknown) => boolean;
+    /**
+     * A tool call failed and was answered with a synthesized error instead of
+     * throwing. The model sees it either way; without this observer nothing else
+     * does.
+     */
+    onToolCallRejected?: (toolCallId: string, error: unknown) => void;
+    /** Throw to abort (run cancelled). Checked at the top of each iteration and after each batch. */
+    ensureNotCancelled?: () => Promise<void> | void;
+    /** Throw a timeout error if the wall-clock budget is exhausted (checked first each iteration). */
+    throwIfTimedOut?: () => void;
+    /** Phase status for rich client feedback. */
+    onStatus?: (status: RunStatus) => void;
+    /** Intermediate assistant text emitted alongside tool calls. NOTE: when
+     *  `onAssistantMessage` is also wired, a text-with-tools message fires to BOTH
+     *  observers (they have different contracts — see below). Wire only one per
+     *  output surface so the same text isn't delivered twice. */
+    onThinking?: (content: string) => void;
+    /**
+     * Every assistant message that carries non-empty text content, fired the
+     * moment it's produced — whether or not it also requested tools, and including
+     * the final tool-less reply. Unlike `onThinking` (text-with-tools only), this
+     * sees ALL of a turn's assistant text, so a caller can stream each message to
+     * the client as it lands rather than batching them at turn end. Receives the
+     * already-trimmed content.
+     */
+    onAssistantMessage?: (content: string) => void;
+    /** Flush accumulated progress (heartbeat). Called force-true after each turn. */
+    flushProgress?: () => Promise<void> | void;
+    /** Cumulative live progress: the running output-token count (updated
+     *  mid-stream and after each model turn) and the number of tool calls made so
+     *  far this run (the count only — never a name or a result). Called with the
+     *  estimate during streaming and with real totals at each iteration boundary,
+     *  and again right after a batch is dispatched so the count rises promptly. */
+    onProgressUpdate?: (outputTokens: number, toolCalls: number) => void;
+    /** Return true to stop the loop after the current turn (e.g. agent disabled mid-run). */
+    shouldStop?: () => Promise<boolean> | boolean;
+    /**
+     * Called when the model produced a turn with NO tool calls — i.e. the loop is
+     * about to stop. Return a non-empty string to inject it as a synthetic `user`
+     * message and CONTINUE the loop instead of stopping; return null/empty to stop
+     * as normal (the default behavior when unwired). Use it to push a stalled turn
+     * forward — nudging an agent that ended a turn having made no progress at all.
+     * Receives the cumulative tool-call count so the hook can detect exactly that.
+     * MUST be self-bounding (eventually return null); `maxIterations` bounds it
+     * regardless, and the injected `user` message is model-only — a caller that
+     * persists a transcript should ignore `user` turns it didn't originate.
+     *
+     * `cumulativeToolCalls` is the running total across ALL iterations of this run
+     * (not just the current one), so a hook can detect "made zero tool calls the
+     * whole run" — a tool call in any earlier iteration makes it non-zero.
+     */
+    onTurnWouldEnd?: (assistantMessage: OpenAI.ChatCompletionMessage, cumulativeToolCalls: number) => string | null | Promise<string | null>;
+    /** Drain queued human interrupts for this run. */
+    drainInterrupts?: () => Array<{
+        userId: string;
+        content: string;
+    }>;
+    /** Report that an interrupt was received (activity row). */
+    onInterruptReceived?: (interrupt: {
+        userId: string;
+        content: string;
+    }) => Promise<void> | void;
+    /** Decide whether the live context (token count) needs auto-compaction. */
+    needsCompaction?: (currentTokens: number) => boolean;
+    /**
+     * Perform + persist a compaction and return the new transcript + usage. The
+     * loop owns swapping `state.messages` and resetting the live counts; this
+     * callback owns the LLM passes and persistence (session + activity row).
+     */
+    applyCompaction?: (trigger: "manual" | "auto", messages: OpenAI.ChatCompletionMessageParam[]) => Promise<CompactionApplied>;
+}
+/**
+ * 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
+ * `maxIterations` is reached.
+ *
+ * Intrinsic: plugin/module activation, two-phase tool batching, compaction
+ * (manual + auto), interrupt draining, and the suspend protocol. Injected:
+ * every side effect — status, heartbeat, activity, persistence, cancellation.
+ *
+ * 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.
+ */
+export declare function runToolLoop(params: ToolLoopParams): Promise<void>;

package/loop/tool-loop.js

@@ -0,0 +1,288 @@
+import { runToolCallsPooledByTool } 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
+ * `maxIterations` is reached.
+ *
+ * Intrinsic: plugin/module activation, two-phase tool batching, compaction
+ * (manual + auto), interrupt draining, and the suspend protocol. Injected:
+ * every side effect — status, heartbeat, activity, persistence, cancellation.
+ *
+ * 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.
+ */
+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;
+    // 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.
+    const reportRejection = (toolCallId, error) => {
+        try {
+            onToolCallRejected?.(toolCallId, error);
+        }
+        catch {
+            // Nothing useful to do — the reporting channel is the thing that broke.
+        }
+    };
+    // Swap in a freshly-compacted transcript and reset the live counts. The
+    // 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) => {
+        state.inputTokens += result.inputTokens;
+        state.outputTokens += result.outputTokens;
+        state.costCents += result.costCents;
+        state.messages.length = 0;
+        state.messages.push(...result.messages);
+        state.lastPromptTokens = 0;
+        state.lastOutputTokens = 0;
+    };
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        throwIfTimedOut?.();
+        await ensureNotCancelled?.();
+        const tools = buildTools();
+        onStatus?.(iteration === 0 ? "thinking" : "thinking_with_tools");
+        // Stream live token progress: the per-call estimate is added to the
+        // cumulative from prior iterations so a caller's counter rises across a
+        // multi-iteration run. The real cumulative is published right after the
+        // call returns (below), reconciling any estimate drift.
+        //
+        // Clamped to a per-call high-water mark because `callModel` may internally
+        // retry — a defect retry, another provider, the fallback model — and each
+        // attempt restarts its own estimate at zero. Unclamped, a caller's counter
+        // visibly runs backwards mid-turn ("1.2k tokens" → blank → "120 tokens"),
+        // which reads as lost work at exactly the moment the system is recovering
+        // from a fault. The mark is per-call, so the post-call reconciliation to
+        // the real total below is free to correct downward.
+        const baseOutputTokens = state.outputTokens;
+        let progressHighWater = baseOutputTokens;
+        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
+        // whatever has accumulated from prior iterations.
+        onProgressUpdate
+            ? (estCallTokens) => {
+                progressHighWater = Math.max(progressHighWater, baseOutputTokens + estCallTokens);
+                onProgressUpdate(progressHighWater, state.toolCalls);
+            }
+            : undefined);
+        state.inputTokens += result.inputTokens;
+        state.outputTokens += result.outputTokens;
+        state.costCents += result.costCents;
+        state.lastPromptTokens = result.inputTokens;
+        state.lastOutputTokens = result.outputTokens;
+        state.hasFreshTokenCount = true;
+        const assistantMessage = result.message;
+        state.messages.push(assistantMessage);
+        if (assistantMessage.content && assistantMessage.tool_calls?.length) {
+            onThinking?.(assistantMessage.content);
+        }
+        // Stream every assistant text message (with or without tool calls, including
+        // the final tool-less reply) so a caller can surface it the moment it lands.
+        if (typeof assistantMessage.content === "string") {
+            const trimmed = assistantMessage.content.trim();
+            if (trimmed)
+                onAssistantMessage?.(trimmed);
+        }
+        // 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?.()) {
+            onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            break;
+        }
+        // Count this iteration's tool batch (a single iteration can request several
+        // tools at once) BEFORE the single progress emit, so the new tool count rides
+        // the SAME frame as the iteration's real token total. A separate
+        // post-increment emit would be coalesced by a throttled transport and lag
+        // the count behind the tokens it belongs with.
+        const toolCalls = assistantMessage.tool_calls;
+        if (toolCalls && toolCalls.length > 0)
+            state.toolCalls += toolCalls.length;
+        onProgressUpdate?.(state.outputTokens, state.toolCalls);
+        if (!toolCalls || toolCalls.length === 0) {
+            // The model stopped calling tools — normally the turn is done. Give a
+            // caller a chance to push it forward instead: if `onTurnWouldEnd` returns
+            // text, inject it as a synthetic user message and keep looping. The hook
+            // is self-bounding and `maxIterations` is the hard ceiling, so this cannot
+            // spin forever.
+            const nudge = await onTurnWouldEnd?.(assistantMessage, state.toolCalls);
+            if (nudge && nudge.trim()) {
+                state.messages.push({ role: "user", content: nudge });
+                continue;
+            }
+            break;
+        }
+        onStatus?.("executing_tools");
+        // Two-phase batch: run activation calls (`tool-discovery__load_plugin` and
+        // `skills__load_skill`) SERIALLY and activate each immediately (so a
+        // dependent tool from the same batch sees the plugin active / the skill's
+        // owner plugin loaded), then run the rest concurrently, pooled per tool
+        // name. Outcomes are collected by original index and applied in emission
+        // order.
+        const outcomes = new Array(toolCalls.length);
+        const deferredIndices = [];
+        const deferredCalls = [];
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            if (runsSerially?.(tc)) {
+                // 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.
+                try {
+                    const outcome = await runToolCall(tc);
+                    outcomes[i] = outcome;
+                    if (outcome.loadedPluginName) {
+                        activatePlugins([outcome.loadedPluginName]);
+                    }
+                    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);
+                        }
+                        await activateSkills([outcome.loadedSkillRef]);
+                    }
+                }
+                catch (err) {
+                    if (isFatalToolError?.(err))
+                        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),
+                            }),
+                        },
+                    };
+                }
+                continue;
+            }
+            deferredIndices.push(i);
+            deferredCalls.push(tc);
+        }
+        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall);
+        for (let j = 0; j < deferredCalls.length; j++) {
+            const origIndex = deferredIndices[j];
+            const call = deferredCalls[j];
+            const settledResult = settled[j];
+            if (settledResult.status === "fulfilled") {
+                outcomes[origIndex] = settledResult.value;
+            }
+            else {
+                // Let a fatal error abort the run immediately rather than be
+                // synthesized into a tool error — symmetric with the serial path, and
+                // so cancellation propagates even if no `ensureNotCancelled` boundary
+                // observer is wired.
+                if (isFatalToolError?.(settledResult.reason))
+                    throw settledResult.reason;
+                reportRejection(call.id, settledResult.reason);
+                outcomes[origIndex] = {
+                    toolMessage: {
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: JSON.stringify({
+                            success: false,
+                            error: settledResult.reason instanceof Error
+                                ? settledResult.reason.message
+                                : String(settledResult.reason),
+                        }),
+                    },
+                };
+            }
+        }
+        let compactionRequested = false;
+        let suspendRequested = false;
+        for (const outcome of outcomes) {
+            // An `answer`-suspend WITHHOLDS its tool message — the result is the
+            // future answer, threaded back on resume. At most one may be open: the
+            // first becomes `state.suspended`; any additional suspend in the same
+            // batch is answered with a synthesized error so no second slot is left
+            // unpaired. A `wake`-suspend keeps its tool message (it re-enters through
+            // a fresh prompt, not a threaded answer).
+            if (outcome.suspend) {
+                suspendRequested = true;
+                if (outcome.suspend.resumeKind === "answer") {
+                    if (!state.suspended) {
+                        // Rebuild with the literal "answer" kind so the assignment matches
+                        // `ToolLoopState.suspended` (always answer — see its type).
+                        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.",
+                        }),
+                    });
+                    continue;
+                }
+                // `wake` (e.g. sleep_until): fall through and push the tool message, then
+                // end the run — it re-enters via a prompt, not a threaded answer.
+            }
+            state.messages.push(outcome.toolMessage);
+            if (outcome.requestCompaction)
+                compactionRequested = true;
+        }
+        // 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
+        // an intentional pause so a caller doesn't read the trailing tool-calling
+        // turn as an iteration-limit cutoff. Honor an explicit
+        // compaction requested in the same batch so the saved transcript is
+        // compacted — UNLESS a suspend is pending: compacting would rewrite the open
+        // 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();
+            }
+            state.endedTurnViaTool = true;
+            break;
+        }
+        await ensureNotCancelled?.();
+        // Explicit (tool-requested) compaction, flushed at the batch boundary so
+        // the summary sees the full batch of tool responses. Account for the
+        // 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();
+        }
+        // Drain human interrupts queued while the agent was working.
+        for (const interrupt of drainInterrupts?.() ?? []) {
+            // Strip control chars/newlines from the id so it can't break out of the
+            // `[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, "");
+            state.messages.push({
+                role: "user",
+                content: `[Interrupt from user ${safeUserId}]\n${interrupt.content}`,
+            });
+            await onInterruptReceived?.(interrupt);
+        }
+        // Auto-compaction using the provider's real token count. Skip when there's
+        // no fresh count (before the first call, or right after a compaction reset
+        // it to 0) so we don't immediately re-trigger.
+        const currentTokens = state.lastPromptTokens + state.lastOutputTokens;
+        if (state.lastPromptTokens > 0 &&
+            needsCompaction?.(currentTokens) &&
+            applyCompaction) {
+            const compacted = await applyCompaction("auto", state.messages);
+            applyCompactionResult(compacted);
+            await compacted.persist();
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juno-ai/bind",
-  "version": "3.0.0",
-  "description": "Agent harness: deterministic LLM provider routing, run mechanics, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary (turn kernel arrives in a later phase). MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "version": "5.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",
   "main": "./index.js",
@@ -15,10 +15,18 @@
       "types": "./routing/index.d.ts",
       "import": "./routing/index.js"
     },
+    "./completion": {
+      "types": "./completion/index.d.ts",
+      "import": "./completion/index.js"
+    },
     "./contracts": {
       "types": "./contracts/index.d.ts",
       "import": "./contracts/index.js"
     },
+    "./loop": {
+      "types": "./loop/index.d.ts",
+      "import": "./loop/index.js"
+    },
     "./run": {
       "types": "./run/index.d.ts",
       "import": "./run/index.js"