@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/native/session/transcript-types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The transcript port (S3 spec 5.5). The native loop loads the whole history
+ * through it at turn start and saves a fresh snapshot at turn end, so a store
+ * is a document store, not a log. nax uses the file store
+ * (`createFileTranscriptStore`); an embedder may inject its own.
+ */
+import type { ConversationMessage } from "@nathapp/nax-ai";
+/** Facade-owned turn bookkeeping. The loop never writes it; `markTurn` does. */
+export interface TurnMarker {
+    readonly turnId: string;
+    readonly state: "running" | "ended";
+}
+export interface TranscriptDoc {
+    /** Absent means 1. nax-agent does not write it in S3-1. */
+    readonly schemaVersion?: 1;
+    readonly owner?: string;
+    readonly model?: string;
+    readonly savedAt: string;
+    readonly messages: readonly ConversationMessage[];
+    /**
+     * Owned by `markTurn`. The loop never writes it, and its saves replace the
+     * whole document, so a loop save drops it; the caller re-marks after the turn
+     * (S3 spec 5.5 write order: markTurn(running), turn, markTurn(ended)).
+     */
+    readonly turn?: TurnMarker;
+}
+export interface TranscriptStore {
+    /** `null` when the session has no document yet. */
+    load(sessionId: string): Promise<TranscriptDoc | null>;
+    /** Replace the document. The loop calls it at turn end and after a caught turn error. */
+    save(sessionId: string, doc: TranscriptDoc): Promise<void>;
+    /** Move the live document out of `load`'s reach, keeping it for a human. Missing is not an error. */
+    retainFailed(sessionId: string): Promise<void>;
+    /** Missing is not an error. */
+    delete(sessionId: string): Promise<void>;
+    /** Read-merge `turn` into the document, creating an empty one when none exists. */
+    markTurn(sessionId: string, marker: TurnMarker): Promise<void>;
+}

package/dist/native/session/transcript-types.js

@@ -0,0 +1,7 @@
+/**
+ * The transcript port (S3 spec 5.5). The native loop loads the whole history
+ * through it at turn start and saves a fresh snapshot at turn end, so a store
+ * is a document store, not a log. nax uses the file store
+ * (`createFileTranscriptStore`); an embedder may inject its own.
+ */
+export {};

package/dist/native/session/truncation-handler.d.ts

@@ -21,19 +21,20 @@
  * the session is known to own.
  */
 import type { HandlerOf } from "./loop-events/types.ts";
+import type { NativeSessionState } from "./session.ts";
 /**
  * Where this session's spills belong, or `undefined` when the session is not
  * known to the runtime at all — in which case nothing is spilled and the marker
  * names no path, rather than naming a file written somewhere unreachable.
  */
-export declare function spillRootFor(sessionId: string): string | undefined;
+export declare function spillRootFor(state: NativeSessionState, sessionId: string): string | undefined;
 /**
  * Shape one tool result for the model: within every cap it is returned
  * untouched (and nothing is spilled); over a cap it is cut, the untruncated
  * body is written under the scratchpad, and the content ends with the marker
  * naming the spill path and both byte counts.
  */
-export declare function truncateNativeToolResult(sessionId: string, body: string, opts: {
+export declare function truncateNativeToolResult(state: NativeSessionState, sessionId: string, body: string, opts: {
     readonly toolName?: string;
     readonly callId?: string;
     readonly reserveBytes?: number;
@@ -44,4 +45,4 @@ export declare function truncateNativeToolResult(sessionId: string, body: string
  * riding on the payload reserves its own bytes out of the result's budget, so
  * the ceiling holds after `withNudge` prepends it.
  */
-export declare function createTruncationHandler(sessionName: string): HandlerOf<"after_tool">;
+export declare function createTruncationHandler(state: NativeSessionState, sessionName: string): HandlerOf<"after_tool">;

package/dist/native/session/truncation-handler.js

@@ -22,14 +22,13 @@
  */
 import { applyModelTruncationPolicy, MODEL_MAX_BYTES } from "#src/tools/index";
 import { nudgeOverheadBytes } from "./nudge.js";
-import { nativeSessionScratchpadRoots, nativeTranscriptDirs } from "./session.js";
 /**
  * Where this session's spills belong, or `undefined` when the session is not
  * known to the runtime at all — in which case nothing is spilled and the marker
  * names no path, rather than naming a file written somewhere unreachable.
  */
-export function spillRootFor(sessionId) {
-    return nativeSessionScratchpadRoots.get(sessionId) ?? nativeTranscriptDirs.get(sessionId);
+export function spillRootFor(state, sessionId) {
+    return state.scratchpadRoots.get(sessionId) ?? state.transcriptDirs.get(sessionId);
 }
 /**
  * Shape one tool result for the model: within every cap it is returned
@@ -37,8 +36,8 @@ export function spillRootFor(sessionId) {
  * body is written under the scratchpad, and the content ends with the marker
  * naming the spill path and both byte counts.
  */
-export async function truncateNativeToolResult(sessionId, body, opts) {
-    const root = spillRootFor(sessionId);
+export async function truncateNativeToolResult(state, sessionId, body, opts) {
+    const root = spillRootFor(state, sessionId);
     // `reserveBytes` is what the CALLER will add to this result after the policy
     // has run -- today only the spin-breaker nudge, which the turn loop prepends.
     // Anything appended or prepended downstream has to be charged against the
@@ -57,9 +56,7 @@ export async function truncateNativeToolResult(sessionId, body, opts) {
         ...(root !== undefined
             ? {
                 root,
-                spillPathStyle: nativeSessionScratchpadRoots.has(sessionId)
-                    ? "root-relative"
-                    : "absolute",
+                spillPathStyle: state.scratchpadRoots.has(sessionId) ? "root-relative" : "absolute",
             }
             : {}),
         maxBytes: Math.max(0, MODEL_MAX_BYTES - reserved),
@@ -71,9 +68,9 @@ export async function truncateNativeToolResult(sessionId, body, opts) {
  * riding on the payload reserves its own bytes out of the result's budget, so
  * the ceiling holds after `withNudge` prepends it.
  */
-export function createTruncationHandler(sessionName) {
+export function createTruncationHandler(state, sessionName) {
     return async (payload) => {
-        const shaped = await truncateNativeToolResult(sessionName, payload.content, {
+        const shaped = await truncateNativeToolResult(state, sessionName, payload.content, {
             toolName: payload.toolName,
             callId: payload.callId,
             ...(payload.nudgeText !== undefined ? { reserveBytes: nudgeOverheadBytes(payload.nudgeText) } : {}),

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

@@ -9,7 +9,7 @@
  * 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
+ * COPY only, and the array the caller holds (which the turn-end transcript save 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
@@ -21,6 +21,7 @@
 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 { TurnEventEmitter } from "./turn-event-emitter.ts";
 import type { NativeTurnResponse, TurnDeps } from "./turn-types.ts";
 export interface CompleteStepResult {
     readonly res: NativeTurnResponse;
@@ -73,5 +74,7 @@ export interface CompleteStepArgs {
     readonly model?: string;
     readonly deps: TurnDeps;
     readonly signal?: AbortSignal;
+    /** S3-3: the turn's event emitter. Emits stream_reset and the overflow compaction; hands the adapter a per-attempt delta sink. */
+    readonly turnEvents: TurnEventEmitter;
 }
 export declare function completeWithRecovery(args: CompleteStepArgs): Promise<CompleteStepResult>;

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

@@ -9,7 +9,7 @@
  * 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
+ * COPY only, and the array the caller holds (which the turn-end transcript save 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
@@ -33,7 +33,7 @@ function isContextOverflow(err) {
     return protocolError?.kind === "context-overflow";
 }
 export async function completeWithRecovery(args) {
-    const { tools, usage, summarizeFailed, sessionName, lastUsage, anchorIndex, loopEvents, roundTrip, model, deps, signal, } = args;
+    const { tools, usage, summarizeFailed, sessionName, lastUsage, anchorIndex, loopEvents, roundTrip, model, deps, signal, turnEvents, } = args;
     let messages = args.messages;
     let compacted = false;
     let honoured = false;
@@ -47,6 +47,12 @@ export async function completeWithRecovery(args) {
     let attempt = 0;
     const request = async (msgs) => {
         attempt += 1;
+        // Spec 5.3: every request attempt after the first voids the round's
+        // deltas so far. nax-ai retries only before the first event, so any
+        // re-issue with deltas already shown comes from here (transport retry or
+        // the overflow retry).
+        if (attempt > 1)
+            turnEvents.emit({ type: "stream_reset", round: roundTrip, attempt });
         const patch = await loopEvents.dispatch("before_request", {
             ...(model !== undefined ? { model } : {}),
             roundTrip,
@@ -56,7 +62,7 @@ export async function completeWithRecovery(args) {
         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,
+        // caller's array, the one the turn-end transcript save 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:
@@ -79,7 +85,7 @@ export async function completeWithRecovery(args) {
         // 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);
+        return deps.complete(wire.messages, tools, options, turnEvents.deltaSink(roundTrip));
     };
     try {
         res = await request(messages);
@@ -150,6 +156,7 @@ export async function completeWithRecovery(args) {
             });
             messages = [...step.messages];
             compacted = true;
+            turnEvents.emit({ type: "compaction", reason: "overflow" });
             // Retried once. A second overflow propagates: compacting further would be
             // guessing, and the failure now carries a correct diagnosis.
             res = await request(messages);

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

@@ -0,0 +1,48 @@
+/**
+ * The one caller of an embedder's `onTurnEvent` sink (S3-3).
+ *
+ * Built once per turn by `runNativeTurn`. Every method is a no-op without a
+ * sink, so nax (which sets none) does no redaction or encoding work. The
+ * emitter owns every branch the event sites would otherwise need, which keeps
+ * `runToolBatch` and `sendTurn` free of new branches (complexity ratchet).
+ *
+ * - A sink that throws, or returns a promise that rejects, is contained and
+ *   logged once per turn: an embedder's bug must not end a turn, a tool call
+ *   or a Node process (an unhandled rejection does, by default).
+ * - Tool input is redacted with the logger's redactor before it leaves; the
+ *   result preview first cuts to `REDACTION_SCAN_BYTES` to bound the scan,
+ *   redacts, then cuts to `TOOL_RESULT_PREVIEW_BYTES` on a codepoint boundary.
+ *   The final cut follows redaction so it cannot split a secret into a prefix
+ *   the patterns no longer match.
+ * - `toolResult` reports only a call `toolCall` reported (counted per id), and
+ *   `flushUnanswered` answers what is left when a turn throws, so a consumer
+ *   sees each `tool_call` answered by exactly one `tool_result`.
+ * - Redaction is best-effort (see `TurnEvent`'s doc) and runs over a bounded
+ *   prefix: a result can be up to 2 MB when no truncation handler ran.
+ */
+import type { ToolCall } from "@nathapp/nax-ai";
+import type { TokenUsage } from "#src/cost/standard-types";
+import type { TurnEvent, TurnEventSink } from "#src/session/turn-event";
+import type { ToolResultMessage } from "./tool-result.ts";
+/** Byte cap on `tool_result.preview`. A preview is for display; the transcript holds the full result. */
+export declare const TOOL_RESULT_PREVIEW_BYTES = 4096;
+/** Byte cap on `tool_call.input` as JSON; a larger input becomes `{ truncated: true, preview }`. */
+export declare const TOOL_CALL_INPUT_BYTES = 8192;
+/** One streamed delta, before the loop stamps its round. */
+export interface StreamDelta {
+    readonly type: "text_delta" | "thinking_delta";
+    readonly text: string;
+}
+export type StreamDeltaSink = (delta: StreamDelta) => void;
+export interface TurnEventEmitter {
+    emit(event: TurnEvent): void;
+    /** A delta sink stamped with `round`; undefined without a sink, so the adapter's tap stays a pass-through. */
+    deltaSink(round: number): StreamDeltaSink | undefined;
+    /** `recordedInput` is a `before_tool` rewrite when there is one; otherwise the model's `call.input` is reported. */
+    toolCall(call: ToolCall, recordedInput: unknown): void;
+    toolResult(result: ToolResultMessage): void;
+    /** Answers every outstanding `tool_call` with an error result. Called from the turn's catch block. */
+    flushUnanswered(): void;
+}
+export declare function usageEvent(round: number, usage: TokenUsage, costUsd: number): TurnEvent;
+export declare function createTurnEventEmitter(sink: TurnEventSink | undefined): TurnEventEmitter;

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

@@ -0,0 +1,134 @@
+/**
+ * The one caller of an embedder's `onTurnEvent` sink (S3-3).
+ *
+ * Built once per turn by `runNativeTurn`. Every method is a no-op without a
+ * sink, so nax (which sets none) does no redaction or encoding work. The
+ * emitter owns every branch the event sites would otherwise need, which keeps
+ * `runToolBatch` and `sendTurn` free of new branches (complexity ratchet).
+ *
+ * - A sink that throws, or returns a promise that rejects, is contained and
+ *   logged once per turn: an embedder's bug must not end a turn, a tool call
+ *   or a Node process (an unhandled rejection does, by default).
+ * - Tool input is redacted with the logger's redactor before it leaves; the
+ *   result preview first cuts to `REDACTION_SCAN_BYTES` to bound the scan,
+ *   redacts, then cuts to `TOOL_RESULT_PREVIEW_BYTES` on a codepoint boundary.
+ *   The final cut follows redaction so it cannot split a secret into a prefix
+ *   the patterns no longer match.
+ * - `toolResult` reports only a call `toolCall` reported (counted per id), and
+ *   `flushUnanswered` answers what is left when a turn throws, so a consumer
+ *   sees each `tool_call` answered by exactly one `tool_result`.
+ * - Redaction is best-effort (see `TurnEvent`'s doc) and runs over a bounded
+ *   prefix: a result can be up to 2 MB when no truncation handler ran.
+ */
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { capStrings, redactSecrets } from "#src/internal/redact";
+import { isThenable } from "#src/internal/thenable";
+import { cutToByteCap } from "#src/tools/truncate";
+import { cacheUsageFields } from "./turn-types.js";
+/** Byte cap on `tool_result.preview`. A preview is for display; the transcript holds the full result. */
+export const TOOL_RESULT_PREVIEW_BYTES = 4096;
+/** Byte cap on `tool_call.input` as JSON; a larger input becomes `{ truncated: true, preview }`. */
+export const TOOL_CALL_INPUT_BYTES = 8192;
+/** Redaction scans at most this many bytes of a result, and of each string in a tool input; the preview keeps far fewer. */
+const REDACTION_SCAN_BYTES = TOOL_RESULT_PREVIEW_BYTES * 16;
+const UNANSWERED_PREVIEW = "Not answered: the turn ended.";
+export function usageEvent(round, usage, costUsd) {
+    return {
+        type: "usage",
+        round,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        ...cacheUsageFields(usage),
+        costUsd,
+    };
+}
+function cappedInput(input) {
+    const redacted = redactSecrets(capStrings(input, REDACTION_SCAN_BYTES));
+    let json;
+    try {
+        json = JSON.stringify(redacted) ?? "null";
+    }
+    catch {
+        return { truncated: true, preview: "[input not serializable]" };
+    }
+    if (Buffer.byteLength(json, "utf8") <= TOOL_CALL_INPUT_BYTES)
+        return redacted;
+    return { truncated: true, preview: cutToByteCap(json, TOOL_CALL_INPUT_BYTES) };
+}
+function previewOf(content) {
+    return cutToByteCap(redactSecrets(cutToByteCap(content, REDACTION_SCAN_BYTES)), TOOL_RESULT_PREVIEW_BYTES);
+}
+const NOOP_EMITTER = {
+    emit: () => { },
+    deltaSink: () => undefined,
+    toolCall: () => { },
+    toolResult: () => { },
+    flushUnanswered: () => { },
+};
+export function createTurnEventEmitter(sink) {
+    if (sink === undefined)
+        return NOOP_EMITTER;
+    let warned = false;
+    /** Outstanding tool calls per id: a provider can repeat an id within a batch. */
+    const outstanding = new Map();
+    const contain = (event, err) => {
+        if (warned)
+            return;
+        warned = true;
+        try {
+            getSafeLogger()?.warn("native-turn-events", "onTurnEvent sink failed; events are still delivered", {
+                eventType: event.type,
+                error: errorMessage(err),
+            });
+        }
+        catch {
+            // The containment path itself must never throw or reject.
+        }
+    };
+    const emit = (event) => {
+        try {
+            const returned = sink(event);
+            if (isThenable(returned))
+                returned.then(undefined, (err) => contain(event, err));
+        }
+        catch (err) {
+            contain(event, err);
+        }
+    };
+    return {
+        emit,
+        deltaSink: (round) => (delta) => emit({ ...delta, round }),
+        toolCall(call, recordedInput) {
+            // Capped BEFORE the count moves: a throwing input (a hostile getter or
+            // proxy) must not leave an outstanding call the matching toolResult then
+            // answers with no preceding tool_call.
+            const input = cappedInput(recordedInput ?? call.input);
+            outstanding.set(call.id, (outstanding.get(call.id) ?? 0) + 1);
+            emit({ type: "tool_call", callId: call.id, name: call.name, input });
+        },
+        toolResult(result) {
+            const count = outstanding.get(result.toolCallId) ?? 0;
+            if (count === 0)
+                return;
+            if (count === 1)
+                outstanding.delete(result.toolCallId);
+            else
+                outstanding.set(result.toolCallId, count - 1);
+            emit({
+                type: "tool_result",
+                callId: result.toolCallId,
+                isError: result.isError === true,
+                preview: previewOf(result.content),
+            });
+        },
+        flushUnanswered() {
+            for (const [callId, count] of outstanding) {
+                for (let i = 0; i < count; i += 1) {
+                    emit({ type: "tool_result", callId, isError: true, preview: UNANSWERED_PREVIEW });
+                }
+            }
+            outstanding.clear();
+        },
+    };
+}

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

@@ -38,6 +38,7 @@ import { type TranscriptMessage as NativeTranscriptMessage } from "./compaction.
 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 TurnEventEmitter } from "./turn-event-emitter.ts";
 import type { TurnDeps } from "./turn-types.ts";
 /**
  * The per-turn bound on `before_turn_end`'s followUp channel (spec 6.4): the
@@ -71,7 +72,7 @@ export interface TurnRoundParams {
     handle: SessionHandle;
     opts: SendTurnOpts;
     deps: TurnDeps;
-    /** `transcriptIdentity.model` — carried into every `nativeSessionLastUsage.set` this turn writes. */
+    /** `transcriptIdentity.model` — carried into every `sessionState.lastUsage.set` this turn writes. */
     transcriptModel: string | undefined;
     tools: ToolDefinition[];
     codingToolNames: ReadonlySet<string>;
@@ -86,6 +87,8 @@ export interface TurnRoundParams {
     codingToolsCalled: string[];
     /** Mutated in place via `.add()` — the caller owns the turn-lifetime accumulator. */
     usage: ReturnType<typeof createTurnAccumulator>;
+    /** S3-3: the turn's one event emitter (a no-op without an `onTurnEvent` sink). */
+    turnEvents: TurnEventEmitter;
 }
 /**
  * Deliberately unbounded by COUNT of varied calls. A coding agent working a
@@ -103,7 +106,7 @@ export type TurnEndOutcome = {
 };
 /**
  * P3 `before_turn_end` (spec 6.4): fires at every turn ENDING, before the
- * final saveTranscript. `stopped` is dispatcher-computed: the three endings
+ * final turn-end transcript save. `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

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

@@ -34,10 +34,10 @@
 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 { usageEvent } from "./turn-event-emitter.js";
 import { runToolBatch } from "./turn-tool-batch.js";
 /**
  * The per-turn bound on `before_turn_end`'s followUp channel (spec 6.4): the
@@ -92,6 +92,7 @@ async function maybeCompact(state, params) {
         // The anchor described the pre-compaction array; it is meaningless now.
         state.lastUsage = undefined;
         state.anchorIndex = undefined;
+        params.turnEvents.emit({ type: "compaction", reason: "proactive" });
     }
     return { summarizeFailed: step.summarizeFailed };
 }
@@ -121,6 +122,7 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
         roundTrip: state.roundTrips + 1,
         ...(handle.modelDef?.model !== undefined ? { model: handle.modelDef.model } : {}),
         deps,
+        turnEvents: params.turnEvents,
         ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     });
     const res = step.res;
@@ -146,13 +148,14 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
     const promptTokens = inputClassTokens(res.usage);
     state.lastUsage = { promptTokens };
     state.anchorIndex = state.messages.length - 1;
-    nativeSessionLastUsage.set(handle.id, {
+    deps.sessionState.lastUsage.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));
+    params.turnEvents.emit(usageEvent(state.roundTrips, res.usage, res.costUsd));
     if (res.text.length > 0)
         deps.onActivity?.({ kind: "message", bytes: res.text.length });
     if (res.thinking !== undefined && res.thinking.length > 0) {
@@ -219,6 +222,7 @@ async function dispatchToolBatch(state, params, toolCalls) {
         maxInteractions,
         spinWarned: spinFlags.warned,
         interactionsSoFar: params.interactions.length,
+        turnEvents: params.turnEvents,
     });
     state.messages = [...batch.messages];
     params.interactions.push(...batch.interactions);
@@ -229,7 +233,7 @@ async function dispatchToolBatch(state, params, toolCalls) {
         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
+    // through the existing catch block — its best-effort transcript save
     // 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
@@ -267,7 +271,7 @@ export async function runRoundTripLoop(state, params) {
 }
 /**
  * P3 `before_turn_end` (spec 6.4): fires at every turn ENDING, before the
- * final saveTranscript. `stopped` is dispatcher-computed: the three endings
+ * final turn-end transcript save. `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

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

@@ -24,11 +24,12 @@ 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 { sessionAnchorFor, sessionTranscriptFor } from "./session.js";
 import { codingToolsToDefinitions, toToolDefinitions } from "./tool-mapping.js";
-import { loadTranscript, saveTranscript, transcriptModelIdentity, } from "./transcript-store.js";
+import { historyFromTranscript, transcriptDocFor, transcriptModelIdentity, } from "./transcript-identity.js";
 import { createTurnAccumulator } from "./turn-accumulator.js";
 import { dispatchTurnEndOnError } from "./turn-end-event.js";
+import { createTurnEventEmitter } from "./turn-event-emitter.js";
 import { runRoundTripLoop, runTurnEndPhase } from "./turn-loop-round-trip.js";
 import { buildTurnResult, logTurnTailWarnings } from "./turn-result.js";
 import { recordNativeTurnFailureUsage } from "./turn-types.js";
@@ -49,21 +50,25 @@ function beforeTurnSeed(patch, prompt) {
     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", {
+    const transcript = sessionTranscriptFor(deps.sessionState, handle.id);
+    if (transcript === undefined) {
+        throw new NaxError(`no transcript store for session "${handle.id}"`, "NATIVE_TRANSCRIPT_DIR_MISSING", {
             stage: "native-session",
         });
     }
+    const { store } = transcript;
     // 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.
+    // nax#2150 (P3 spec 8.3): so does a recorded different model — the loop
+    // applies that guarantee to every store's document (historyFromTranscript),
+    // whatever the session layer above decided.
     const transcriptIdentity = {
-        owner: nativeSessionTranscriptOwners.get(handle.id),
+        owner: deps.sessionState.transcriptOwners.get(handle.id),
         model: transcriptModelIdentity(handle.modelDef?.model),
     };
-    let messages = [...(await loadTranscript(dir, handle.id, transcriptIdentity))];
+    let messages = [
+        ...historyFromTranscript(await store.load(handle.id), transcriptIdentity, handle.id),
+    ];
     // 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
@@ -75,6 +80,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
     const loopEvents = deps.loopEvents ?? createLoopEventRegistry();
     registerBuiltinLoopHandlers(loopEvents, {
         sessionName: handle.id,
+        sessionState: deps.sessionState,
         budget: invalidCallBudget,
         ...(deps.spinBreaker !== undefined ? { spinBreaker: deps.spinBreaker } : {}),
         ...(deps.loopHandlers !== undefined ? { loopHandlers: deps.loopHandlers } : {}),
@@ -84,7 +90,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
             spinFlags.warned = true;
         },
     });
-    const anchor = sessionAnchorFor(handle.id, transcriptIdentity.model);
+    const anchor = sessionAnchorFor(deps.sessionState, 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
@@ -101,7 +107,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
         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
+    // rewrites the IN-MEMORY array, and the turn-end transcript save
     // persists it — before_turn is the conversation-rewriting event, unlike
     // transform_context's wire-copy-only ruling (spec 6.6).
     messages = [
@@ -148,6 +154,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
         interactions,
         codingToolsCalled,
         usage,
+        turnEvents: createTurnEventEmitter(deps.onTurnEvent),
     };
     let state = {
         messages,
@@ -183,6 +190,9 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
         }
     }
     catch (err) {
+        // S3-3: a throw can leave a reported tool_call unanswered; answer it so the
+        // sink's one-result-per-call rule holds on every ending.
+        params.turnEvents.flushUnanswered();
         // 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
@@ -205,7 +215,11 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
         // 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) => {
+        // Deferred into a promise so a store whose `save` throws synchronously is
+        // caught here too, rather than escaping and replacing the turn's error.
+        await Promise.resolve()
+            .then(() => store.save(handle.id, transcriptDocFor(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),
@@ -233,7 +247,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
     // 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);
+    await store.save(handle.id, transcriptDocFor(state.messages, transcriptIdentity));
     return buildTurnResult({
         output: state.output,
         usage,

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

@@ -2,7 +2,7 @@
  * 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
+ * Extracted from `turn-loop.ts`, which keeps the turn-end transcript save 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.

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

@@ -2,7 +2,7 @@
  * 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
+ * Extracted from `turn-loop.ts`, which keeps the turn-end transcript save 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.

package/dist/native/session/turn-tool-batch.d.ts

@@ -22,6 +22,7 @@ import type { InteractionExchange, SendTurnOpts } from "#src/session/session-typ
 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 { TurnEventEmitter } from "./turn-event-emitter.ts";
 import type { TurnDeps } from "./turn-types.ts";
 export interface ToolBatchResult {
     readonly messages: readonly NativeTranscriptMessage[];
@@ -57,5 +58,7 @@ export interface ToolBatchArgs {
     readonly spinWarned: boolean;
     /** Exchanges already recorded this turn, so the ask_human budget is turn-lifetime, not per-batch. */
     readonly interactionsSoFar: number;
+    /** S3-3: the turn's event emitter; reports each answered call (no-op without a sink). */
+    readonly turnEvents: TurnEventEmitter;
 }
 export declare function runToolBatch(args: ToolBatchArgs): Promise<ToolBatchResult>;