@nathapp/nax-agent 0.1.0

package/dist/cost/usage-math.d.ts

@@ -0,0 +1,18 @@
+/** Pure usage arithmetic shared by the pricing core and nax's reporting helpers. */
+import type { TokenUsage } from "./standard-types.ts";
+/** Sum two TokenUsage values. Pure.
+ * A cache field is present on the result when either operand carries it or the
+ * sum is positive, preserving the zero-versus-absent distinction producers set. */
+export declare function addTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * Tokens the provider counted as part of the prompt.
+ *
+ * Cache reads and writes are prompt tokens that the provider reports
+ * separately because it prices them differently — not tokens that were
+ * absent from the request. Any consumer asking "how big was the prompt"
+ * needs all three; `inputTokens` alone answers a different question and,
+ * under prompt caching, collapses to near zero (nax#1852).
+ *
+ * Output is deliberately excluded: this measures the prompt, not the call.
+ */
+export declare function inputClassTokens(usage: TokenUsage): number;

package/dist/cost/usage-math.js

@@ -0,0 +1,46 @@
+/** Coerce a token count to a finite number, falling back to 0. Defense in
+ * depth (BUG-10): upstream guards in parser.ts / token-mapper.ts should
+ * already keep non-numeric values out, but `addTokenUsage` is a cheap pure
+ * function reachable from multiple call sites, so it validates its own
+ * inputs rather than trusting the static TokenUsage type — a malformed
+ * operand (e.g. a stringified number) would otherwise trigger `+`'s string
+ * concatenation instead of numeric addition, and a genuinely non-numeric
+ * value would propagate NaN into the running total. */
+function toFiniteTokenCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/** Sum two TokenUsage values. Pure.
+ * A cache field is present on the result when either operand carries it or the
+ * sum is positive, preserving the zero-versus-absent distinction producers set. */
+export function addTokenUsage(a, b) {
+    // BUG-58: apply the same finite-number guard to the cache fields as
+    // inputTokens/outputTokens above — `?? 0` alone only guards undefined/null,
+    // not a malformed non-numeric operand (e.g. a stringified number), which
+    // would otherwise hit `+`'s string-concatenation behavior here too.
+    const cacheRead = toFiniteTokenCount(a.cacheReadTokens ?? 0) + toFiniteTokenCount(b.cacheReadTokens ?? 0);
+    const cacheWrite = toFiniteTokenCount(a.cacheWriteTokens ?? 0) + toFiniteTokenCount(b.cacheWriteTokens ?? 0);
+    return {
+        inputTokens: toFiniteTokenCount(a.inputTokens) + toFiniteTokenCount(b.inputTokens),
+        outputTokens: toFiniteTokenCount(a.outputTokens) + toFiniteTokenCount(b.outputTokens),
+        ...(cacheRead > 0 || a.cacheReadTokens !== undefined || b.cacheReadTokens !== undefined
+            ? { cacheReadTokens: cacheRead }
+            : {}),
+        ...(cacheWrite > 0 || a.cacheWriteTokens !== undefined || b.cacheWriteTokens !== undefined
+            ? { cacheWriteTokens: cacheWrite }
+            : {}),
+    };
+}
+/**
+ * Tokens the provider counted as part of the prompt.
+ *
+ * Cache reads and writes are prompt tokens that the provider reports
+ * separately because it prices them differently — not tokens that were
+ * absent from the request. Any consumer asking "how big was the prompt"
+ * needs all three; `inputTokens` alone answers a different question and,
+ * under prompt caching, collapses to near zero (nax#1852).
+ *
+ * Output is deliberately excluded: this measures the prompt, not the call.
+ */
+export function inputClassTokens(usage) {
+    return usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @nathapp/nax-agent public entry (S1 spec section 4.4, S2 spec section 5.3).
+ *
+ * Every export is named: nothing reaches this entry through `export *`. No "_"
+ * name belongs here; test seams and reset hooks live on ./internal. The built
+ * surface of both entries is pinned by api/nax-agent.api.txt (`bun run check:api`).
+ *
+ * Generated once by S2-7 from the previous `export *` barrels; maintained by hand.
+ */
+export { appendCommandSafetyRow, type BuildCommandShadowOptions, buildCommandShadow, buildRequest, type Classify, COMMAND_SAFETY_DIR, type CommandGuard, type CommandSafetyRow, type CommandShadow, type CommandShadowOptions, createCommandGuard, createCommandShadow, createSystemOneClient, detectTmpWrite, type ExecRun, type FinalOutcome, type GuardDecision, type GuardInput, HARM_OPTIONS, HARM_QUESTION_ID, type HarmOption, isTempOnly, type LedgerOutcome, type MechanicalVerdict, type ModelAnswers, type ModelResult, type Observation, openShadowTap, parseAnswer, QUESTION_IDS, QUESTION_SET_VERSION, type QuestionId, RULE_SET_VERSION, type RuleContext, type RuleResult, type ShadowCall, type ShadowTap, SYSTEMONE_MODEL_LABEL, type SystemOneClientOptions, type SystemOneQuestion, type SystemOneRequest, scoreGuard, scoreRules, shadowCacheKey, toMechanical, } from "#src/command-safety/index";
+export { addTokenUsage, estimateCostUsd, inputClassTokens, type Pricing, type PricingRates, type PricingTier, priceCall, type TokenUsage, } from "#src/cost/core/index";
+export { type ModelSpec, parseModelSpec, } from "#src/cost/model-spec";
+export type { AgentLogger, CredentialAuthConfig, CredentialsConfig } from "#src/infra/index";
+export { configureCredentials, setAgentLogger } from "#src/infra/index";
+export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, } from "#src/native/index";
+export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, type AskControl, type AskDecidedBy, type AskDecision, type AskLink, type AskLinkOutcome, type AskRequest, type AskResolver, type AskVerdict, appendApproval, appendApprovalAudit, approvalId, approvalsPath, type BashLexResult, type BashRedirect, type BashSegment, type BashSegmentSeparator, type BashToken, type ClearTaintOutcome, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, type MaskResult, maskForPrompt, type PrepareApprovalsStoreOptions, parseRuleList, parseToolExpression, prepareApprovalsStore, type RemovalDecision, type RemovalResult, type ResolvedPermissions, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, type SecretSpan, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
+export { type AgentGlobOptions, type AgentRuntime, type AgentSpawnOptions, type AgentSpawnResult, type AgentSpawnStdin, getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
+export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export type { AdapterFailure } from "#src/session/adapter-failure";
+export type { AgentAwaitingHumanEvent, AgentCallEndedEvent, AgentCallStartedEvent, AgentMessageUpdateEvent, AgentProcessUpdateEvent, AgentStreamEvent, AgentStreamEventBase, AgentThinkingUpdateEvent, AgentToolCallUpdateEvent, AgentUsageUpdateEvent, } from "#src/session/agent-stream-events";
+export { type AdapterInteraction, type AdapterInteractionResponse, type InteractionHandler, NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
+export type { ProtocolIds } from "#src/session/protocol-types";
+export { type AgentSessionAdapter, type AuthStamp, type InteractionExchange, type InvalidToolCallDetail, type OpenSessionOpts, type SendTurnOpts, type SessionHandle, type SessionModel, SessionTurnError, type TrackedSpawnDeadlineOptions, type TurnResult, } from "#src/session/session-types";
+export type { JSONSchema, ToolDescriptor, } from "#src/session/tool-descriptor";
+export { createTurnDeadline, type TurnDeadline, } from "#src/session/turn-deadline";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @nathapp/nax-agent public entry (S1 spec section 4.4, S2 spec section 5.3).
+ *
+ * Every export is named: nothing reaches this entry through `export *`. No "_"
+ * name belongs here; test seams and reset hooks live on ./internal. The built
+ * surface of both entries is pinned by api/nax-agent.api.txt (`bun run check:api`).
+ *
+ * Generated once by S2-7 from the previous `export *` barrels; maintained by hand.
+ */
+export { appendCommandSafetyRow, buildCommandShadow, buildRequest, COMMAND_SAFETY_DIR, createCommandGuard, createCommandShadow, createSystemOneClient, detectTmpWrite, HARM_OPTIONS, HARM_QUESTION_ID, isTempOnly, openShadowTap, parseAnswer, QUESTION_IDS, QUESTION_SET_VERSION, RULE_SET_VERSION, SYSTEMONE_MODEL_LABEL, scoreGuard, scoreRules, shadowCacheKey, toMechanical, } from "#src/command-safety/index";
+export { addTokenUsage, estimateCostUsd, inputClassTokens, priceCall, } from "#src/cost/core/index";
+export { parseModelSpec, } from "#src/cost/model-spec";
+export { configureCredentials, setAgentLogger } from "#src/infra/index";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, appendApproval, appendApprovalAudit, approvalId, approvalsPath, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, maskForPrompt, parseRuleList, parseToolExpression, prepareApprovalsStore, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
+export { getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
+export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";
+export { NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
+export { SessionTurnError, } from "#src/session/session-types";
+export { createTurnDeadline, } from "#src/session/turn-deadline";
+export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, deleteTool, EXEC_TOOL_NAME, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, mcpRuleAdmits, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, PROVIDER_ID_RE, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";

package/dist/infra/agent-logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The logger slot (spec R2). nax-agent logs through whatever logger the host
+ * installs; nax installs its own from `initLogger` and clears it in
+ * `resetLogger`.
+ *
+ * Unset semantics match nax's logger exactly: `getSafeLogger()` gives `null`
+ * (callers use `?.`), and `getLogger()` gives a silent no-op rather than
+ * throwing. nax's `getLogger()` returns a sink-less silent logger when
+ * uninitialised, so neither form has ever produced output before init.
+ */
+export interface AgentLogger {
+    error(stage: string, message: string, data?: Record<string, unknown>): void;
+    warn(stage: string, message: string, data?: Record<string, unknown>): void;
+    info(stage: string, message: string, data?: Record<string, unknown>): void;
+    debug(stage: string, message: string, data?: Record<string, unknown>): void;
+}
+/** Install (or, with `null`, clear) the process-wide logger. */
+export declare function setAgentLogger(logger: AgentLogger | null): void;
+/** The installed logger, or `null` when none is installed. */
+export declare function getSafeLogger(): AgentLogger | null;
+/** The installed logger, or a silent no-op when none is installed. Never throws. */
+export declare function getLogger(): AgentLogger;

package/dist/infra/agent-logger.js

@@ -0,0 +1,19 @@
+const noopLogger = {
+    error: () => { },
+    warn: () => { },
+    info: () => { },
+    debug: () => { },
+};
+let installed = null;
+/** Install (or, with `null`, clear) the process-wide logger. */
+export function setAgentLogger(logger) {
+    installed = logger;
+}
+/** The installed logger, or `null` when none is installed. */
+export function getSafeLogger() {
+    return installed;
+}
+/** The installed logger, or a silent no-op when none is installed. Never throws. */
+export function getLogger() {
+    return installed ?? noopLogger;
+}

package/dist/infra/credentials-config.d.ts

@@ -0,0 +1,20 @@
+/** Auth settings used by the native credential store. */
+export interface CredentialAuthConfig {
+    readonly source: "file" | "exec";
+    readonly exec?: {
+        readonly command: readonly string[];
+        readonly timeoutMs: number;
+    };
+    readonly onChange: "warn" | "refuse";
+}
+/** Host functions the native credential store reads on demand. */
+export interface CredentialsConfig {
+    /** The directory holding `credentials`, `config.json` and the fingerprint salt. Read per call. */
+    configDir(): string;
+    /** The auth section of the global config. Read per call. */
+    readAuthConfig(): Promise<CredentialAuthConfig>;
+}
+export declare function configureCredentials(config: CredentialsConfig): void;
+export declare function credentialsConfig(): CredentialsConfig;
+/** Clears the slot. Tests only. @internal */
+export declare function _resetCredentialsConfig(): void;

package/dist/infra/credentials-config.js

@@ -0,0 +1,15 @@
+import { NaxError } from "./nax-error.js";
+let configured;
+export function configureCredentials(config) {
+    configured = config;
+}
+export function credentialsConfig() {
+    if (configured === undefined) {
+        throw new NaxError("Credentials are not configured: call configureCredentials() before reading credentials", "CREDENTIALS_NOT_CONFIGURED", { stage: "credentials" });
+    }
+    return configured;
+}
+/** Clears the slot. Tests only. @internal */
+export function _resetCredentialsConfig() {
+    configured = undefined;
+}

package/dist/infra/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error utilities
+ */
+/**
+ * Extract error message from unknown error type.
+ *
+ * Handles both Error instances and non-Error values that can be thrown in JavaScript.
+ */
+export declare function errorMessage(err: unknown): string;

package/dist/infra/errors.js

@@ -0,0 +1,11 @@
+/**
+ * Error utilities
+ */
+/**
+ * Extract error message from unknown error type.
+ *
+ * Handles both Error instances and non-Error values that can be thrown in JavaScript.
+ */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/infra/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * nax-agent infrastructure (spec R2): the error base class and the process-wide
+ * slots nax fills. Imports nothing from nax.
+ */
+export { type AgentLogger, getLogger, getSafeLogger, setAgentLogger } from "./agent-logger.ts";
+export { _resetCredentialsConfig, type CredentialAuthConfig, type CredentialsConfig, configureCredentials, credentialsConfig, } from "./credentials-config.ts";
+export { NaxError } from "./nax-error.ts";

package/dist/infra/index.js

@@ -0,0 +1,7 @@
+/**
+ * nax-agent infrastructure (spec R2): the error base class and the process-wide
+ * slots nax fills. Imports nothing from nax.
+ */
+export { getLogger, getSafeLogger, setAgentLogger } from "./agent-logger.js";
+export { _resetCredentialsConfig, configureCredentials, credentialsConfig, } from "./credentials-config.js";
+export { NaxError } from "./nax-error.js";

package/dist/infra/nax-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Base error class for all nax errors. Lives in the move set (spec R2);
+ * `src/errors.ts` re-exports it so every `instanceof NaxError` check matches
+ * one class.
+ */
+export declare class NaxError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}

package/dist/infra/nax-error.js

@@ -0,0 +1,16 @@
+/**
+ * Base error class for all nax errors. Lives in the move set (spec R2);
+ * `src/errors.ts` re-exports it so every `instanceof NaxError` check matches
+ * one class.
+ */
+export class NaxError extends Error {
+    code;
+    context;
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = "NaxError";
+        Error.captureStackTrace(this, this.constructor);
+    }
+}

package/dist/infra/spin-breaker/hash.d.ts

@@ -0,0 +1,2 @@
+/** In-memory deduplication key with 64 bits of collision resistance. */
+export declare function digest64(text: string): string;

package/dist/infra/spin-breaker/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** In-memory deduplication key with 64 bits of collision resistance. */
+export function digest64(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}

package/dist/infra/spin-breaker/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Repetition breaker for an agent turn.
+ *
+ * A verifier session ran 36 minutes re-running the same PASSING scoped test
+ * 622 times, emitted no verdict, and was ended by an operator (nax#2013). Every
+ * call was fast and exited 0, so there was no timeout, no error rate and no
+ * failing gate to trip; what distinguished it was repetition without progress
+ * — 622 calls across 2 distinct argv shapes and no file writes.
+ *
+ * Deliberately NOT a round-trip cap. That was removed twice on purpose
+ * (#1823/#1827/#1830, then #1819/#1820) and a session making 600 VARIED calls
+ * is working, not spinning. This counts only calls whose normalised shape was
+ * already seen.
+ *
+ * Transport-neutral and config-free by construction: it takes resolved
+ * settings, so `src/agents/native/` can consult it without reading NaxConfig
+ * (check:adapter-no-config-import).
+ */
+export interface ResolvedSpinBreakerSettings {
+    readonly enabled: boolean;
+    /** Repeats since the last new call before the first nudge. */
+    readonly nudgeAfterRepeats: number;
+    /** How many nudges to spend before the hard stop. */
+    readonly maxNudges: number;
+    /**
+     * Repeats since the last new call at which the turn ends, AND the raw
+     * per-key backstop. Overloaded: `stopAfterSameKeyRepeats` gates the
+     * consecutive-identical-result threshold, while the same key's raw
+     * cumulative count is separately capped here. That backstop is the only
+     * thing that bounds a call whose result changes every time (or never
+     * reaches `noteResult`), which the result axis cannot see.
+     */
+    readonly stopAfterRepeats: number;
+    /** How many recent distinct keys count as "already seen". */
+    readonly recentKeyWindow: number;
+    /**
+     * Consecutive occurrences of the same call whose RESULT was unchanged at
+     * which the turn ends — the consecutive same-result run, NOT the raw
+     * per-key count (which `stopAfterRepeats` caps). This is the axis that
+     * closes the nax#2047 laundering hole (a different key firing between
+     * occurrences no longer resets the run) without killing a healthy
+     * edit -> re-run-test loop, whose result changes each iteration. `0`
+     * disables this axis.
+     */
+    readonly stopAfterSameKeyRepeats: number;
+    /**
+     * nax#2017: seconds with no new call key after which a repeat run ends the turn, so a slow spin
+     * stops as fail-spin before the tool-call-only idle watchdog cancels it as fail-stale. 0 disables.
+     */
+    readonly stopAfterNoProgressSeconds: number;
+}
+export declare const DEFAULT_SPIN_BREAKER_SETTINGS: ResolvedSpinBreakerSettings;
+/** Why the breaker ended the turn. Kept exhaustive so telemetry is accurate. */
+export type SpinStopReason = "repeat-run" | "same-key-cumulative" | "same-key-backstop" | "no-progress-time";
+export type SpinVerdict = {
+    readonly action: "allow";
+} | {
+    readonly action: "nudge";
+    readonly nudgeNumber: number;
+    readonly repeats: number;
+    readonly text: string;
+} | {
+    readonly action: "stop";
+    readonly repeats: number;
+    readonly reason: SpinStopReason;
+};
+export interface SpinSummary {
+    readonly totalCalls: number;
+    /**
+     * Cache-misses against the bounded `recentKeyWindow`, i.e. how many times
+     * this session did something new. Equal to true key cardinality only while
+     * the session's distinct-key count stays within `recentKeyWindow` — once a
+     * key is evicted from the window, seeing it again counts as another new-key
+     * event, so this is NOT a reliable "unique calls this session made" count
+     * for a long session. Deliberately not backed by an unbounded Set: the
+     * window exists to bound memory, and "how many new things happened" is the
+     * more useful number for a spin diagnostic anyway.
+     */
+    readonly newKeyEvents: number;
+    readonly maxRepeatRun: number;
+    /**
+     * Highest cumulative repeat count observed for a single key (nax#2047).
+     * Same windowing tradeoff as `newKeyEvents`: an evicted key loses its
+     * count, so this is the peak within the current window rather than a
+     * session-lifetime peak. The `maxRepeatRun` field above stays the
+     * instrument for #2013's 622-call varied verifier; this is the new
+     * instrument for the laundering hole — they answer different questions.
+     */
+    readonly maxSameKeyRepeats: number;
+    readonly nudges: number;
+}
+export interface SpinBreaker {
+    observe(toolName: string, input: unknown): SpinVerdict;
+    /**
+     * Feed back what a call returned. `observe` runs pre-execution, so the
+     * result of occurrence N is only known when occurrence N+1 is judged —
+     * that one-call lag is intentional and harmless at these thresholds.
+     * A call that throws never reaches here (an error string is not a result),
+     * so it falls back to the raw backstop inside `observe`. A DENIED call
+     * does reach here (turn-loop feeds `answer.answer`): a stable denial is an
+     * unchanged result and is intended to count toward the same-result run.
+     */
+    noteResult(toolName: string, input: unknown, resultText: string): void;
+    summary(): SpinSummary;
+}
+/**
+ * Answered to every outstanding call when the breaker first decides to end a
+ * turn (nax#2120). The stop used to break with the call unexecuted and
+ * unanswered, so the turn was classified `fail-spin` and retried on the
+ * timeout lane — a FRESH session at a reduced budget, discarding everything
+ * the turn had accumulated. One terminal round trip lets the model close out
+ * instead. NUDGE_ESCALATION's final warning is one step ahead of the hard
+ * end, not literally true: the first stop only warns (this notice) and only a
+ * further stop verdict ends the turn.
+ */
+export declare const SPIN_TERMINAL_NOTICE: string;
+export declare function spinTerminalNotice(reason: SpinStopReason): string;
+export declare function createSpinBreaker(settings: ResolvedSpinBreakerSettings, deps?: {
+    readonly now?: () => number;
+}): SpinBreaker;