@nathapp/nax-agent 0.1.0

package/dist/native/session/turn-compaction-step.js

@@ -0,0 +1,128 @@
+/**
+ * The two compaction steps of the native turn loop.
+ *
+ * `runProactiveCompaction` runs before a round trip when the estimate crosses
+ * the threshold; `runOverflowCompaction` is the backstop when a round trip
+ * throws a context overflow anyway. They are deliberately TWO functions, not one
+ * with a `reactive` flag, because they differ in exactly three ways a boolean
+ * would hide:
+ *
+ *   1. the backstop halves the keep budget (`keepBudget(..., true)`);
+ *   2. a summarizer throw is swallowed by the proactive step (the request may
+ *      still fit) and propagates out of the backstop;
+ *   3. only the proactive step logs its progress (Finding 2, whole-branch
+ *      review 2026-09-04);
+ *   4. a `before_compaction` decline is HONOURED proactively — the branch runs
+ *      before any request, so sending uncompacted is a legitimate outcome — and
+ *      IGNORED + logged at overflow, where the request has already failed with
+ *      a context overflow and declining would leave no recovery (spec 6.2).
+ *
+ * They share only the summarize-and-apply core below. The failure semantics
+ * stay with the callers on purpose — see each function's catch.
+ */
+import { getSafeLogger } from "#src/infra/index";
+import { applyCompaction, estimateContextTokens, keepBudget, prepareCompaction, } from "./compaction.js";
+import { usageBeat } from "./turn-accumulator.js";
+/**
+ * The half both branches share: summarize the dropped span, then apply the
+ * summary to the transcript. A throw here is left to propagate — catching it is
+ * the proactive caller's decision, not this function's.
+ */
+async function summarizeAndApply(messages, plan, deps, source = {}) {
+    const summary = source.replacementSummary !== undefined
+        ? { text: source.replacementSummary, usage: { inputTokens: 0, outputTokens: 0 }, costUsd: 0 }
+        : await deps.summarize(plan.toSummarize, plan.previousSummary);
+    // Rebound, not spliced in place: `messages` is a local accumulator and
+    // rebinding it keeps the compacted array a fresh value.
+    const compacted = applyCompaction(messages, plan, summary.text);
+    return { messages: compacted, summary };
+}
+export async function runProactiveCompaction(args) {
+    const { messages, usage, sessionName, lastUsage, anchorIndex, deps, signal, loopEvents } = args;
+    const preCompactionTokens = estimateContextTokens(messages, lastUsage, anchorIndex);
+    const plan = prepareCompaction(messages, keepBudget(deps.contextWindow, deps.compaction));
+    if (plan === undefined) {
+        return { messages, compacted: false, summarizeFailed: false };
+    }
+    try {
+        const patch = await loopEvents.dispatch("before_compaction", {
+            reason: "proactive",
+            toSummarize: plan.toSummarize,
+            ...(plan.previousSummary !== undefined ? { previousSummary: plan.previousSummary } : {}),
+            estimatedTokens: preCompactionTokens,
+        });
+        // Nothing has been requested yet, so sending uncompacted is a legitimate
+        // outcome — the decline is HONOURED here (spec 6.2). `summarizeFailed`
+        // stays false: the overflow backstop must remain armed for the uncompacted
+        // try. A decline wins over a replacement summary — not compacting at all
+        // subsumes replacing what the summarizer would say.
+        if (patch.decline === true) {
+            return { messages, compacted: false, summarizeFailed: false };
+        }
+        const applied = await summarizeAndApply(messages, plan, deps, { replacementSummary: patch.summary });
+        // Finding 2 (whole-branch review, 2026-09-04): a previous-summary merge
+        // can produce a same-size (or larger) array — a paid model call that
+        // shrank nothing. Not fatal (the reactive backstop is the real safety
+        // net if this repeats into an overflow) but worth surfacing, since it
+        // would otherwise burn a model call every round trip with no signal.
+        const postCompactionTokens = estimateContextTokens(applied.messages, undefined, undefined);
+        if (postCompactionTokens >= preCompactionTokens) {
+            getSafeLogger()?.warn("native-adapter", "compaction made no size progress", {
+                sessionName,
+                preCompactionTokens,
+                postCompactionTokens,
+            });
+        }
+        getSafeLogger()?.info("native-adapter", "compaction completed", {
+            sessionName,
+            // Keep token counts under the plural `tokens` metric key so the
+            // logger's credential redactor does not mistake them for secrets.
+            tokens: { before: preCompactionTokens, after: postCompactionTokens },
+            messagesDropped: plan.toSummarize.length,
+            summaryLength: applied.summary.text.length,
+        });
+        usage.add(applied.summary.usage, applied.summary.costUsd, applied.summary.rates);
+        // Resets the watchdog's lastActivityAt between the summary and the
+        // round trip, so the two silent spans do not add up against one budget.
+        deps.onActivity?.(usageBeat(applied.summary.usage, applied.summary.costUsd));
+        return { messages: applied.messages, compacted: true, summarizeFailed: false };
+    }
+    catch (err) {
+        if (deps.deadline?.expired() === true || signal?.aborted === true)
+            throw err;
+        // Not fatal: the request may still fit, and if it does not it fails
+        // through the path #1837 and #1839 made correct. Killing a story
+        // because a summarizer hiccuped would be worse than the problem.
+        getSafeLogger()?.warn("native-adapter", "compaction summary failed; sending uncompacted", {
+            sessionName,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return { messages, compacted: false, summarizeFailed: true };
+    }
+}
+export async function runOverflowCompaction(args) {
+    const { messages, usage, sessionName, lastUsage, anchorIndex, deps, error, loopEvents } = args;
+    // Same code path, half the keep budget. Not a second algorithm.
+    const plan = prepareCompaction(messages, keepBudget(deps.contextWindow, deps.compaction, true));
+    if (plan === undefined)
+        throw error;
+    const patch = await loopEvents.dispatch("before_compaction", {
+        reason: "overflow",
+        toSummarize: plan.toSummarize,
+        ...(plan.previousSummary !== undefined ? { previousSummary: plan.previousSummary } : {}),
+        estimatedTokens: estimateContextTokens(messages, lastUsage, anchorIndex),
+    });
+    // The request has ALREADY failed with a context overflow: there is no
+    // uncompacted path left, so a decline has nothing to decline into and
+    // honouring it would kill the story. The signal stops, the compaction does
+    // not (spec 6.2), and the ignore is on the record.
+    if (patch.decline === true) {
+        getSafeLogger()?.warn("native-loop-events", "before_compaction decline ignored at overflow", {
+            sessionName,
+        });
+    }
+    const applied = await summarizeAndApply(messages, plan, deps, { replacementSummary: patch.summary });
+    usage.add(applied.summary.usage, applied.summary.costUsd, applied.summary.rates);
+    deps.onActivity?.(usageBeat(applied.summary.usage, applied.summary.costUsd));
+    return { messages: applied.messages, compacted: true, summarizeFailed: false };
+}

package/dist/native/session/turn-complete-step.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The complete-with-recovery step of the native turn loop.
+ *
+ * `deps.complete` plus its two recoveries — the bounded transport-fault retry
+ * (nax#1870) and the context-overflow compaction backstop — live here as one
+ * site: one round trip is issued, and a throw gets exactly one of the two
+ * recoveries. They were two branches of the loop's single try/catch; folding
+ * them into a step is what will let one seam observe every round trip. P3
+ * attaches `transform_context` and `before_request` here: both fire per request
+ * attempt from the private `request()` wrapper below (spec 6.5, 6.6) —
+ * before_request shapes the per-call options, transform_context shapes the WIRE
+ * COPY only, and the array the caller holds (which saveTranscript persists) is
+ * returned untouched. An honoured rewrite is reported as `honoured`, with the
+ * boundary fact that produced it as `boundary`, so the caller can clear the
+ * cache anchor exactly when spec 3.6 says to — a prefix-stable honour leaves
+ * the anchor valid (spec 6.6).
+ *
+ * The private `isContextOverflow` guard is this module's alone: it decides
+ * which recovery a thrown round trip gets.
+ */
+import type { TranscriptMessage as NativeTranscriptMessage } from "./compaction.ts";
+import type { LoopEventRegistry } from "./loop-events/index.ts";
+import type { TurnAccumulator } from "./turn-accumulator.ts";
+import type { NativeTurnResponse, TurnDeps } from "./turn-types.ts";
+export interface CompleteStepResult {
+    readonly res: NativeTurnResponse;
+    /** The transcript after recovery; rebound only by the overflow branch. */
+    readonly messages: readonly NativeTranscriptMessage[];
+    /** True when the overflow branch ran: it always rebinds messages (and the caller clears lastUsage/anchorIndex). */
+    readonly compacted: boolean;
+    /**
+     * True when the provider was sent an honoured `transform_context` rewrite
+     * (spec 6.6) — the last attempt to reach the wire is the one that counts.
+     * The caller clears lastUsage/anchorIndex on it ONLY together with
+     * `boundary`: a prefix-stable honour leaves the anchor valid (spec 6.6 —
+     * wire and persisted prefix are reference-identical, nothing to
+     * invalidate), while a boundary-exempt honour changed the prefix the
+     * provider saw even though the saved array did not (spec 3.6).
+     */
+    readonly honoured: boolean;
+    /**
+     * True when the honoured rewrite (if any) rode the boundary exemption —
+     * the post-compaction retry is the only boundary this step can produce
+     * (`compacted`; spec 3.4: a handler may never assert one). Paired with
+     * `honoured` rather than folded into it: the step-level contract keeps both
+     * facts.
+     */
+    readonly boundary: boolean;
+}
+export interface CompleteStepArgs {
+    readonly messages: readonly NativeTranscriptMessage[];
+    readonly tools: Parameters<TurnDeps["complete"]>[1];
+    readonly usage: TurnAccumulator;
+    /**
+     * Set by the proactive step for this round trip: the summarizer already threw,
+     * so the overflow retry must not try again.
+     */
+    readonly summarizeFailed: boolean;
+    readonly sessionName: string;
+    readonly lastUsage: {
+        readonly promptTokens: number;
+    } | undefined;
+    readonly anchorIndex: number | undefined;
+    /**
+     * The registry actually in use — the loop's local (`deps.loopEvents ??
+     * createLoopEventRegistry()`), not `deps.loopEvents` itself, which is
+     * usually absent and would dispatch to nothing.
+     */
+    readonly loopEvents: LoopEventRegistry;
+    /** The round trip this request belongs to, as counted by the loop. */
+    readonly roundTrip: number;
+    /** The session's resolved model; undefined when driven without a modelDef. */
+    readonly model?: string;
+    readonly deps: TurnDeps;
+    readonly signal?: AbortSignal;
+}
+export declare function completeWithRecovery(args: CompleteStepArgs): Promise<CompleteStepResult>;

package/dist/native/session/turn-complete-step.js

@@ -0,0 +1,159 @@
+/**
+ * The complete-with-recovery step of the native turn loop.
+ *
+ * `deps.complete` plus its two recoveries — the bounded transport-fault retry
+ * (nax#1870) and the context-overflow compaction backstop — live here as one
+ * site: one round trip is issued, and a throw gets exactly one of the two
+ * recoveries. They were two branches of the loop's single try/catch; folding
+ * them into a step is what will let one seam observe every round trip. P3
+ * attaches `transform_context` and `before_request` here: both fire per request
+ * attempt from the private `request()` wrapper below (spec 6.5, 6.6) —
+ * before_request shapes the per-call options, transform_context shapes the WIRE
+ * COPY only, and the array the caller holds (which saveTranscript persists) is
+ * returned untouched. An honoured rewrite is reported as `honoured`, with the
+ * boundary fact that produced it as `boundary`, so the caller can clear the
+ * cache anchor exactly when spec 3.6 says to — a prefix-stable honour leaves
+ * the anchor valid (spec 6.6).
+ *
+ * The private `isContextOverflow` guard is this module's alone: it decides
+ * which recovery a thrown round trip gets.
+ */
+import { getSafeLogger } from "#src/infra/index";
+import { applyHistoryPatch } from "./loop-events/cache-boundary.js";
+import { runOverflowCompaction } from "./turn-compaction-step.js";
+import { realSleep, retryTransportFault } from "./turn-retry.js";
+/**
+ * Structural, matching adapter-deps.ts's guard: nax-ai's error class is not
+ * importable here and the kind is what matters.
+ */
+function isContextOverflow(err) {
+    if (typeof err !== "object" || err === null || !("protocolError" in err))
+        return false;
+    const { protocolError } = err;
+    return protocolError?.kind === "context-overflow";
+}
+export async function completeWithRecovery(args) {
+    const { tools, usage, summarizeFailed, sessionName, lastUsage, anchorIndex, loopEvents, roundTrip, model, deps, signal, } = args;
+    let messages = args.messages;
+    let compacted = false;
+    let honoured = false;
+    let res;
+    // Model, thinking level and timeout are bound in the adapter's closure above
+    // the loop (spec 6.3), so the bag this dispatches starts empty; a handler's
+    // patch is the only thing that ever fills it.
+    const baseOptions = {};
+    // One wrapper, three call sites (spec 6.5). The wrapper owns `attempt`, so
+    // the retry machinery reports 2..n without knowing an event exists.
+    let attempt = 0;
+    const request = async (msgs) => {
+        attempt += 1;
+        const patch = await loopEvents.dispatch("before_request", {
+            ...(model !== undefined ? { model } : {}),
+            roundTrip,
+            attempt,
+            options: baseOptions,
+        });
+        const options = patch.options === undefined ? baseOptions : { ...baseOptions, ...patch.options };
+        // transform_context fires here too, per attempt (spec 6.6). The patch
+        // shapes ONLY the wire copy handed to deps.complete below: `msgs` — the
+        // caller's array, the one saveTranscript persists — is returned untouched,
+        // so the transcript stays the true record. `boundary` is this step's
+        // overflow fact (`compacted`): true only on the post-compaction retry,
+        // where a prefix rewrite is free. A model change never reaches this step:
+        // the transcript store refuses another model's history (spec 8.3).
+        const transformed = await loopEvents.dispatch("transform_context", {
+            messages: msgs,
+            tools,
+            anchorIndex,
+            boundary: compacted,
+            ...(model !== undefined ? { model } : {}),
+        });
+        const wire = applyHistoryPatch({
+            before: msgs,
+            patched: transformed.messages,
+            anchorIndex,
+            boundary: compacted,
+            event: "transform_context",
+        });
+        // Last write wins: a failed attempt is discarded wholesale, so the
+        // successful attempt is the last one to reach this line — `honoured`
+        // describes the wire the provider actually answered (spec 3.6).
+        honoured = wire.honoured;
+        return deps.complete(wire.messages, tools, options);
+    };
+    try {
+        res = await request(messages);
+    }
+    catch (err) {
+        // Written as one guarded `if` (not a separate `canRetry` boolean) so
+        // TypeScript's narrowing carries deps.summarize/contextWindow/compaction
+        // as defined below — a boolean flag loses that narrowing.
+        if (!isContextOverflow(err) ||
+            summarizeFailed ||
+            deps.summarize === undefined ||
+            deps.contextWindow === undefined ||
+            deps.compaction === undefined ||
+            !deps.compaction.enabled) {
+            // nax#1870: not an overflow this branch can handle. One more
+            // guarded branch beside the overflow backstop above, not a second
+            // loop or a second try/catch here — the retry's own looping and
+            // backoff live in retryTransportFault (./turn-retry), called once.
+            if (deps.transportRetry === undefined)
+                throw err;
+            res = await retryTransportFault(err, {
+                attempt: () => request(messages),
+                config: deps.transportRetry,
+                deadline: deps.deadline,
+                signal,
+                sleep: deps.sleep ?? realSleep,
+                onRetry: (retryNumber, delayMs, fault) => {
+                    getSafeLogger()?.warn("native-adapter", `retrying after a ${fault.protocolError.kind} fault`, {
+                        sessionName,
+                        retryNumber,
+                        delayMs,
+                        kind: fault.protocolError.kind,
+                        message: fault.protocolError.message,
+                        ...(fault.protocolError.status !== undefined ? { status: fault.protocolError.status } : {}),
+                        ...(fault.protocolError.retryAfter !== undefined ? { retryAfter: fault.protocolError.retryAfter } : {}),
+                    });
+                    // Resets the watchdog's lastActivityAt so a call being retried
+                    // is not mistaken for an idle one — same mechanism the
+                    // compaction summary above uses. All-zero is honest, not
+                    // fabricated: a pre-first-event transport throw bills nothing
+                    // (see nax-ai's retry.ts), so this beat truly carries zero
+                    // tokens, not a guessed non-zero number.
+                    deps.onActivity?.({ kind: "usage", inputTokens: 0, outputTokens: 0, costUsd: 0 });
+                },
+            });
+            // Falls through to the shared round-trip bookkeeping and tool
+            // execution below, exactly like the overflow-retry branch's own
+            // `res = await request(messages)` two lines down — one success
+            // path, reached from either recovery, not a second copy of it.
+        }
+        else {
+            const step = await runOverflowCompaction({
+                messages,
+                usage,
+                sessionName,
+                lastUsage,
+                anchorIndex,
+                loopEvents,
+                deps: {
+                    summarize: deps.summarize,
+                    contextWindow: deps.contextWindow,
+                    compaction: deps.compaction,
+                    onActivity: deps.onActivity,
+                    deadline: deps.deadline,
+                },
+                error: err,
+                ...(signal !== undefined ? { signal } : {}),
+            });
+            messages = [...step.messages];
+            compacted = true;
+            // Retried once. A second overflow propagates: compacting further would be
+            // guessing, and the failure now carries a correct diagnosis.
+            res = await request(messages);
+        }
+    }
+    return { res, messages, compacted, honoured, boundary: compacted };
+}

package/dist/native/session/turn-end-event.d.ts

@@ -0,0 +1,3 @@
+import type { LoopEventRegistry } from "./loop-events/index.ts";
+import type { BeforeTurnEndPayload } from "./loop-events/types.ts";
+export declare function dispatchTurnEndOnError(loopEvents: LoopEventRegistry, payload: Omit<BeforeTurnEndPayload, "ended">, signal?: AbortSignal): Promise<void>;

package/dist/native/session/turn-end-event.js

@@ -0,0 +1,17 @@
+/**
+ * Review #20: `before_turn_end` also fires when a turn throws, so a handler
+ * sees every ending. The result is ignored on this path -- there is no turn
+ * left to continue. The dispatch is awaited without a timeout of its own: a
+ * plugin handler is timed by its wrapper (`wrapExternalHandler`, US-002),
+ * and a built-in handler is not timed at all.
+ */
+import { getSafeLogger } from "#src/infra/index";
+export async function dispatchTurnEndOnError(loopEvents, payload, signal) {
+    const patch = await loopEvents.dispatch("before_turn_end", {
+        ...payload,
+        ended: signal?.aborted === true ? "aborted" : "errored",
+    });
+    if (patch.followUp !== undefined) {
+        getSafeLogger()?.warn("native-loop-events", "before_turn_end followUp ignored on error path", {});
+    }
+}

package/dist/native/session/turn-events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Native round-trip activity -> AgentStreamEvent.
+ *
+ * The idle watchdog subscribes to the runtime stream bus and tracks calls from
+ * these events; nothing under src/agents/native/ emitted any, so
+ * `agent.idleWatchdog` was inert on every native session in both modes.
+ *
+ * Native has no token streaming — one `complete()` is a single call — so these
+ * are emitted at round-trip boundaries rather than continuously. That is
+ * sufficient: a HUNG call is already bounded by the per-call abort, and the
+ * watchdog's unique job is the productive-looking loop that keeps calling tools
+ * forever. That loop emits `tool` AND `usage` on every iteration, so the usage
+ * event carries `perRoundTrip` to mark it as a round-trip boundary rather than
+ * semantic progress — otherwise it reset `lastNonToolCallActivityAt` every
+ * iteration and `toolCallOnlyIdleTimeout` could never fire (nax#2013).
+ */
+import type { AgentStreamEvent } from "#src/session/agent-stream-events";
+export type NativeTurnActivity = {
+    kind: "message";
+    bytes: number;
+} | {
+    kind: "thinking";
+    bytes: number;
+} | {
+    kind: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    /** Absent when the round trip reported no cache data — never coerced to 0. */
+    cacheRead?: number;
+    /** Absent when the round trip reported no cache data — never coerced to 0. */
+    cacheWrite?: number;
+    /** 1-based ordinal of the round trip this beat covers. Absent on a
+     *  compaction-summary or retry beat, which are not round-trip boundaries. */
+    roundTrip?: number;
+} | {
+    kind: "tool";
+    toolName: string;
+} | {
+    /**
+     * US-004: the turn is waiting on a human approval prompt. Carried so the
+     * runtime stream bus can turn it into `agent.awaiting_human` for the idle
+     * watchdog, which must not read legitimate human waiting as idleness.
+     */
+    kind: "awaiting_human";
+};
+export interface NativeStreamEventBase {
+    readonly callId: string;
+    readonly runId: string;
+    readonly agentName: string;
+    readonly sessionName: string;
+    readonly storyId?: string;
+    /** Pipeline stage label; the contract does not know nax's stage union (S1 spec port 4). */
+    readonly stage?: string;
+    /**
+     * The transcript/ledger join key (`transcript.owner` = `ledger.scopeId`),
+     * forwarded from the native session's owner map. Absent when the session was
+     * opened without a `transcriptOwner` — absent reads as "unknown". Never the
+     * stream-local `callId`.
+     */
+    readonly scopeId?: string;
+}
+export declare function buildNativeStreamEvent(base: NativeStreamEventBase, activity: NativeTurnActivity, timestamp: number): AgentStreamEvent;

package/dist/native/session/turn-events.js

@@ -0,0 +1,48 @@
+/**
+ * Native round-trip activity -> AgentStreamEvent.
+ *
+ * The idle watchdog subscribes to the runtime stream bus and tracks calls from
+ * these events; nothing under src/agents/native/ emitted any, so
+ * `agent.idleWatchdog` was inert on every native session in both modes.
+ *
+ * Native has no token streaming — one `complete()` is a single call — so these
+ * are emitted at round-trip boundaries rather than continuously. That is
+ * sufficient: a HUNG call is already bounded by the per-call abort, and the
+ * watchdog's unique job is the productive-looking loop that keeps calling tools
+ * forever. That loop emits `tool` AND `usage` on every iteration, so the usage
+ * event carries `perRoundTrip` to mark it as a round-trip boundary rather than
+ * semantic progress — otherwise it reset `lastNonToolCallActivityAt` every
+ * iteration and `toolCallOnlyIdleTimeout` could never fire (nax#2013).
+ */
+export function buildNativeStreamEvent(base, activity, timestamp) {
+    const common = { ...base, timestamp };
+    switch (activity.kind) {
+        case "message":
+            return { ...common, kind: "agent.message_update", deltaBytes: activity.bytes };
+        case "thinking":
+            return { ...common, kind: "agent.thinking_update", deltaBytes: activity.bytes };
+        case "usage":
+            return {
+                ...common,
+                kind: "agent.usage_update",
+                inputTokens: activity.inputTokens,
+                outputTokens: activity.outputTokens,
+                costUsd: activity.costUsd,
+                ...(activity.cacheRead !== undefined ? { cacheRead: activity.cacheRead } : {}),
+                ...(activity.cacheWrite !== undefined ? { cacheWrite: activity.cacheWrite } : {}),
+                // Only a real round-trip boundary may claim `perRoundTrip` and an
+                // ordinal: the compaction-summary and transport-retry beats are usage
+                // events too, but they are not round trips (nax#2013, nax#2045). The
+                // cadence is still nax's own loop even on those beats.
+                ...(activity.roundTrip !== undefined ? { roundTrip: activity.roundTrip, perRoundTrip: true } : {}),
+                cadence: "round-trip",
+            };
+        case "tool":
+            return { ...common, kind: "agent.tool_call_update", toolName: activity.toolName };
+        case "awaiting_human":
+            // US-004: the turn is waiting on a human approval prompt. The watchdog
+            // treats this as semantic progress on both activity clocks and clears an
+            // open grace window, so a pending prompt never reads as idle.
+            return { ...common, kind: "agent.awaiting_human" };
+    }
+}

package/dist/native/session/turn-loop-round-trip.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The round-trip loop and turn-end phase of the native turn loop.
+ *
+ * Split out of `./turn-loop.ts` during the complexity drain
+ * (docs/plans/STATUS-complexity-drain.md A2): `runNativeTurn` scored 97 as one
+ * function covering setup, the round-trip loop (deliberately unbounded —
+ * bounded by the deadline, the idle watchdog, and the spin breaker, not a
+ * call count), and the `before_turn_end` continuation decision. Both loop
+ * bodies move here unchanged; only the plumbing that threads state across
+ * calls changed shape. A pure extraction: no loop rule changed.
+ *
+ * `runRoundTripLoop` mutates its `state` argument in place rather than
+ * returning a new one, and does so on every field the moment each value is
+ * known — not only at a clean exit. The original was one function where
+ * `messages` (and friends) were plain `let`s: a mid-loop throw (the
+ * `batch.cancelled` path below) still left the catch block reading the
+ * latest values, because it was the same variable. Returning a fresh object
+ * only at the end of the function would lose every update since the last
+ * return the moment a throw skips it — exactly the synthetic tool-result
+ * messages `runToolBatch` just appended before signalling cancellation. The
+ * caller passes one `TurnLoopState` and keeps reading through that same
+ * reference after an `await` that might throw.
+ *
+ * `spinStopped` / `spinWarned` were two `let`s in `runNativeTurn`, one of them
+ * (`spinWarned`) mutated by an `onSpinStop` closure registered ONCE in setup,
+ * before either extracted function is ever called, and read/written across
+ * every outer-loop iteration after that. Splitting the loop body out cannot
+ * split that closure's target too, so both flags now live in one mutable
+ * `SpinFlags` object created in setup and threaded by reference into every
+ * call here — the same shared-mutable-state semantics as the original two
+ * `let`s, just addressed through an object instead of two closed-over
+ * bindings.
+ */
+import type { ToolDefinition } from "@nathapp/nax-ai";
+import type { SpinBreaker } from "#src/infra/spin-breaker/index";
+import type { InteractionExchange, SendTurnOpts, SessionHandle } from "#src/session/session-types";
+import { type TranscriptMessage as NativeTranscriptMessage } from "./compaction.ts";
+import type { InvalidCallBudget } from "./handle-invalid-tool-call.ts";
+import type { LoopEventRegistry } from "./loop-events/index.ts";
+import type { createTurnAccumulator } from "./turn-accumulator.ts";
+import type { TurnDeps } from "./turn-types.ts";
+/**
+ * The per-turn bound on `before_turn_end`'s followUp channel (spec 6.4): the
+ * only event that can spend money on its own, so injections are capped per
+ * turn regardless of what handlers return. At the cap the channel stops and
+ * the turn ends.
+ */
+export declare const MAX_FOLLOW_UPS_PER_TURN = 3;
+/** Shared across every call in one turn — see the file header. */
+export interface SpinFlags {
+    /** Set ONLY when the breaker ended the turn, so the wiring layer can classify it as `fail-spin` rather than a generic incomplete turn. */
+    stopped: boolean;
+    /** nax#2120: the first stop verdict spends a terminal round trip rather than tearing the turn down, so a false positive does not cost the transcript. */
+    warned: boolean;
+}
+/** Values that change across outer-loop (followUp) iterations. */
+export interface TurnLoopState {
+    messages: NativeTranscriptMessage[];
+    lastUsage: {
+        promptTokens: number;
+    } | undefined;
+    anchorIndex: number | undefined;
+    roundTrips: number;
+    output: string;
+    completedNormally: boolean;
+    timedOut: boolean;
+    followUpsSoFar: number;
+}
+/** Turn-scoped values that never change across outer-loop iterations. */
+export interface TurnRoundParams {
+    handle: SessionHandle;
+    opts: SendTurnOpts;
+    deps: TurnDeps;
+    /** `transcriptIdentity.model` — carried into every `nativeSessionLastUsage.set` this turn writes. */
+    transcriptModel: string | undefined;
+    tools: ToolDefinition[];
+    codingToolNames: ReadonlySet<string>;
+    loopEvents: LoopEventRegistry;
+    invalidCallBudget: InvalidCallBudget;
+    spinBreaker: SpinBreaker | undefined;
+    spinFlags: SpinFlags;
+    maxInteractions: number;
+    /** Mutated in place — the caller owns the turn-lifetime array. */
+    interactions: InteractionExchange[];
+    /** Mutated in place — the caller owns the turn-lifetime array. */
+    codingToolsCalled: string[];
+    /** Mutated in place via `.add()` — the caller owns the turn-lifetime accumulator. */
+    usage: ReturnType<typeof createTurnAccumulator>;
+}
+/**
+ * Deliberately unbounded by COUNT of varied calls. A coding agent working a
+ * story is bounded by wall clock (deps.deadline), by the idle watchdog, and
+ * — since nax#2013 — by the spin breaker, which ends a turn that keeps
+ * REPEATING a call it already made. `agent.maxInteractionTurns` is NOT this
+ * budget — it bounds human Q&A exchanges, which are counted separately.
+ */
+export declare function runRoundTripLoop(state: TurnLoopState, params: TurnRoundParams): Promise<void>;
+export type TurnEndOutcome = {
+    action: "break";
+} | {
+    action: "continue";
+    state: TurnLoopState;
+};
+/**
+ * P3 `before_turn_end` (spec 6.4): fires at every turn ENDING, before the
+ * final saveTranscript. `stopped` is dispatcher-computed: the three endings
+ * that are stops, not completions — the spin breaker (nax#2120), the
+ * invalid-call budget (nax#2047), and the deadline — close the followUp
+ * channel entirely, because resurrecting a turn a breaker just killed would
+ * re-open the loops those breakers exist to close. The payload's `stopped`
+ * flag is all a handler sees: WHICH breaker fired is not leaked, and any
+ * followUp returned against a stop is ignored (with a warn — a handler
+ * trying to resurrect is worth a trace). The channel is also capped per turn
+ * at MAX_FOLLOW_UPS_PER_TURN.
+ */
+export declare function runTurnEndPhase(state: TurnLoopState, params: TurnRoundParams): Promise<TurnEndOutcome>;