@nathapp/nax-agent 0.1.0

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

@@ -0,0 +1,200 @@
+/**
+ * Conversation persistence for the native transport.
+ *
+ * nax-ai's client is stateless — every call takes the whole message array — so
+ * nax keeps the conversation. Under ACP the acpx subprocess remembered it and
+ * nax stored nothing; SessionDescriptor still has no message field, and gains
+ * none. See ADR-028 sections 2 and 3.
+ */
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getLogger, NaxError } from "#src/infra/index";
+import { parseModelSpec } from "../models.js";
+export function transcriptPath(dir, sessionName) {
+    return join(dir, `${sessionName}.transcript.json`);
+}
+/**
+ * The model half of `TranscriptIdentity`: the native `provider/model` id with
+ * the reasoning-effort suffix stripped. A thinking signature binds to the
+ * model, not to the effort — pi-ai's own `isSameModel` compares
+ * provider/api/model for the same reason. `parseModelSpec`, not
+ * `parseNativeModel`: this must never throw.
+ */
+export function transcriptModelIdentity(rawModel) {
+    return rawModel === undefined ? undefined : parseModelSpec(rawModel).model;
+}
+/** A bare array is a pre-#1877 transcript: real messages, no recorded owner. */
+function isLegacyTranscript(parsed) {
+    return Array.isArray(parsed);
+}
+/**
+ * Missing file means a new conversation. Anything else is a real failure.
+ *
+ * Returns `[]` — a new conversation — when the transcript on disk belongs to a
+ * different `owner` or a different recorded `model` than the caller (nax#1877,
+ * nax#2150). A reader that declares no identity is not making a claim and
+ * reads whatever is there, which keeps non-op callers and unit tests working
+ * unchanged.
+ */
+export async function loadTranscript(dir, sessionName, identity = {}) {
+    let raw;
+    try {
+        raw = await readFile(transcriptPath(dir, sessionName), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        // Deliberately not [] — silently restarting a conversation would drop the
+        // history the model is mid-way through and look like a fresh session.
+        throw new NaxError(`transcript for session "${sessionName}" is unreadable: ${err instanceof Error ? err.message : String(err)}`, "TRANSCRIPT_CORRUPT", {
+            stage: "native-session",
+        });
+    }
+    if (isLegacyTranscript(parsed)) {
+        // Unowned history is foreign history to a reader that has an identity.
+        // Dropping it is the safe direction: the cost is one re-exploration, where
+        // inheriting it silently bills a conversation this session never had.
+        return identity.owner === undefined ? parsed : [];
+    }
+    const file = parsed;
+    if (isForeignTranscript(file, identity, sessionName))
+        return [];
+    return file.messages ?? [];
+}
+/**
+ * Another invocation's history (nax#1877) or another model's (nax#2150, P3
+ * spec 8.3(c)) reads as a new conversation. An ABSENT file model reads, unlike
+ * an absent owner: every native production turn records one (the adapter parses
+ * the model before the loop runs), so an absent field is a pre-upgrade file —
+ * which the owner check already keeps out of new processes.
+ */
+function isForeignTranscript(file, identity, sessionName) {
+    const { owner, model } = identity;
+    if (owner !== undefined && file.owner !== owner) {
+        getLogger().debug("native-session", "Ignoring a transcript owned by another invocation", {
+            sessionName,
+            storedOwner: file.owner,
+            owner,
+        });
+        return true;
+    }
+    if (model !== undefined && file.model !== undefined && file.model !== model) {
+        getLogger().debug("native-session", "Ignoring a transcript written by another model", {
+            sessionName,
+            storedModel: file.model,
+            model,
+        });
+        return true;
+    }
+    return false;
+}
+export async function saveTranscript(dir, sessionName, messages, identity = {}) {
+    await mkdir(dir, { recursive: true });
+    const file = {
+        ...(identity.owner !== undefined ? { owner: identity.owner } : {}),
+        ...(identity.model !== undefined ? { model: identity.model } : {}),
+        savedAt: new Date().toISOString(),
+        messages: [...messages],
+    };
+    await writeFile(transcriptPath(dir, sessionName), JSON.stringify(file, null, 2), "utf8");
+}
+/**
+ * Move a failed session's transcript off the path the next session reads.
+ *
+ * The kept-on-failure transcript (nax#1838) used to stay at its live name, which
+ * is exactly the name `loadTranscript` opens — so the post-mortem artifact and
+ * the resumption source were one file (nax#1877). Renaming keeps every byte of
+ * debugging value and removes the resumption entirely. It also stops the NEXT
+ * attempt's `saveTranscript` from overwriting the artifact #1838 wanted kept.
+ *
+ * A missing transcript is not an error: a session can fail before its first save.
+ */
+export async function retainTranscript(dir, sessionName) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    try {
+        await rename(transcriptPath(dir, sessionName), join(dir, `${sessionName}.transcript.failed-${stamp}.json`));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+export async function deleteTranscript(dir, sessionName) {
+    await rm(transcriptPath(dir, sessionName), { force: true });
+}
+/**
+ * Cap on transcripts retained per feature's `sessions/` directory. Transcripts
+ * are deleted on a clean close (`closeNativeSession`) but kept when a turn
+ * failed, so the kept-on-failure set otherwise grows without bound — nothing
+ * else prunes it (issue #1445 is the same class of unbounded `~/.nax` growth).
+ * Follows the precedent of `MAX_RETAINED_RUNS` in `src/metrics/tracker.ts`.
+ */
+export const MAX_RETAINED_TRANSCRIPTS = 50;
+/**
+ * One-shot dedupe flag, mirroring `hasWarnedAboutRunTruncation` in
+ * `src/metrics/tracker.ts`: pruning runs on every failed close, so once a
+ * feature is past the cap this would otherwise warn on every subsequent
+ * close. Log it once per process lifetime instead.
+ */
+let hasWarnedAboutTranscriptTruncation = false;
+/**
+ * Reset the one-shot truncation-warning flag (for testing only).
+ * @internal
+ */
+export function _resetTranscriptTruncationWarningForTests() {
+    hasWarnedAboutTranscriptTruncation = false;
+}
+/**
+ * Prune a feature's `sessions/` directory to the `maxRetained` most recently
+ * modified transcript files, deleting the oldest first. Called from
+ * `closeNativeSession`'s kept-on-failure branch — the only place transcripts
+ * accumulate, since a clean close always deletes its own transcript.
+ *
+ * A missing directory is not an error (nothing to prune yet).
+ *
+ * Returns the number of transcript files deleted (0 when there is nothing to
+ * delete) so callers can report the sweep's work without re-reading the dir.
+ */
+export async function pruneRetainedTranscripts(dir, maxRetained = MAX_RETAINED_TRANSCRIPTS) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+    // Matches both the live name and the `failed-<stamp>` names `retainTranscript`
+    // produces — the retained set is the one that accumulates, so a filter that
+    // missed it would leave the cap enforcing nothing.
+    const transcriptFiles = entries.filter((name) => name.includes(".transcript.") && name.endsWith(".json"));
+    if (transcriptFiles.length <= maxRetained)
+        return 0;
+    const withMtimes = await Promise.all(transcriptFiles.map(async (name) => {
+        const fullPath = join(dir, name);
+        const stats = await stat(fullPath);
+        return { path: fullPath, mtimeMs: stats.mtimeMs };
+    }));
+    // Oldest first, so the slice below drops exactly the excess over the cap.
+    withMtimes.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const toDelete = withMtimes.slice(0, withMtimes.length - maxRetained);
+    await Promise.all(toDelete.map((f) => rm(f.path, { force: true })));
+    if (!hasWarnedAboutTranscriptTruncation) {
+        hasWarnedAboutTranscriptTruncation = true;
+        getLogger().warn("native-session", "Transcript retention cap reached — oldest kept-on-failure transcripts pruned", {
+            droppedCount: toDelete.length,
+            maxRetained,
+            dir,
+        });
+    }
+    return toDelete.length;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * US-003 — the native session's model-facing truncation, applied to every
+ * genuine tool result before it enters the message array.
+ *
+ * This IS a registered `after_tool` handler now: `createTruncationHandler`
+ * builds it and `registerBuiltinLoopHandlers` registers it LAST, so it shapes
+ * whatever earlier handlers produced — the same position the loop's hardcoded
+ * call held before the seam carried it. It could not be registered while the
+ * dispatcher was synchronous: the spill write has to be awaited, because AC8's
+ * fail-open contract means the marker may only name the spill file when the
+ * write actually succeeded, so the write cannot be fired and forgotten and its
+ * outcome discovered afterwards. Dispatch is async now, so that documented
+ * exception is deleted rather than restated. The policy itself remains
+ * `applyModelTruncationPolicy` — the one implementation the coding-tool
+ * runtime applies too.
+ *
+ * The spill root is the session's scratchpad root, recorded at open from the
+ * session's workdir so the marker's relative path resolves through
+ * `ScratchpadRead`. A session driven without one (unit tests calling
+ * `runNativeTurn` directly) falls back to its transcript directory, the one path
+ * the session is known to own.
+ */
+import type { HandlerOf } from "./loop-events/types.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;
+/**
+ * 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: {
+    readonly toolName?: string;
+    readonly callId?: string;
+    readonly reserveBytes?: number;
+}): Promise<string>;
+/**
+ * The `after_tool` handler the loop registers: the same policy, at the same
+ * chokepoint, reached through the seam instead of a hardcoded call. A nudge
+ * 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">;

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

@@ -0,0 +1,83 @@
+/**
+ * US-003 — the native session's model-facing truncation, applied to every
+ * genuine tool result before it enters the message array.
+ *
+ * This IS a registered `after_tool` handler now: `createTruncationHandler`
+ * builds it and `registerBuiltinLoopHandlers` registers it LAST, so it shapes
+ * whatever earlier handlers produced — the same position the loop's hardcoded
+ * call held before the seam carried it. It could not be registered while the
+ * dispatcher was synchronous: the spill write has to be awaited, because AC8's
+ * fail-open contract means the marker may only name the spill file when the
+ * write actually succeeded, so the write cannot be fired and forgotten and its
+ * outcome discovered afterwards. Dispatch is async now, so that documented
+ * exception is deleted rather than restated. The policy itself remains
+ * `applyModelTruncationPolicy` — the one implementation the coding-tool
+ * runtime applies too.
+ *
+ * The spill root is the session's scratchpad root, recorded at open from the
+ * session's workdir so the marker's relative path resolves through
+ * `ScratchpadRead`. A session driven without one (unit tests calling
+ * `runNativeTurn` directly) falls back to its transcript directory, the one path
+ * the session is known to own.
+ */
+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);
+}
+/**
+ * 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 async function truncateNativeToolResult(sessionId, body, opts) {
+    const root = spillRootFor(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
+    // same ceiling here, or the guarantee this chokepoint exists to give (the
+    // model-facing content is at most MODEL_MAX_BYTES) is broken by exactly the
+    // bytes the caller adds. Reserving is what keeps the ceiling unconditional.
+    const reserved = Math.max(0, opts.reserveBytes ?? 0);
+    // A session opened through the runtime has a scratchpad root recorded from its
+    // workdir, which IS the directory its tools and shell start in, so a
+    // root-relative marker resolves there. The transcript-directory fallback is
+    // not that directory, so its marker must name the absolute path or the model
+    // would look for the spill somewhere it is not.
+    return applyModelTruncationPolicy(body, {
+        toolName: opts.toolName ?? "",
+        callId: opts.callId ?? "",
+        ...(root !== undefined
+            ? {
+                root,
+                spillPathStyle: nativeSessionScratchpadRoots.has(sessionId)
+                    ? "root-relative"
+                    : "absolute",
+            }
+            : {}),
+        maxBytes: Math.max(0, MODEL_MAX_BYTES - reserved),
+    });
+}
+/**
+ * The `after_tool` handler the loop registers: the same policy, at the same
+ * chokepoint, reached through the seam instead of a hardcoded call. A nudge
+ * 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) {
+    return async (payload) => {
+        const shaped = await truncateNativeToolResult(sessionName, payload.content, {
+            toolName: payload.toolName,
+            callId: payload.callId,
+            ...(payload.nudgeText !== undefined ? { reserveBytes: nudgeOverheadBytes(payload.nudgeText) } : {}),
+        });
+        return { content: shaped };
+    };
+}

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

@@ -0,0 +1,45 @@
+/**
+ * The six usage/cost/rate counters `runNativeTurn` accumulates.
+ *
+ * Extracted because the same ten lines appeared three times — after a
+ * proactive compaction summary, after a reactive overflow summary, and after
+ * each round trip — and a fourth copy was one loop event away. A factory
+ * returning an object, matching `createRateTotals` and `createInvalidCallBudget`.
+ *
+ * `add` and `usageBeat` are deliberately separate: the round-trip beat carries
+ * `roundTrip` and the two summary beats do not, so folding the beat into `add`
+ * would either drop that field or fabricate it for the summaries.
+ */
+import type { PricingRates, TokenUsage } from "#src/cost/standard-types";
+import type { NativeTurnActivity } from "./turn-events.ts";
+/**
+ * Token counts ONLY. `costUsd` is deliberately NOT a field here: both readers
+ * (`recordNativeTurnFailureUsage` at turn-loop.ts:542 and the TurnResult at
+ * :580) take `tokenUsage` and the cost as SEPARATE arguments, so folding cost
+ * in would force every call site to destructure it back out.
+ */
+export interface TurnTokenTotals {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /**
+     * Undefined until something reports cache data, then a running sum. Staying
+     * undefined when nothing ever reports it preserves the absent/zero
+     * distinction nax-ai's `toTokenUsage` establishes: "no cache data" and "zero
+     * cache tokens" must stay distinguishable downstream (nax#2045).
+     */
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+export interface TurnAccumulator {
+    add(usage: TokenUsage, costUsd: number, rates?: PricingRates): void;
+    tokens(): TurnTokenTotals;
+    costUsd(): number;
+    /** Aggregated rate provenance, or undefined when nothing priced. */
+    rates(): PricingRates | undefined;
+}
+export declare function createTurnAccumulator(): TurnAccumulator;
+/**
+ * The `onActivity` usage beat. `roundTrip` is 1-based and omitted for the two
+ * compaction-summary beats, which are not round trips.
+ */
+export declare function usageBeat(usage: TokenUsage, costUsd: number, roundTrip?: number): NativeTurnActivity;

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

@@ -0,0 +1,67 @@
+/**
+ * The six usage/cost/rate counters `runNativeTurn` accumulates.
+ *
+ * Extracted because the same ten lines appeared three times — after a
+ * proactive compaction summary, after a reactive overflow summary, and after
+ * each round trip — and a fourth copy was one loop event away. A factory
+ * returning an object, matching `createRateTotals` and `createInvalidCallBudget`.
+ *
+ * `add` and `usageBeat` are deliberately separate: the round-trip beat carries
+ * `roundTrip` and the two summary beats do not, so folding the beat into `add`
+ * would either drop that field or fabricate it for the summaries.
+ */
+import { addRateTotals, aggregateRates, createRateTotals } from "./rate-provenance.js";
+import { cacheUsageFields } from "./turn-types.js";
+export function createTurnAccumulator() {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens;
+    let cacheWriteTokens;
+    let costUsd = 0;
+    const rateTotals = createRateTotals();
+    return {
+        add(usage, addedCostUsd, rates) {
+            inputTokens += usage.inputTokens;
+            outputTokens += usage.outputTokens;
+            if (usage.cacheReadTokens !== undefined) {
+                cacheReadTokens = (cacheReadTokens ?? 0) + usage.cacheReadTokens;
+            }
+            if (usage.cacheWriteTokens !== undefined) {
+                cacheWriteTokens = (cacheWriteTokens ?? 0) + usage.cacheWriteTokens;
+            }
+            costUsd += addedCostUsd;
+            addRateTotals(rateTotals, usage, rates);
+        },
+        tokens() {
+            return {
+                inputTokens,
+                outputTokens,
+                ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+                ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
+            };
+        },
+        costUsd() {
+            return costUsd;
+        },
+        rates() {
+            return aggregateRates(rateTotals);
+        },
+    };
+}
+/**
+ * The `onActivity` usage beat. `roundTrip` is 1-based and omitted for the two
+ * compaction-summary beats, which are not round trips.
+ */
+export function usageBeat(usage, costUsd, roundTrip) {
+    return {
+        kind: "usage",
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        costUsd,
+        // Absent stays absent (never 0): `cacheReadTokens` stays
+        // `number | undefined` so "no cache data" and "zero cache tokens"
+        // remain distinguishable downstream (nax#2045).
+        ...cacheUsageFields(usage),
+        ...(roundTrip !== undefined ? { roundTrip } : {}),
+    };
+}

package/dist/native/session/turn-ask-human.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `ask_human` branch of the turn loop's tool-call batch.
+ *
+ * Extracted unchanged. It is not an ordinary tool call: no tool produced it,
+ * so it deliberately fires no `before_tool`/`after_tool` event — a policy that
+ * shapes tool output has nothing to shape here.
+ */
+import type { InteractionExchange, SendTurnOpts } from "#src/session/session-types";
+import { type ToolResultMessage } from "./tool-result.ts";
+export interface AskHumanOutcome {
+    /** Appended to the message array by the caller. */
+    readonly result: ToolResultMessage;
+    /** Present only when a real exchange happened; the caller pushes it. */
+    readonly exchange?: InteractionExchange;
+}
+export declare function handleAskHumanCall(args: {
+    readonly toolCallId: string;
+    readonly question: string;
+    readonly interactionsSoFar: number;
+    readonly maxInteractions: number;
+    readonly roundTrips: number;
+    readonly interactionHandler: SendTurnOpts["interactionHandler"];
+}): Promise<AskHumanOutcome>;

package/dist/native/session/turn-ask-human.js

@@ -0,0 +1,41 @@
+/**
+ * The `ask_human` branch of the turn loop's tool-call batch.
+ *
+ * Extracted unchanged. It is not an ordinary tool call: no tool produced it,
+ * so it deliberately fires no `before_tool`/`after_tool` event — a policy that
+ * shapes tool output has nothing to shape here.
+ */
+import { buildToolResult } from "./tool-result.js";
+export async function handleAskHumanCall(args) {
+    const { toolCallId, question, interactionsSoFar, maxInteractions, roundTrips, interactionHandler } = args;
+    // An unset budget (maxInteractions undefined -> 0) keeps the tool unadvertised
+    // above AND refuses a call made anyway. "No budget configured" must not
+    // read as "unlimited" — that inverts the property this budget provides.
+    if (interactionsSoFar >= maxInteractions) {
+        return {
+            result: buildToolResult({
+                toolCallId,
+                content: "The human Q&A budget for this turn is spent. Proceed on your best judgement.",
+                isError: true,
+            }),
+        };
+    }
+    const answer = await interactionHandler.onInteraction({ kind: "question", text: question });
+    // A null answer means no operator is reachable — run-interaction-handler
+    // returns null for kind:"question" when no interactionBridge is
+    // configured. That is not an exchange: it must not consume budget and
+    // must not be recorded as a question the operator answered with "".
+    if (answer === null) {
+        return {
+            result: buildToolResult({
+                toolCallId,
+                content: "No human operator is available for this run. Proceed on your best judgement.",
+                isError: true,
+            }),
+        };
+    }
+    return {
+        result: buildToolResult({ toolCallId, content: answer.answer }),
+        exchange: { turnIndex: roundTrips, question, reply: answer.answer },
+    };
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 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 { type TranscriptMessage as NativeTranscriptMessage } from "./compaction.ts";
+import type { LoopEventRegistry } from "./loop-events/index.ts";
+import { type TurnAccumulator } from "./turn-accumulator.ts";
+import type { TurnDeps } from "./turn-types.ts";
+/**
+ * The compaction dependencies, with the three the step cannot run without
+ * required. `TurnDeps` has them optional (absent disables compaction); the call
+ * site narrows them to defined with the guard before calling, and requiring them
+ * here is what carries that narrowing into this module.
+ */
+export interface CompactionStepDeps {
+    readonly summarize: NonNullable<TurnDeps["summarize"]>;
+    readonly contextWindow: NonNullable<TurnDeps["contextWindow"]>;
+    readonly compaction: NonNullable<TurnDeps["compaction"]>;
+    readonly onActivity?: TurnDeps["onActivity"];
+    readonly deadline?: TurnDeps["deadline"];
+}
+export interface CompactionStepArgs {
+    readonly messages: readonly NativeTranscriptMessage[];
+    readonly usage: TurnAccumulator;
+    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. Threaded from `turn-loop.ts`
+     * and from `completeWithRecovery`'s own arg, the same as `CompleteStepArgs`.
+     */
+    readonly loopEvents: LoopEventRegistry;
+    readonly deps: CompactionStepDeps;
+    readonly signal?: AbortSignal;
+}
+export interface CompactionStepResult {
+    readonly messages: readonly NativeTranscriptMessage[];
+    /** True when the array was rebound, so the caller clears lastUsage/anchorIndex. */
+    readonly compacted: boolean;
+    /** Proactive only: the summarizer threw, so the overflow retry must not try again. */
+    readonly summarizeFailed: boolean;
+}
+export interface OverflowCompactionArgs extends CompactionStepArgs {
+    /**
+     * The original context-overflow error. `prepareCompaction` returning undefined
+     * means there is nothing safe left to drop, so it is rethrown verbatim —
+     * tests and the failure-usage ledger key on the error's own identity.
+     */
+    readonly error: unknown;
+}
+export declare function runProactiveCompaction(args: CompactionStepArgs): Promise<CompactionStepResult>;
+export declare function runOverflowCompaction(args: OverflowCompactionArgs): Promise<CompactionStepResult>;