@nathapp/nax-agent 0.1.0

package/dist/native/session/session.js

@@ -0,0 +1,208 @@
+/**
+ * Native session lifecycle.
+ *
+ * There is no subprocess and no backend that remembers, so opening a session
+ * establishes nothing — it records where the conversation will be kept. ADR-027
+ * section 10 predicted exactly this shape: "openSession and closeSession become
+ * either no-ops or transcript-file handles".
+ */
+import { NaxError } from "#src/infra/index";
+import { createSpinBreaker } from "#src/infra/spin-breaker/index";
+import { NATIVE_AGENT } from "../models.js";
+import { nativeSessionId } from "../session-affinity.js";
+import { deleteTranscript, pruneRetainedTranscripts, retainTranscript } from "./transcript-store.js";
+/**
+ * Session name -> transcript directory, so sendTurn and close can find it.
+ *
+ * Cleared by every close path — `closeNativeSession` (in-process) and the
+ * adapter's `closePhysicalSession` (run teardown, which only has the name) —
+ * through the shared `clearNativeSessionState`. A caller that opens a session
+ * and never closes it (e.g. an early return, or a thrown error between open and
+ * close) still leaks an entry for the lifetime of the process. Harmless in
+ * practice (it is a small in-memory map keyed by session name, not a handle
+ * to a real resource), but worth knowing when debugging a growing map.
+ */
+export const nativeTranscriptDirs = new Map();
+/**
+ * Session name -> the root whose `.nax/scratchpad/` holds this session's
+ * spill files (US-003).
+ *
+ * Recorded from the session's `workdir` at open — the same root the coding
+ * tools are confined to — so a spilled body is reachable through
+ * `ScratchpadRead` with the relative path the truncation marker names. Same
+ * lifecycle as the maps above: set on open, cleared on close.
+ */
+export const nativeSessionScratchpadRoots = new Map();
+/**
+ * Session name -> timeoutSeconds, so sendTurn can bound each `complete()`
+ * call with a deadline (whole-branch review finding 4). Same lifecycle as
+ * `nativeTranscriptDirs` — populated on open, cleared on close only.
+ */
+export const nativeSessionTimeouts = new Map();
+/**
+ * Session name -> the runtime hooks handed to openSession. SessionManager
+ * passes both (manager.ts, openSession) and the native adapter previously
+ * ignored them, which is why the idle watchdog never covered native. Same
+ * lifecycle as `nativeTranscriptDirs`: set on open, cleared on close only.
+ */
+export const nativeSessionStreamHooks = new Map();
+/**
+ * Session names whose most recent turn failed.
+ *
+ * `AgentAdapter.closeSession(handle)` carries no failure signal, so the close
+ * cannot tell a finished session from a broken one and passed `failed: false`
+ * for both -- deleting the transcript of exactly the session whose history the
+ * retry needs and a human would read (nax#1838). Rather than widen the adapter
+ * interface for one transport, the turn records what it knows here and the
+ * close reads it. Same lifecycle as the maps above: written per turn, cleared
+ * on close.
+ *
+ * A later successful turn clears the mark. "Failed" describes the session's
+ * current state, not whether it ever stumbled -- a session that recovered and
+ * finished is still cleaned up.
+ */
+export const nativeSessionFailed = new Set();
+/**
+ * Session name -> the identity that owns this session's transcript (nax#1877).
+ *
+ * Read by `runNativeTurn` on both the load and the save, so a transcript left
+ * behind by an abandoned invocation of the same deterministic session name is
+ * recognised as foreign rather than silently resumed. Same lifecycle as the
+ * maps above: set on open, cleared on close.
+ */
+export const nativeSessionTranscriptOwners = new Map();
+/** Session name -> resolved compaction settings. Same lifecycle as the maps above. */
+export const nativeSessionCompaction = new Map();
+/**
+ * Session name -> resolved transport-fault retry settings (nax#1870). Same
+ * lifecycle as the maps above: set on open, cleared on close.
+ */
+export const nativeSessionTransportRetry = new Map();
+/**
+ * Session name -> live `SpinBreaker` instance (nax#2013, lifetime extended in
+ * nax#2047). Constructed once at open so the cumulative counter survives
+ * across `runNativeTurn` calls — a fix round that opens a new turn on the
+ * same `handle.id` must inherit the prior turn's evidence rather than start
+ * fresh. Same lifecycle as `nativeSessionTransportRetry`: set on open, cleared
+ * on close.
+ */
+export const nativeSessionSpinBreaker = new Map();
+export const nativeSessionLastUsage = new Map();
+/**
+ * The persisted anchor a turn on `model` may use. Prefix stability is a
+ * property of (model, prefix) (P3 spec 3.3): an anchor measured under a
+ * different model indexes history the transcript store refused (spec 8.3(c)),
+ * so it is dropped here rather than mis-sizing the next compaction decision.
+ * An entry or a turn with no model makes no claim — the store's own rule.
+ */
+export function sessionAnchorFor(sessionName, model) {
+    const entry = nativeSessionLastUsage.get(sessionName);
+    if (entry?.model === undefined || model === undefined || entry.model === model)
+        return entry;
+    nativeSessionLastUsage.delete(sessionName);
+    return undefined;
+}
+/** Records how the session's latest turn ended, for `closeNativeSession`. */
+export function markNativeTurnOutcome(sessionName, failed) {
+    if (failed)
+        nativeSessionFailed.add(sessionName);
+    else
+        nativeSessionFailed.delete(sessionName);
+}
+export async function openNativeSession(name, opts) {
+    // Never defaulted. An adapter that picks its own path writes a transcript
+    // somewhere nobody looks, which is #1794's empty-packageDir bug one layer up.
+    if (!opts.transcriptDir) {
+        throw new NaxError(`native session "${name}" opened without a transcriptDir`, "NATIVE_TRANSCRIPT_DIR_MISSING", {
+            stage: "native-session",
+        });
+    }
+    nativeTranscriptDirs.set(name, opts.transcriptDir);
+    nativeSessionTimeouts.set(name, opts.timeoutSeconds);
+    nativeSessionScratchpadRoots.set(name, opts.workdir);
+    if (opts.transcriptOwner !== undefined)
+        nativeSessionTranscriptOwners.set(name, opts.transcriptOwner);
+    else
+        nativeSessionTranscriptOwners.delete(name);
+    // `resume` is SessionManager's "this name already has a descriptor in this
+    // process" signal, and it had no consumer on this transport (nax#1877) — a
+    // native session resumed whatever transcript happened to be on disk. Honouring
+    // it here is the flag's documented contract; the owner check in loadTranscript
+    // is what covers the cases `resume` cannot see (a same-process re-entry into a
+    // stage, and a process that died without closing anything).
+    if (opts.resume !== true)
+        await deleteTranscript(opts.transcriptDir, name);
+    if (opts.compaction !== undefined)
+        nativeSessionCompaction.set(name, opts.compaction);
+    if (opts.transportRetry !== undefined)
+        nativeSessionTransportRetry.set(name, opts.transportRetry);
+    if (opts.spinBreaker !== undefined)
+        nativeSessionSpinBreaker.set(name, createSpinBreaker(opts.spinBreaker));
+    nativeSessionStreamHooks.set(name, {
+        ...(opts.onStreamActivity !== undefined ? { onStreamActivity: opts.onStreamActivity } : {}),
+        ...(opts.onActiveCall !== undefined ? { onActiveCall: opts.onActiveCall } : {}),
+    });
+    return {
+        id: name,
+        agentName: NATIVE_AGENT,
+        // Both fields carry the same value on purpose. On ACP they differ because a
+        // physical session can be re-established under a stable logical record;
+        // native has no reconnect, so its logical and physical identity genuinely
+        // coincide. `nativeSessionId` is a pure hash of the name and deliberately
+        // not memoised, so this is exactly the id `sendTurn` later puts on the wire.
+        protocolIds: { recordId: nativeSessionId(name), sessionId: nativeSessionId(name) },
+        ...(opts.modelDef !== undefined ? { modelDef: opts.modelDef } : {}),
+        ...(opts.modelTier !== undefined ? { modelTier: opts.modelTier } : {}),
+    };
+}
+/**
+ * Clear every module-level entry for one session name.
+ *
+ * Extracted so both close paths share one source of truth. `closeNativeSession`
+ * has a `SessionHandle`; the adapter's `closePhysicalSession` gets only the
+ * handle string that run teardown carries (`descriptor.handle`). The two are
+ * the same string — every map is keyed by the session name, and `SessionHandle.id`
+ * is that name — but the signatures are not interchangeable, so this helper is
+ * string-keyed rather than reconstructed into a synthetic handle.
+ */
+export function clearNativeSessionState(sessionName) {
+    nativeTranscriptDirs.delete(sessionName);
+    nativeSessionTimeouts.delete(sessionName);
+    nativeSessionScratchpadRoots.delete(sessionName);
+    nativeSessionTranscriptOwners.delete(sessionName);
+    nativeSessionStreamHooks.delete(sessionName);
+    nativeSessionFailed.delete(sessionName);
+    nativeSessionCompaction.delete(sessionName);
+    nativeSessionTransportRetry.delete(sessionName);
+    nativeSessionSpinBreaker.delete(sessionName);
+    nativeSessionLastUsage.delete(sessionName);
+}
+/**
+ * Kept on failure, deleted on success. Every Phase B op is lifetime "fresh", so
+ * the transcript survives exactly when it is worth reading. The kept-on-failure
+ * set is otherwise unbounded, so a failed close also prunes the feature's
+ * `sessions/` directory down to `MAX_RETAINED_TRANSCRIPTS` (ADR-028 section 3).
+ */
+export async function closeNativeSession(handle, failed) {
+    const dir = nativeTranscriptDirs.get(handle.id);
+    // An explicit argument wins; otherwise the last turn's own verdict decides.
+    // The adapter passes nothing, because its interface has no failure signal.
+    const treatAsFailed = failed ?? nativeSessionFailed.has(handle.id);
+    try {
+        if (dir !== undefined) {
+            if (treatAsFailed) {
+                // Retain for a human, out of reach of the next session of this name.
+                await retainTranscript(dir, handle.id);
+                await pruneRetainedTranscripts(dir);
+            }
+            else {
+                await deleteTranscript(dir, handle.id);
+            }
+        }
+    }
+    finally {
+        // The deletes must run even when the transcript I/O throws: a failed
+        // cleanup step is no reason to strand the session's other state.
+        clearNativeSessionState(handle.id);
+    }
+}

package/dist/native/session/tool-input-exemplar.d.ts

@@ -0,0 +1,2 @@
+import type { ToolInputViolation } from "./tool-input-validation.ts";
+export declare function exemplarFor(schema: unknown, input: Record<string, unknown>, violation: ToolInputViolation): Record<string, unknown>;

package/dist/native/session/tool-input-exemplar.js

@@ -0,0 +1,66 @@
+export function exemplarFor(schema, input, violation) {
+    const exemplar = { ...input };
+    // Defensive: validateToolInput never currently emits "" (every violation
+    // names the offending property), but ToolInputViolation.property is typed
+    // as `string`, not a non-empty literal, so a synthetic or future
+    // top-level violation with no single property to correct must still be
+    // handled -- return the input verbatim rather than writing to an empty key.
+    if (violation.property === "") {
+        return exemplar;
+    }
+    if (!isPlainObject(schema))
+        return exemplar;
+    const properties = schema.properties;
+    if (!isPlainObject(properties))
+        return exemplar;
+    const propSchema = properties[violation.property];
+    if (!isPlainObject(propSchema)) {
+        exemplar[violation.property] = "<FILL IN>";
+        return exemplar;
+    }
+    const propType = propSchema.type;
+    // Enum first (nax#2200): `{type: "string", enum: [...]}` is the common
+    // spelling, and a `<FILL IN>` placeholder there violates the very enum the
+    // exemplar is meant to demonstrate. The first member is a valid value.
+    if (Array.isArray(propSchema.enum) && propSchema.enum.length > 0 && propSchema.enum.every(isString)) {
+        exemplar[violation.property] = propSchema.enum[0];
+    }
+    else if (propType === "string") {
+        exemplar[violation.property] = `<FILL IN: ${violation.property}>`;
+    }
+    else if (propType === "number" || propType === "integer") {
+        exemplar[violation.property] = 0;
+    }
+    else if (propType === "boolean") {
+        exemplar[violation.property] = false;
+    }
+    else if (propType === "null") {
+        exemplar[violation.property] = null;
+    }
+    else if (propType === "array") {
+        exemplar[violation.property] = [`<FILL IN: ${violation.property}>`];
+    }
+    else if (propType === "object") {
+        const subProperties = propSchema.properties;
+        if (isPlainObject(subProperties)) {
+            const subExemplar = {};
+            for (const key of Object.keys(subProperties)) {
+                subExemplar[key] = "<FILL IN>";
+            }
+            exemplar[violation.property] = subExemplar;
+        }
+        else {
+            exemplar[violation.property] = { "<FILL IN>": "<FILL IN>" };
+        }
+    }
+    else {
+        exemplar[violation.property] = "<FILL IN>";
+    }
+    return exemplar;
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/native/session/tool-input-validation.d.ts

@@ -0,0 +1,15 @@
+export interface ToolInputViolation {
+    readonly property: string;
+    readonly expected: string;
+    readonly actual: string;
+    readonly message: string;
+}
+export declare function validateToolInput(schema: unknown, input: unknown): ToolInputViolation | undefined;
+/**
+ * The input with every `null`-valued optional property removed, or `undefined`
+ * when there is nothing to remove (including any schema the validator does not
+ * understand — the same fail-open contract). A property whose own schema
+ * declares `type: "null"` keeps its value: there `null` IS the supplied value.
+ * Never mutates `input`.
+ */
+export declare function stripNullOptionals(schema: unknown, input: unknown): Record<string, unknown> | undefined;

package/dist/native/session/tool-input-validation.js

@@ -0,0 +1,146 @@
+/**
+ * Fail-open subset validator for tool inputs (nax#2047).
+ *
+ * The model returned RunCommand calls with `values:""` 69 times and
+ * `values:"\t"` 13 times in a row -- the empty string produced no rejected
+ * keys, the tab became the key "0", and neither message ever named "values"
+ * itself as the wrong type, so the loop could not break. This validator
+ * catches that shape at the transport boundary so a malformed input never
+ * persists in the transcript.
+ *
+ * The contract is a strict subset of JSON Schema on purpose: type, enum,
+ * required, and a `properties` object. Anything we cannot decide -- unknown
+ * keywords such as `anyOf`, a missing or non-object schema, extra properties
+ * with no `additionalProperties` -- returns `undefined` (allow), so this
+ * validator never breaks a tool that was previously passing.
+ *
+ * `null` on a property the schema does not list as `required` is treated as
+ * absent (nax#2200). The tools already read it that way (`Git` treats a
+ * non-array `refs` as `[]`), and models routinely spell "not supplied" as
+ * `null`; rejecting it made the gate stricter than the tools it guards, and a
+ * verifier that sent `refs: null` three times lost its turn to the budget.
+ * `stripNullOptionals` removes those properties so the handler sees the same
+ * "absent" the validator judged.
+ */
+import { describeValuesType } from "#src/internal/describe-value-type";
+export function validateToolInput(schema, input) {
+    if (!isPlainObject(schema))
+        return undefined;
+    const { properties, required, type } = schema;
+    if (!isPlainObject(properties))
+        return undefined;
+    if (type !== undefined && type !== "object")
+        return undefined;
+    if (!isPlainObject(input))
+        return undefined;
+    const requiredKeys = requiredSet(required);
+    for (const entry of requiredKeys) {
+        if (!(entry in input)) {
+            return {
+                property: entry,
+                expected: "present",
+                actual: "absent",
+                message: `\`${entry}\` is required`,
+            };
+        }
+    }
+    for (const key of Object.keys(input)) {
+        const propSchema = properties[key];
+        if (!isPlainObject(propSchema))
+            continue;
+        const value = input[key];
+        // nax#2200: `null` on an optional property reads as "not supplied".
+        if (value === null && !requiredKeys.has(key))
+            continue;
+        if (typeof propSchema.type === "string" && PRIMITIVE_TYPES.has(propSchema.type)) {
+            if (!typeMatches(propSchema.type, value)) {
+                const expected = propSchema.type;
+                const actual = describeValuesType(value);
+                return {
+                    property: key,
+                    expected,
+                    actual,
+                    message: `\`${key}\` expected ${expected}, got ${actual}`,
+                };
+            }
+        }
+        const enumSchema = propSchema.enum;
+        if (Array.isArray(enumSchema) && enumSchema.every((m) => typeof m === "string")) {
+            if (!enumSchema.includes(value)) {
+                const expected = `one of: ${enumSchema.join(", ")}`;
+                const actual = describeValuesType(value);
+                return {
+                    property: key,
+                    expected,
+                    actual,
+                    message: `\`${key}\` must be ${expected} (got ${actual})`,
+                };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * The input with every `null`-valued optional property removed, or `undefined`
+ * when there is nothing to remove (including any schema the validator does not
+ * understand — the same fail-open contract). A property whose own schema
+ * declares `type: "null"` keeps its value: there `null` IS the supplied value.
+ * Never mutates `input`.
+ */
+export function stripNullOptionals(schema, input) {
+    if (!isPlainObject(schema) || !isPlainObject(input))
+        return undefined;
+    const { properties, required, type } = schema;
+    if (!isPlainObject(properties))
+        return undefined;
+    if (type !== undefined && type !== "object")
+        return undefined;
+    const requiredKeys = requiredSet(required);
+    const stripped = Object.keys(input).filter((key) => {
+        const propSchema = properties[key];
+        if (input[key] !== null || requiredKeys.has(key) || !isPlainObject(propSchema))
+            return false;
+        return propSchema.type !== "null";
+    });
+    if (stripped.length === 0)
+        return undefined;
+    const drop = new Set(stripped);
+    return Object.fromEntries(Object.entries(input).filter(([key]) => !drop.has(key)));
+}
+function requiredSet(required) {
+    if (!Array.isArray(required))
+        return new Set();
+    return new Set(required.filter((entry) => typeof entry === "string"));
+}
+const PRIMITIVE_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+    "null",
+    "object",
+]);
+function typeMatches(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "null":
+            return value === null;
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return true;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/native/session/tool-mapping.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ToolDescriptor -> ToolDefinition.
+ *
+ * Nearly one-to-one. The budget fields stay behind deliberately: nax executes
+ * these tools, so `maxCallsPerSession` and `maxTokensPerCall` are enforced by
+ * PullToolBudget on this side and mean nothing to a provider.
+ */
+import type { ToolDefinition } from "@nathapp/nax-ai";
+import type { ToolDescriptor } from "#src/session/tool-descriptor";
+import type { CodingTool } from "#src/tools/index";
+export declare function toToolDefinitions(descriptors: readonly ToolDescriptor[]): ToolDefinition[];
+/**
+ * CodingTool -> ToolDefinition.
+ *
+ * `scope` and `run` stay behind for the same reason the pull tools' budget
+ * fields do: nax executes these, so they mean nothing to a provider.
+ */
+export declare function codingToolsToDefinitions(tools: readonly CodingTool[]): ToolDefinition[];

package/dist/native/session/tool-mapping.js

@@ -0,0 +1,27 @@
+/**
+ * ToolDescriptor -> ToolDefinition.
+ *
+ * Nearly one-to-one. The budget fields stay behind deliberately: nax executes
+ * these tools, so `maxCallsPerSession` and `maxTokensPerCall` are enforced by
+ * PullToolBudget on this side and mean nothing to a provider.
+ */
+export function toToolDefinitions(descriptors) {
+    return descriptors.map((d) => ({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+    }));
+}
+/**
+ * CodingTool -> ToolDefinition.
+ *
+ * `scope` and `run` stay behind for the same reason the pull tools' budget
+ * fields do: nax executes these, so they mean nothing to a provider.
+ */
+export function codingToolsToDefinitions(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    }));
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The one place a native `tool-result` message is constructed.
+ *
+ * The result used to be appended at seven separate sites in `turn-loop.ts`, so
+ * there was no single point at which a policy could be applied even if one
+ * existed, and invariants like "`toolCallId` is always set" were re-asserted by
+ * hand at each. Every site now builds its message here.
+ *
+ * That chokepoint is also what makes `after_tool` safe by construction
+ * (nax#2151): the event shapes a result BEFORE it enters the message array, so
+ * no handler can rewrite history and re-bill the prefix-cached prompt. The four
+ * synthetic sites — where no tool ran — use this builder without firing the
+ * event; the three genuine sites use both.
+ */
+/**
+ * A refusal the model is meant to act on. Structural (ADR-029 s5), never a
+ * string convention: `{ answer }` alone cannot distinguish "refused, and here
+ * is why" from "here is your file".
+ */
+export interface DenialInfo {
+    readonly reason: string;
+    readonly breach: boolean;
+}
+export interface ToolResultMessage {
+    readonly role: "tool-result";
+    readonly toolCallId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+    readonly denied?: DenialInfo;
+}
+export interface BuildToolResultArgs {
+    readonly toolCallId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+    readonly denied?: DenialInfo;
+}
+export declare function buildToolResult(args: BuildToolResultArgs): ToolResultMessage;

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

@@ -0,0 +1,25 @@
+/**
+ * The one place a native `tool-result` message is constructed.
+ *
+ * The result used to be appended at seven separate sites in `turn-loop.ts`, so
+ * there was no single point at which a policy could be applied even if one
+ * existed, and invariants like "`toolCallId` is always set" were re-asserted by
+ * hand at each. Every site now builds its message here.
+ *
+ * That chokepoint is also what makes `after_tool` safe by construction
+ * (nax#2151): the event shapes a result BEFORE it enters the message array, so
+ * no handler can rewrite history and re-bill the prefix-cached prompt. The four
+ * synthetic sites — where no tool ran — use this builder without firing the
+ * event; the three genuine sites use both.
+ */
+export function buildToolResult(args) {
+    return {
+        role: "tool-result",
+        toolCallId: args.toolCallId,
+        content: args.content,
+        // Absent stays absent: a clean result must not carry an `isError: undefined`
+        // key, so the field is spread in only when it has a value.
+        ...(args.isError === undefined ? {} : { isError: args.isError }),
+        ...(args.denied === undefined ? {} : { denied: args.denied }),
+    };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * 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 type { ConversationMessage } from "@nathapp/nax-ai";
+export declare function transcriptPath(dir: string, sessionName: string): string;
+/**
+ * Who may resume a transcript. `owner` is the op invocation (nax#1877); `model`
+ * is the native model that wrote it (nax#2150, P3 spec 8.3). A field the caller
+ * leaves undefined makes no claim, so non-op callers and tests read whatever is
+ * there.
+ */
+export interface TranscriptIdentity {
+    readonly owner?: string;
+    readonly model?: string;
+}
+/**
+ * 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 declare function transcriptModelIdentity(rawModel: string | undefined): string | undefined;
+/**
+ * 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 declare function loadTranscript(dir: string, sessionName: string, identity?: TranscriptIdentity): Promise<ConversationMessage[]>;
+export declare function saveTranscript(dir: string, sessionName: string, messages: readonly ConversationMessage[], identity?: TranscriptIdentity): Promise<void>;
+/**
+ * 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 declare function retainTranscript(dir: string, sessionName: string): Promise<void>;
+export declare function deleteTranscript(dir: string, sessionName: string): Promise<void>;
+/**
+ * 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 declare const MAX_RETAINED_TRANSCRIPTS = 50;
+/**
+ * Reset the one-shot truncation-warning flag (for testing only).
+ * @internal
+ */
+export declare function _resetTranscriptTruncationWarningForTests(): void;
+/**
+ * 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 declare function pruneRetainedTranscripts(dir: string, maxRetained?: number): Promise<number>;