@nathapp/nax-agent 0.1.0

package/dist/native/session/turn-loop-round-trip.js

@@ -0,0 +1,318 @@
+/**
+ * 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 { inputClassTokens } from "#src/cost/core/index";
+import { getSafeLogger } from "#src/infra/index";
+import { estimateContextTokens, shouldCompact, } from "./compaction.js";
+import { nativeSessionLastUsage } from "./session.js";
+import { usageBeat } from "./turn-accumulator.js";
+import { runProactiveCompaction } from "./turn-compaction-step.js";
+import { completeWithRecovery } from "./turn-complete-step.js";
+import { runToolBatch } from "./turn-tool-batch.js";
+/**
+ * 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 const MAX_FOLLOW_UPS_PER_TURN = 3;
+/**
+ * Compaction runs at most once per round trip. That bound is what stops a
+ * compact-still-over-compact loop when the pinned prompt alone is too large.
+ * The returned `summarizeFailed` is read by the overflow-retry backstop
+ * (`canRetry = ... && !summarizeFailed && ...`) inside `completeWithRecovery`,
+ * which suppresses a doomed retry after the summarizer has already failed
+ * this round trip.
+ */
+async function maybeCompact(state, params) {
+    const { handle, opts, deps, loopEvents } = params;
+    // Guard clauses, not one big `&&`: each keeps TS's narrowing of deps.summarize
+    // / contextWindow / compaction live for the `deps: {...}` literal below,
+    // which a hoisted boolean would have thrown away.
+    if (deps.summarize === undefined || deps.contextWindow === undefined || deps.compaction === undefined) {
+        return { summarizeFailed: false };
+    }
+    if (!shouldCompact(estimateContextTokens(state.messages, state.lastUsage, state.anchorIndex), deps.contextWindow, deps.compaction)) {
+        return { summarizeFailed: false };
+    }
+    const step = await runProactiveCompaction({
+        messages: state.messages,
+        usage: params.usage,
+        sessionName: handle.id,
+        lastUsage: state.lastUsage,
+        anchorIndex: state.anchorIndex,
+        // The loop's local, not deps.loopEvents — the same registry
+        // completeWithRecovery and runToolBatch receive below, so every
+        // dispatch seam observes the same handlers.
+        loopEvents,
+        // Copied, not the `deps` object itself: the guards above narrow the
+        // three properties to defined, and a fresh object is what carries that
+        // narrowing into the step's `CompactionStepDeps` parameter.
+        deps: {
+            summarize: deps.summarize,
+            contextWindow: deps.contextWindow,
+            compaction: deps.compaction,
+            onActivity: deps.onActivity,
+            deadline: deps.deadline,
+        },
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    });
+    state.messages = [...step.messages];
+    if (step.compacted) {
+        // The anchor described the pre-compaction array; it is meaningless now.
+        state.lastUsage = undefined;
+        state.anchorIndex = undefined;
+    }
+    return { summarizeFailed: step.summarizeFailed };
+}
+/**
+ * One model call and its bookkeeping: `completeWithRecovery`, the usage/anchor
+ * updates, the activity beats, `after_response`, and pushing the settled
+ * assistant message. Returns the tool calls the model asked for, if any —
+ * `undefined` means the turn completed normally (mutates
+ * `state.completedNormally`).
+ */
+async function runModelRoundTrip(state, params, summarizeFailed) {
+    const { handle, opts, deps, tools, loopEvents } = params;
+    const step = await completeWithRecovery({
+        messages: state.messages,
+        tools,
+        usage: params.usage,
+        summarizeFailed,
+        sessionName: handle.id,
+        lastUsage: state.lastUsage,
+        anchorIndex: state.anchorIndex,
+        // The loop's local, not deps.loopEvents — the same registry runToolBatch
+        // below receives, so both dispatch seams observe the same handlers.
+        loopEvents,
+        // 1-based, matching the usage beat below: the request being issued is
+        // round trip roundTrips + 1 — before_request(0-based N) and a later
+        // after_response(1-based N) would otherwise disagree on the same trip.
+        roundTrip: state.roundTrips + 1,
+        ...(handle.modelDef?.model !== undefined ? { model: handle.modelDef.model } : {}),
+        deps,
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    });
+    const res = step.res;
+    state.messages = [...step.messages];
+    // The anchor described the pre-compaction array (compacted), or a
+    // prefix the provider was never sent (a boundary-exempt transform_context
+    // rewrite — spec 3.6: the wire changed even though the saved array did
+    // not); it is meaningless now. Compaction invalidates it unconditionally;
+    // a transform_context honour clears only when it rode the boundary
+    // exemption — a prefix-stable honour leaves the anchor valid (spec 6.6:
+    // wire and persisted prefix are reference-identical, nothing to invalidate).
+    if (step.compacted || (step.honoured && step.boundary)) {
+        state.lastUsage = undefined;
+        state.anchorIndex = undefined;
+    }
+    state.roundTrips += 1;
+    params.usage.add(res.usage, res.costUsd, res.rates);
+    state.output = res.text;
+    // nax#1852: the anchor is the whole prompt the provider charged for, not
+    // just its uncached portion. Under prompt caching (which the round trip
+    // above always requests) the cached prefix arrives in the cache fields,
+    // and counting inputTokens alone reads a 71k-token context as ~16.
+    const promptTokens = inputClassTokens(res.usage);
+    state.lastUsage = { promptTokens };
+    state.anchorIndex = state.messages.length - 1;
+    nativeSessionLastUsage.set(handle.id, {
+        promptTokens,
+        anchorIndex: state.anchorIndex,
+        ...(params.transcriptModel !== undefined ? { model: params.transcriptModel } : {}),
+    });
+    // 1-based; `roundTrips` is incremented above, before this beat fires.
+    deps.onActivity?.(usageBeat(res.usage, res.costUsd, state.roundTrips));
+    if (res.text.length > 0)
+        deps.onActivity?.({ kind: "message", bytes: res.text.length });
+    if (res.thinking !== undefined && res.thinking.length > 0) {
+        deps.onActivity?.({
+            kind: "thinking",
+            bytes: res.thinking.reduce((n, t) => n + t.text.length, 0),
+        });
+    }
+    // P3 `after_response` (spec 6.1): fires once per round trip on the
+    // settled assistant message, BEFORE it enters the array — a patch is
+    // safe by construction because it shapes the message, never the array,
+    // so the anchorIndex recorded above (`messages.length - 1`, which runs
+    // before this push) keeps describing the prefix the provider charged
+    // for. `usage`/`costUsd` are surfaced readonly: the registry reads only
+    // the patchable fields off a return, so billing truth cannot surface
+    // even from a handler that bypasses the type.
+    const afterResponse = await loopEvents.dispatch("after_response", {
+        text: res.text,
+        ...(res.toolCalls !== undefined ? { toolCalls: res.toolCalls } : {}),
+        ...(res.thinking !== undefined ? { thinking: res.thinking } : {}),
+        usage: res.usage,
+        costUsd: res.costUsd,
+        roundTrip: state.roundTrips,
+    });
+    // The pushed message carries the patched shape, and the loop acts on
+    // what it records: answering the ORIGINAL calls while recording patched
+    // ones would desync the transcript from what actually executed.
+    const assistantText = afterResponse.text ?? res.text;
+    const assistantToolCalls = afterResponse.toolCalls ?? res.toolCalls;
+    const assistantThinking = afterResponse.thinking ?? res.thinking;
+    // Thinking blocks are appended, not merely representable: Anthropic needs
+    // the exact block back to continue a thinking conversation (ADR-028 s8).
+    state.messages.push({
+        role: "assistant",
+        content: assistantText,
+        ...(assistantToolCalls !== undefined ? { toolCalls: assistantToolCalls } : {}),
+        ...(assistantThinking !== undefined ? { thinking: assistantThinking } : {}),
+    });
+    if (assistantToolCalls === undefined || assistantToolCalls.length === 0) {
+        state.completedNormally = true;
+        return undefined;
+    }
+    return assistantToolCalls;
+}
+/**
+ * Answers the round trip's tool calls and decides whether the round-trip loop
+ * should keep going. `state` is already up to date (mutated above, not
+ * returned — see the file header) the moment `batch.cancelled` throws, so the
+ * caller's catch block still sees this batch's messages.
+ */
+async function dispatchToolBatch(state, params, toolCalls) {
+    const { opts, deps, tools, codingToolNames, loopEvents, invalidCallBudget, spinBreaker, spinFlags, maxInteractions } = params;
+    const batch = await runToolBatch({
+        messages: state.messages,
+        toolCalls,
+        tools,
+        codingToolNames,
+        roundTrips: state.roundTrips,
+        opts,
+        deps,
+        loopEvents,
+        invalidCallBudget,
+        spinBreaker,
+        maxInteractions,
+        spinWarned: spinFlags.warned,
+        interactionsSoFar: params.interactions.length,
+    });
+    state.messages = [...batch.messages];
+    params.interactions.push(...batch.interactions);
+    params.codingToolsCalled.push(...batch.codingToolsCalled);
+    if (batch.spinStopped)
+        spinFlags.stopped = true;
+    if (batch.spinStopped || batch.budgetExceeded)
+        return { shouldBreak: true };
+    // US-002: a cancelled turn signal during the batch answers every
+    // outstanding call synthetically and stops the loop. The throw routes
+    // through the existing catch block — its best-effort saveTranscript
+    // persists the synthetic results before the throw propagates, keeping one
+    // result per assistant id in the saved transcript (AC2 / AC3). AC4 carries
+    // the abort reason verbatim; AC6 — a no-reason abort — produces a
+    // DOMException named AbortError, the contract `build-hop-callback` and the
+    // idle-watchdog key on.
+    if (batch.cancelled) {
+        throw deps.signal?.reason ?? new DOMException("signal is aborted without reason", "AbortError");
+    }
+    return { shouldBreak: false };
+}
+/**
+ * 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 async function runRoundTripLoop(state, params) {
+    while (true) {
+        // Checked before starting a round-trip rather than after finishing one:
+        // starting a call we know cannot finish inside the budget spends money for
+        // an answer we will discard.
+        if (params.deps.deadline?.expired() === true) {
+            state.timedOut = true;
+            break;
+        }
+        const { summarizeFailed } = await maybeCompact(state, params);
+        const toolCalls = await runModelRoundTrip(state, params, summarizeFailed);
+        if (toolCalls === undefined)
+            break; // completedNormally already set
+        const { shouldBreak } = await dispatchToolBatch(state, params, toolCalls);
+        if (shouldBreak)
+            break;
+    }
+}
+/**
+ * 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 async function runTurnEndPhase(state, params) {
+    const stopped = params.spinFlags.stopped || params.invalidCallBudget.exceeded || state.timedOut;
+    const turnEnd = await params.loopEvents.dispatch("before_turn_end", {
+        messages: state.messages,
+        roundTrips: state.roundTrips,
+        ended: "completed",
+        stopped,
+        followUpsSoFar: state.followUpsSoFar,
+    });
+    if (stopped || state.followUpsSoFar >= MAX_FOLLOW_UPS_PER_TURN) {
+        if (turnEnd.followUp !== undefined) {
+            getSafeLogger()?.warn("native-loop-events", "before_turn_end followUp ignored", {
+                sessionName: params.handle.id,
+                ...(stopped ? { reason: "stopped" } : { reason: "cap", cap: MAX_FOLLOW_UPS_PER_TURN }),
+            });
+        }
+        return { action: "break" };
+    }
+    if (turnEnd.followUp === undefined)
+        return { action: "break" };
+    // Honoured: the user message enters the array and the outer loop
+    // re-enters the round-trip loop — each injection counts as its own
+    // round trip through the normal loop, and the turn's result is NOT
+    // built here.
+    const messages = [...state.messages, { role: "user", content: turnEnd.followUp }];
+    // The continuation must earn its own clean exit, and a reprieved stop's
+    // terminal-round-trip snapshot does not carry into it — the breaker's
+    // own cumulative, session-lifetime counters (nax#2047) still enforce.
+    params.spinFlags.warned = false;
+    return {
+        action: "continue",
+        state: {
+            ...state,
+            messages,
+            followUpsSoFar: state.followUpsSoFar + 1,
+            completedNormally: false,
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * The native turn loop.
+ *
+ * nax owns the conversation, so a turn is: append the prompt, call the model,
+ * and while it asks for tools, execute them and call again. Tools are executed
+ * through the InteractionHandler the ACP adapter already uses — this file never
+ * touches the context engine.
+ *
+ * The public types this loop consumes (`TurnDeps`, `NativeTurnResponse`,
+ * `NativeSummaryResponse`) and the failure-usage ledger
+ * (`readNativeTurnFailureUsage` / `recordNativeTurnFailureUsage`) live in
+ * `./turn-types.ts`. Splitting them out keeps this file focused on the
+ * algorithm and below the 600-line hard limit (project-conventions.md).
+ *
+ * The round-trip loop and the `before_turn_end` continuation decision live in
+ * `./turn-loop-round-trip.ts` (complexity drain A2,
+ * docs/plans/STATUS-complexity-drain.md) — this file does setup (transcript
+ * load, event registry, `before_turn`), sequences the outer while(true) over
+ * those two phases, and handles the error/completion tail.
+ */
+import type { SendTurnOpts, SessionHandle, TurnResult } from "#src/session/session-types";
+import { type TurnDeps } from "./turn-types.ts";
+export declare function runNativeTurn(handle: SessionHandle, prompt: string, opts: SendTurnOpts, deps: TurnDeps): Promise<TurnResult>;

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

@@ -0,0 +1,250 @@
+/**
+ * The native turn loop.
+ *
+ * nax owns the conversation, so a turn is: append the prompt, call the model,
+ * and while it asks for tools, execute them and call again. Tools are executed
+ * through the InteractionHandler the ACP adapter already uses — this file never
+ * touches the context engine.
+ *
+ * The public types this loop consumes (`TurnDeps`, `NativeTurnResponse`,
+ * `NativeSummaryResponse`) and the failure-usage ledger
+ * (`readNativeTurnFailureUsage` / `recordNativeTurnFailureUsage`) live in
+ * `./turn-types.ts`. Splitting them out keeps this file focused on the
+ * algorithm and below the 600-line hard limit (project-conventions.md).
+ *
+ * The round-trip loop and the `before_turn_end` continuation decision live in
+ * `./turn-loop-round-trip.ts` (complexity drain A2,
+ * docs/plans/STATUS-complexity-drain.md) — this file does setup (transcript
+ * load, event registry, `before_turn`), sequences the outer while(true) over
+ * those two phases, and handles the error/completion tail.
+ */
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { askHumanToolDefinition } from "./ask-human.js";
+import { createInvalidCallBudget } from "./handle-invalid-tool-call.js";
+import { applyHistoryPatch } from "./loop-events/cache-boundary.js";
+import { createLoopEventRegistry } from "./loop-events/index.js";
+import { registerBuiltinLoopHandlers } from "./loop-handlers.js";
+import { nativeSessionTranscriptOwners, nativeTranscriptDirs, sessionAnchorFor } from "./session.js";
+import { codingToolsToDefinitions, toToolDefinitions } from "./tool-mapping.js";
+import { loadTranscript, saveTranscript, transcriptModelIdentity, } from "./transcript-store.js";
+import { createTurnAccumulator } from "./turn-accumulator.js";
+import { dispatchTurnEndOnError } from "./turn-end-event.js";
+import { runRoundTripLoop, runTurnEndPhase } from "./turn-loop-round-trip.js";
+import { buildTurnResult, logTurnTailWarnings } from "./turn-result.js";
+import { recordNativeTurnFailureUsage } from "./turn-types.js";
+/**
+ * The messages `before_turn` appends as the turn's seed: the handler's patch
+ * when it is a non-empty user-role array (spec 6.1's stop rule), otherwise the
+ * prompt the caller handed the turn. A bad patch is rejected the way a bad
+ * history patch is — warn, original kept (spec 3.7) — because a seed that is
+ * empty or speaks with another role hands the model a conversation it cannot
+ * answer as itself.
+ */
+function beforeTurnSeed(patch, prompt) {
+    if (patch === undefined)
+        return [{ role: "user", content: prompt }];
+    if (patch.length > 0 && patch.every((m) => m.role === "user"))
+        return [...patch];
+    getSafeLogger()?.warn("native-loop-events", "before_turn seed patch rejected: seed must be a non-empty user-role array", { seedLength: patch.length });
+    return [{ role: "user", content: prompt }];
+}
+export async function runNativeTurn(handle, prompt, opts, deps) {
+    const dir = nativeTranscriptDirs.get(handle.id);
+    if (dir === undefined) {
+        throw new NaxError(`no transcript directory for session "${handle.id}"`, "NATIVE_TRANSCRIPT_DIR_MISSING", {
+            stage: "native-session",
+        });
+    }
+    // nax#1877: an owner mismatch reads as a new conversation, so an abandoned
+    // invocation's history cannot ride along on the first request of this one.
+    // nax#2150 (P3 spec 8.3): so does a recorded different model — the store
+    // owns that guarantee, whatever the session layer above decided.
+    const transcriptIdentity = {
+        owner: nativeSessionTranscriptOwners.get(handle.id),
+        model: transcriptModelIdentity(handle.modelDef?.model),
+    };
+    let messages = [...(await loadTranscript(dir, handle.id, transcriptIdentity))];
+    // nax#2151: the invalid-call repair and the spin breaker are `before_tool`
+    // registrations rather than inline branches. Absent a caller-supplied
+    // registry the loop owns one, so both built-ins run exactly as they did
+    // before the seam. The block sits above `before_turn` now: the dispatch
+    // needs the registry, and the built-ins must be installed before ANY event
+    // fires, exactly as they were installed before any round trip ran.
+    const spinFlags = { stopped: false, warned: false };
+    const invalidCallBudget = createInvalidCallBudget();
+    const loopEvents = deps.loopEvents ?? createLoopEventRegistry();
+    registerBuiltinLoopHandlers(loopEvents, {
+        sessionName: handle.id,
+        budget: invalidCallBudget,
+        ...(deps.spinBreaker !== undefined ? { spinBreaker: deps.spinBreaker } : {}),
+        ...(deps.loopHandlers !== undefined ? { loopHandlers: deps.loopHandlers } : {}),
+        ...(deps.loopHandlerContext !== undefined ? { loopHandlerContext: deps.loopHandlerContext } : {}),
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+        onSpinStop: () => {
+            spinFlags.warned = true;
+        },
+    });
+    const anchor = sessionAnchorFor(handle.id, transcriptIdentity.model);
+    const lastUsage = anchor?.promptTokens !== undefined ? { promptTokens: anchor.promptTokens } : undefined;
+    const anchorIndex = anchor?.anchorIndex;
+    // P3 `before_turn` (spec 6.1): fires ONCE, after the transcript loads and
+    // before the seed push. `boundary` is dispatcher-computed (spec 3.4) and
+    // always false: the model-change boundary never arises, because the
+    // transcript store refuses another model's history (spec 8.3), so the
+    // history channel is honoured only at an undefined anchor (spec 3.5) — an
+    // off-boundary patch is rejected + warned by applyHistoryPatch and the turn
+    // proceeds on the loaded history.
+    const turnStart = await loopEvents.dispatch("before_turn", {
+        prompt,
+        history: messages,
+        sessionName: handle.id,
+        boundary: false,
+    });
+    // An honoured history patch (reachable only at an undefined anchor today)
+    // rewrites the IN-MEMORY array, and the saveTranscript at the turn's end
+    // persists it — before_turn is the conversation-rewriting event, unlike
+    // transform_context's wire-copy-only ruling (spec 6.6).
+    messages = [
+        ...applyHistoryPatch({
+            before: messages,
+            patched: turnStart.history,
+            anchorIndex,
+            boundary: false,
+            event: "before_turn",
+        }).messages,
+    ];
+    messages.push(...beforeTurnSeed(turnStart.seed, prompt));
+    const codingTools = opts.codingTools ?? [];
+    const codingToolNames = new Set(codingTools.map((t) => t.name));
+    // Native spends the budget ONLY on ask_human exchanges. Unlike ACP it is
+    // not this loop's bound — the loop is `while (true)`, bounded by the
+    // whole-turn deadline and the idle watchdog (issue #1820).
+    //
+    // Advertised only while the Q&A budget can still be spent; a tool the model
+    // cannot successfully call is worse than no tool.
+    const maxInteractions = opts.maxInteractions ?? 0;
+    const tools = [
+        ...toToolDefinitions(opts.contextPullTools ?? []),
+        ...codingToolsToDefinitions(codingTools),
+        ...(maxInteractions > 0 ? [askHumanToolDefinition] : []),
+    ];
+    const usage = createTurnAccumulator();
+    // Reported on the result so the review guards can corroborate a reviewer's
+    // self-declared inspection trail against calls it actually made.
+    const codingToolsCalled = [];
+    const interactions = [];
+    const params = {
+        handle,
+        opts,
+        deps,
+        transcriptModel: transcriptIdentity.model,
+        tools,
+        codingToolNames,
+        loopEvents,
+        invalidCallBudget,
+        spinBreaker: deps.spinBreaker,
+        spinFlags,
+        maxInteractions,
+        interactions,
+        codingToolsCalled,
+        usage,
+    };
+    let state = {
+        messages,
+        lastUsage,
+        anchorIndex,
+        roundTrips: 0,
+        output: "",
+        // Set ONLY on the clean exit — the model returned no further tool calls.
+        // Every other way out of the loop (the deadline, or an abort) leaves work
+        // the model asked for unexecuted.
+        completedNormally: false,
+        timedOut: false,
+        // `before_turn_end`'s followUp injections so far this turn (spec 6.4) —
+        // reset every turn, capped at MAX_FOLLOW_UPS_PER_TURN.
+        followUpsSoFar: 0,
+    };
+    // nax#1838: the save below the loop is the clean exit's alone. A turn that
+    // throws must persist too — the retry reopens the same deterministic session
+    // name, so an unsaved conversation is one the model silently resumes without.
+    try {
+        // The OUTER loop is `before_turn_end`'s followUp continuation (spec 6.4):
+        // an honoured followUp re-enters the round-trip loop via runRoundTripLoop
+        // instead of building the turn's result — the result is built when the
+        // turn ENDS.
+        while (true) {
+            // Mutates `state` in place, including up to the point of a throw — see
+            // runRoundTripLoop's own header for why this is not `state = await ...`.
+            await runRoundTripLoop(state, params);
+            const turnEnd = await runTurnEndPhase(state, params);
+            if (turnEnd.action === "break")
+                break;
+            state = turnEnd.state;
+        }
+    }
+    catch (err) {
+        // Review #20: the event fires on EVERY ending, so a throwing turn
+        // dispatches it before the transcript save — a handler sees the failure
+        // ending with `ended: "aborted"` (signal fired) or `"errored"`, and its
+        // result is ignored: there is no turn left to continue. A rejecting
+        // dispatch must not replace the original error or skip the save below —
+        // it is logged and skipped, the same skip-not-fail contract the registry
+        // applies to a single throwing handler.
+        await dispatchTurnEndOnError(loopEvents, {
+            messages: state.messages,
+            roundTrips: state.roundTrips,
+            stopped: spinFlags.stopped || invalidCallBudget.exceeded || state.timedOut,
+            followUpsSoFar: state.followUpsSoFar,
+        }, deps.signal).catch((dispatchErr) => {
+            getSafeLogger()?.warn("native-loop-events", "before_turn_end dispatch failed on the error path; skipping it", {
+                sessionName: handle.id,
+                error: dispatchErr instanceof Error ? dispatchErr.message : String(dispatchErr),
+            });
+        });
+        // Best-effort, and deliberately unlike the clean-exit save: there a write
+        // failure fails the turn, because continuing on unstored history is silent
+        // degradation. Here a failure is already in flight, and masking it with a
+        // write error would lose the cause.
+        await saveTranscript(dir, handle.id, state.messages, transcriptIdentity).catch((saveErr) => {
+            getSafeLogger()?.warn("native-adapter", "could not persist the transcript of a failed turn", {
+                sessionName: handle.id,
+                error: saveErr instanceof Error ? saveErr.message : String(saveErr),
+            });
+        });
+        // nax#1840: attach what was already spent, keyed on the error's own
+        // identity so the error itself is rethrown byte-for-byte unmodified.
+        if (typeof err === "object" && err !== null) {
+            recordNativeTurnFailureUsage(err, {
+                tokenUsage: usage.tokens(),
+                costUsd: usage.costUsd(),
+            });
+        }
+        throw err;
+    }
+    logTurnTailWarnings({
+        sessionName: handle.id,
+        completedNormally: state.completedNormally,
+        spinStopped: spinFlags.stopped,
+        roundTrips: state.roundTrips,
+        timedOut: state.timedOut,
+        spinBreaker: deps.spinBreaker,
+        invalidCallHalt: invalidCallBudget.halt,
+    });
+    // Persisted before returning, and a write failure fails the turn: continuing
+    // on a history that could not be stored is the silent degradation #1794
+    // removed from the pipeline (ADR-028 s4).
+    await saveTranscript(dir, handle.id, state.messages, transcriptIdentity);
+    return buildTurnResult({
+        output: state.output,
+        usage,
+        roundTrips: state.roundTrips,
+        codingTools,
+        codingToolsCalled,
+        completedNormally: state.completedNormally,
+        timedOut: state.timedOut,
+        spinStopped: spinFlags.stopped,
+        invalidCallHalt: invalidCallBudget.halt,
+        interactions,
+        pricingSource: deps.pricingSource,
+    });
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The turn's tail: the warnings emitted once the loop has exited, and the
+ * `TurnResult` assembled from what the loop accumulated.
+ *
+ * Extracted from `turn-loop.ts`, which keeps the `saveTranscript` call that
+ * sits between the two: a write failure there fails the turn, unlike the
+ * best-effort save in the catch, and that distinction belongs with the control
+ * flow rather than in a result builder.
+ */
+import type { InteractionExchange, InvalidToolCallDetail, TurnResult } from "#src/session/session-types";
+import type { CodingTool } from "#src/tools/index";
+import type { TurnAccumulator } from "./turn-accumulator.ts";
+import type { TurnDeps } from "./turn-types.ts";
+export interface LogTurnTailWarningsArgs {
+    readonly sessionName: string;
+    readonly completedNormally: boolean;
+    readonly spinStopped: boolean;
+    readonly roundTrips: number;
+    readonly timedOut: boolean;
+    readonly spinBreaker: TurnDeps["spinBreaker"];
+    /** The call that tripped the invalid-call budget; absent when it did not trip. */
+    readonly invalidCallHalt?: InvalidToolCallDetail;
+}
+export declare function logTurnTailWarnings(args: LogTurnTailWarningsArgs): void;
+export interface BuildTurnResultArgs {
+    readonly output: string;
+    readonly usage: TurnAccumulator;
+    readonly roundTrips: number;
+    readonly codingTools: readonly CodingTool[];
+    readonly codingToolsCalled: readonly string[];
+    readonly completedNormally: boolean;
+    readonly timedOut: boolean;
+    readonly spinStopped: boolean;
+    /** The call that tripped the invalid-call budget; absent when it did not trip. */
+    readonly invalidCallHalt: InvalidToolCallDetail | undefined;
+    readonly interactions: readonly InteractionExchange[];
+    readonly pricingSource: TurnDeps["pricingSource"];
+}
+export declare function buildTurnResult(args: BuildTurnResultArgs): TurnResult;