@nathapp/nax-agent 0.1.0

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

@@ -0,0 +1,73 @@
+/**
+ * The handlers the seam carries today (nax#2151, US-002, US-003). Installed in
+ * order: the two built-in `before_tool` handlers — invalid-call repair and the
+ * spin breaker — then every plugin entry the turn supplied, then the built-in
+ * `after_tool` truncation. The first two were inline branches in `turn-loop.ts`
+ * before the seam; they are ordinary registrations now, and the order they
+ * register in is the order the loop consulted them before.
+ *
+ * The plugin entries sit BETWEEN the built-ins on purpose (US-003): a call the
+ * repair already blocked or the breaker already terminated never reaches a
+ * plugin handler (`dispatchBeforeTool` returns on the first block/terminate),
+ * while a plugin `before_tool` handler still judges the call the tool would
+ * actually receive, after null-optional repair. Truncation registers LAST among
+ * `after_tool` handlers, which is the position the loop's hardcoded call held:
+ * it shapes whatever the plugin `after_tool` entries produced, before the
+ * result is built.
+ *
+ * All of them are PER-TURN — the invalid-call budget, the spin reprieve, the
+ * plugin set with its context and signal, and the session whose spill root
+ * truncation resolves all reset or are re-supplied with the turn — but they are
+ * installed ONCE per registry, with the per-turn state swapped underneath them.
+ * Registering a fresh set every turn would accumulate handlers on a registry a
+ * caller reuses across turns, each set still closing over the turn that created
+ * it: a later turn would be judged by an earlier turn's budget, the shared
+ * breaker would be advanced once per installed pair — halving every threshold
+ * it is supposed to enforce — and a plugin handler would run once per turn
+ * installed instead of once per dispatch.
+ *
+ * The wrapped plugin entries read the current turn through `state` rather than
+ * from whatever was in scope at install time, so a repointed registry hands
+ * them the new context and the new signal.
+ */
+import { type SpinBreaker } from "#src/infra/spin-breaker/index";
+import { type InvalidCallBudget } from "./handle-invalid-tool-call.ts";
+import { type LoopEventRegistry, type LoopHandlerContext, type LoopHandlerSet } from "./loop-events/index.ts";
+export interface BuiltinLoopHandlerDeps {
+    /**
+     * The session the handlers run for. Truncation resolves its spill root
+     * against it; read through `state.current` at dispatch like every other
+     * per-turn dep, so a repointed registry never keeps a stale session.
+     */
+    readonly sessionName: string;
+    /** Per-turn invalid-call budget. The loop reads `exceeded` for the halt. */
+    readonly budget: InvalidCallBudget;
+    /** Absent disables the breaker, exactly as `TurnDeps.spinBreaker` does. */
+    readonly spinBreaker?: SpinBreaker;
+    /**
+     * Called when the breaker stops the batch (nax#2120). The loop spends one
+     * terminal round trip on that stop, so it is the loop — not the handler —
+     * that records what the stop means for the turn.
+     */
+    readonly onSpinStop: () => void;
+    /**
+     * The run's plugin-contributed handlers (US-003), staged by
+     * `PluginRegistry.getLoopHandlers()` and forwarded per turn by the adapter.
+     * Absent or empty is the normal case: the built-ins are then the whole
+     * chain.
+     */
+    readonly loopHandlers?: LoopHandlerSet;
+    /**
+     * The read-only facts a plugin handler is handed at dispatch. Read through
+     * `state.current` like every other per-turn dep, so a repointed registry
+     * never keeps an earlier turn's context.
+     */
+    readonly loopHandlerContext?: LoopHandlerContext;
+    /**
+     * The turn's abort signal (US-003), handed to each wrapped plugin entry so
+     * an abort lands on a pending plugin handler. Read-only: a plugin handler
+     * gets no way to abort the turn.
+     */
+    readonly signal?: AbortSignal;
+}
+export declare function registerBuiltinLoopHandlers(registry: LoopEventRegistry, deps: BuiltinLoopHandlerDeps): void;

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

@@ -0,0 +1,137 @@
+/**
+ * The handlers the seam carries today (nax#2151, US-002, US-003). Installed in
+ * order: the two built-in `before_tool` handlers — invalid-call repair and the
+ * spin breaker — then every plugin entry the turn supplied, then the built-in
+ * `after_tool` truncation. The first two were inline branches in `turn-loop.ts`
+ * before the seam; they are ordinary registrations now, and the order they
+ * register in is the order the loop consulted them before.
+ *
+ * The plugin entries sit BETWEEN the built-ins on purpose (US-003): a call the
+ * repair already blocked or the breaker already terminated never reaches a
+ * plugin handler (`dispatchBeforeTool` returns on the first block/terminate),
+ * while a plugin `before_tool` handler still judges the call the tool would
+ * actually receive, after null-optional repair. Truncation registers LAST among
+ * `after_tool` handlers, which is the position the loop's hardcoded call held:
+ * it shapes whatever the plugin `after_tool` entries produced, before the
+ * result is built.
+ *
+ * All of them are PER-TURN — the invalid-call budget, the spin reprieve, the
+ * plugin set with its context and signal, and the session whose spill root
+ * truncation resolves all reset or are re-supplied with the turn — but they are
+ * installed ONCE per registry, with the per-turn state swapped underneath them.
+ * Registering a fresh set every turn would accumulate handlers on a registry a
+ * caller reuses across turns, each set still closing over the turn that created
+ * it: a later turn would be judged by an earlier turn's budget, the shared
+ * breaker would be advanced once per installed pair — halving every threshold
+ * it is supposed to enforce — and a plugin handler would run once per turn
+ * installed instead of once per dispatch.
+ *
+ * The wrapped plugin entries read the current turn through `state` rather than
+ * from whatever was in scope at install time, so a repointed registry hands
+ * them the new context and the new signal.
+ */
+import { spinTerminalNotice } from "#src/infra/spin-breaker/index";
+import { normalizeNullOptionals } from "./handle-invalid-tool-call.js";
+import { wrapExternalHandler, } from "./loop-events/index.js";
+import { createTruncationHandler } from "./truncation-handler.js";
+/** A signal that is never aborted, standing in when a turn supplied none. */
+const NEVER_ABORTED = new AbortController().signal;
+/**
+ * The context handed to a plugin handler. A caller that supplies handlers is
+ * expected to supply the context with them, but a handler must never be handed
+ * `undefined`: the fact it scopes itself by is the session's own name, which
+ * nax always knows.
+ */
+function contextFor(state) {
+    return state.current.loopHandlerContext ?? { sessionName: state.current.sessionName };
+}
+/**
+ * A live view of the turn's signal. The wrapped plugin entries are installed
+ * once per registry, while the signal is repointed with the rest of the
+ * per-turn state, so the view reads `state.current.signal` when the wrapper
+ * subscribes instead of capturing whatever was in scope at install time.
+ *
+ * `raceSettlement` subscribes and unsubscribes and nothing else, so those two
+ * methods are the whole surface this view has to answer.
+ */
+function turnSignalView(state) {
+    const current = () => state.current.signal ?? NEVER_ABORTED;
+    return {
+        addEventListener: (...args) => current().addEventListener(...args),
+        removeEventListener: (...args) => current().removeEventListener(...args),
+    };
+}
+/**
+ * One entry per registry the built-ins are installed on, so a second call for
+ * the same registry is a repoint rather than a second pair. Weak, so the
+ * loop's own per-turn registry takes its state with it when the turn ends.
+ */
+const turnStateByRegistry = new WeakMap();
+export function registerBuiltinLoopHandlers(registry, deps) {
+    const installed = turnStateByRegistry.get(registry);
+    if (installed !== undefined) {
+        installed.current = deps;
+        return;
+    }
+    const state = { current: deps };
+    turnStateByRegistry.set(registry, state);
+    // Registered first, which is the pre-seam order: a malformed call is refused
+    // before the spin breaker counts it. The empty string produced no rejected
+    // keys, so counting a malformed call as spin evidence is how nax#2047's 69
+    // identical bad calls stayed invisible.
+    registry.register("before_tool", ({ call, tools }) => repairInvalidCall(state, call, tools));
+    registry.register("before_tool", ({ call }) => observeSpin(state, call));
+    // US-003: the plugin entries go between the built-in pair above and the
+    // built-in truncation below, so a call a built-in already refused is never
+    // offered to a plugin — `dispatchBeforeTool` returns on the first
+    // block/terminate — while a plugin `before_tool` handler still judges the
+    // repaired call. Each handler and its context are read through `state`, so
+    // the entries installed here are the same ones a repointed registry
+    // dispatches, with the turn's own facts.
+    for (const entry of deps.loopHandlers ?? []) {
+        registry.register(entry.event, wrapExternalHandler(entry, () => contextFor(state), turnSignalView(state)));
+    }
+    // Registered LAST among after_tool handlers, which is the pre-seam position:
+    // the loop's hardcoded truncation call ran after the dispatcher, so it shaped
+    // whatever the handlers produced. The handler is rebuilt per dispatch so the
+    // session name is read through `state.current` — the same lifetime the other
+    // per-turn deps use — rather than frozen at install time.
+    registry.register("after_tool", (payload) => createTruncationHandler(state.current.sessionName)(payload));
+}
+function repairInvalidCall(state, call, tools) {
+    const invalid = state.current.budget.observe(call, tools);
+    if (invalid === undefined) {
+        // nax#2200: a `null` optional property validated as absent, so the tool
+        // must receive it absent too — the rewrite is what the loop runs and
+        // records. No `null` to drop leaves the success path untouched.
+        const normalized = normalizeNullOptionals(call, tools);
+        return normalized === undefined ? { kind: "allow" } : { kind: "allow", input: normalized };
+    }
+    if (invalid.kind === "stopped") {
+        // A tripped budget ends the batch with NO tool-result — "a result nobody
+        // reads only grows the transcript" (nax#2047 Task 4). None of the four
+        // outcome kinds can express that (each of them answers the call), so the
+        // loop reads the halt from `budget.exceeded` and breaks before applying
+        // this outcome.
+        return { kind: "allow" };
+    }
+    // Repaired, not executed: the loop records the model's input minus the
+    // rejected property on the assistant message, and answers with the error
+    // text, which carries the exemplar (nax#2200).
+    return { kind: "block", content: invalid.content, isError: true, input: invalid.input };
+}
+function observeSpin(state, call) {
+    const { budget, spinBreaker, onSpinStop } = state.current;
+    // The budget halt wins: the turn ends without executing this call, so
+    // letting the breaker count it would record a call that never ran.
+    if (budget.exceeded)
+        return { kind: "allow" };
+    const verdict = spinBreaker?.observe(call.name, call.input) ?? { action: "allow" };
+    if (verdict.action === "stop") {
+        onSpinStop();
+        return { kind: "terminate", content: spinTerminalNotice(verdict.reason), isError: true };
+    }
+    if (verdict.action === "nudge")
+        return { kind: "nudge", text: verdict.text };
+    return { kind: "allow" };
+}

package/dist/native/session/nudge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The spin-breaker nudge's text composition and its cost against the
+ * model-facing byte ceiling.
+ *
+ * These live together because they are one decision seen from two sides: how
+ * the nudge is joined to a tool result, and how many bytes that join spends.
+ * `truncateNativeToolResult` reserves what `nudgeOverheadBytes` reports so the
+ * prefix fits INSIDE `MODEL_MAX_BYTES` instead of pushing the result past it —
+ * splitting the two across modules is what lets the separator change without
+ * the reservation following it.
+ */
+/**
+ * `nudge` prefixes the eventual result rather than replacing it: the model
+ * needs the real output to act on, plus the notice that it is repeating itself
+ * (nax#2120). The handler's text leads, because a handler that says "begin with
+ * this" must be able to.
+ */
+export declare function withNudge(nudgeText: string | undefined, content: string): string;
+/**
+ * What `withNudge` will add, in the bytes the ceiling is measured in. The
+ * truncation chokepoint reserves this so the prefix fits inside
+ * `MODEL_MAX_BYTES` rather than on top of it.
+ *
+ * The nudge text is harness-authored and short by construction (`nudgeText()`
+ * in src/runtime/spin-breaker), so the reservation never consumes the whole
+ * budget in practice; `truncateNativeToolResult` floors the remainder at zero
+ * regardless.
+ */
+export declare function nudgeOverheadBytes(nudgeText: string): number;

package/dist/native/session/nudge.js

@@ -0,0 +1,35 @@
+/**
+ * The spin-breaker nudge's text composition and its cost against the
+ * model-facing byte ceiling.
+ *
+ * These live together because they are one decision seen from two sides: how
+ * the nudge is joined to a tool result, and how many bytes that join spends.
+ * `truncateNativeToolResult` reserves what `nudgeOverheadBytes` reports so the
+ * prefix fits INSIDE `MODEL_MAX_BYTES` instead of pushing the result past it —
+ * splitting the two across modules is what lets the separator change without
+ * the reservation following it.
+ */
+/** Joins the nudge to the result it prefixes. Counted by `nudgeOverheadBytes`. */
+const NUDGE_SEPARATOR = "\n\n---\n\n";
+/**
+ * `nudge` prefixes the eventual result rather than replacing it: the model
+ * needs the real output to act on, plus the notice that it is repeating itself
+ * (nax#2120). The handler's text leads, because a handler that says "begin with
+ * this" must be able to.
+ */
+export function withNudge(nudgeText, content) {
+    return nudgeText === undefined ? content : `${nudgeText}${NUDGE_SEPARATOR}${content}`;
+}
+/**
+ * What `withNudge` will add, in the bytes the ceiling is measured in. The
+ * truncation chokepoint reserves this so the prefix fits inside
+ * `MODEL_MAX_BYTES` rather than on top of it.
+ *
+ * The nudge text is harness-authored and short by construction (`nudgeText()`
+ * in src/runtime/spin-breaker), so the reservation never consumes the whole
+ * budget in practice; `truncateNativeToolResult` floors the remainder at zero
+ * regardless.
+ */
+export function nudgeOverheadBytes(nudgeText) {
+    return Buffer.byteLength(nudgeText, "utf8") + Buffer.byteLength(NUDGE_SEPARATOR, "utf8");
+}

package/dist/native/session/rate-provenance.d.ts

@@ -0,0 +1,17 @@
+import type { PricingRates, TokenUsage } from "#src/cost/standard-types";
+interface RateTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    inputCostPerMillionTokens: number;
+    outputCostPerMillionTokens: number;
+    cacheReadCostPerMillionTokens: number;
+    cacheCreationCostPerMillionTokens: number;
+    latestRates?: PricingRates;
+    complete: boolean;
+}
+export declare function createRateTotals(): RateTotals;
+export declare function addRateTotals(totals: RateTotals, usage: TokenUsage, rates: PricingRates | undefined): void;
+export declare function aggregateRates(totals: RateTotals): PricingRates | undefined;
+export {};

package/dist/native/session/rate-provenance.js

@@ -0,0 +1,39 @@
+export function createRateTotals() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        inputCostPerMillionTokens: 0,
+        outputCostPerMillionTokens: 0,
+        cacheReadCostPerMillionTokens: 0,
+        cacheCreationCostPerMillionTokens: 0,
+        complete: true,
+    };
+}
+export function addRateTotals(totals, usage, rates) {
+    if (rates === undefined) {
+        totals.complete = false;
+        return;
+    }
+    totals.inputTokens += usage.inputTokens;
+    totals.outputTokens += usage.outputTokens;
+    totals.cacheReadTokens += usage.cacheReadTokens ?? 0;
+    totals.cacheCreationTokens += usage.cacheWriteTokens ?? 0;
+    totals.inputCostPerMillionTokens += usage.inputTokens * rates.input;
+    totals.outputCostPerMillionTokens += usage.outputTokens * rates.output;
+    totals.cacheReadCostPerMillionTokens += (usage.cacheReadTokens ?? 0) * rates.cacheRead;
+    totals.cacheCreationCostPerMillionTokens += (usage.cacheWriteTokens ?? 0) * rates.cacheWrite;
+    totals.latestRates = rates;
+}
+export function aggregateRates(totals) {
+    if (!totals.complete || totals.latestRates === undefined)
+        return undefined;
+    const weightedRate = (tokens, rateTotal, fallback) => tokens === 0 ? fallback : rateTotal / tokens;
+    return {
+        input: weightedRate(totals.inputTokens, totals.inputCostPerMillionTokens, totals.latestRates.input),
+        output: weightedRate(totals.outputTokens, totals.outputCostPerMillionTokens, totals.latestRates.output),
+        cacheRead: weightedRate(totals.cacheReadTokens, totals.cacheReadCostPerMillionTokens, totals.latestRates.cacheRead),
+        cacheWrite: weightedRate(totals.cacheCreationTokens, totals.cacheCreationCostPerMillionTokens, totals.latestRates.cacheWrite),
+    };
+}

package/dist/native/session/session.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 { type SpinBreaker } from "#src/infra/spin-breaker/index";
+import type { AgentStreamEvent } from "#src/session/agent-stream-events";
+import type { OpenSessionOpts, SessionHandle } from "#src/session/session-types";
+import type { ResolvedCompaction } from "./compaction.ts";
+import type { TurnRetryConfig } from "./turn-retry.ts";
+/**
+ * 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 declare const nativeTranscriptDirs: Map<string, string>;
+/**
+ * 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 declare const nativeSessionScratchpadRoots: Map<string, string>;
+/**
+ * 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 declare const nativeSessionTimeouts: Map<string, number>;
+/**
+ * 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 declare const nativeSessionStreamHooks: Map<string, {
+    onStreamActivity?: (event: AgentStreamEvent) => void;
+    onActiveCall?: (callId: string, cancel: () => Promise<void>) => void;
+}>;
+/**
+ * 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 declare const nativeSessionFailed: Set<string>;
+/**
+ * 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 declare const nativeSessionTranscriptOwners: Map<string, string>;
+/** Session name -> resolved compaction settings. Same lifecycle as the maps above. */
+export declare const nativeSessionCompaction: Map<string, ResolvedCompaction>;
+/**
+ * Session name -> resolved transport-fault retry settings (nax#1870). Same
+ * lifecycle as the maps above: set on open, cleared on close.
+ */
+export declare const nativeSessionTransportRetry: Map<string, TurnRetryConfig>;
+/**
+ * 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 declare const nativeSessionSpinBreaker: Map<string, SpinBreaker>;
+/**
+ * Session name -> the last round trip's reported input tokens and the index it
+ * covers, so the next estimate can anchor on a real number.
+ *
+ * In-memory rather than persisted because runNativeTurn reloads the transcript
+ * from disk on EVERY turn: without this the second turn of every session would
+ * be estimated from scratch. A process restart still loses it, which is the case
+ * the reactive backstop covers.
+ *
+ * `model` is the transcript model identity the anchor was measured under
+ * (P3 spec 8.3(d)); read it through `sessionAnchorFor`, never directly.
+ */
+export interface SessionAnchor {
+    readonly promptTokens: number;
+    readonly anchorIndex: number;
+    readonly model?: string;
+}
+export declare const nativeSessionLastUsage: Map<string, SessionAnchor>;
+/**
+ * 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 declare function sessionAnchorFor(sessionName: string, model: string | undefined): SessionAnchor | undefined;
+/** Records how the session's latest turn ended, for `closeNativeSession`. */
+export declare function markNativeTurnOutcome(sessionName: string, failed: boolean): void;
+export declare function openNativeSession(name: string, opts: OpenSessionOpts): Promise<SessionHandle>;
+/**
+ * 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 declare function clearNativeSessionState(sessionName: string): void;
+/**
+ * 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 declare function closeNativeSession(handle: SessionHandle, failed?: boolean): Promise<void>;