@nathapp/nax-agent 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.3.1] - 2026-10-07
+
+### Added
+
+- `attachTurnSpend(err, spend)` and `readTurnSpend(err)`, with the `FailedTurnSpend` type: a backend attaches the spend a failed turn had already incurred to the error it throws, and the turn's `turn_end` reports it (#2367).
+- `OpenSessionOpts.toolAudit` (optional `{ dir, header }`): the tool-audit ledger location and header for an S1 adapter that writes its own ledger (nax's ACP adapter, S4b). nax-agent itself does not read it; native takes its sink from coding-tool support.
+- `resultBytes` (optional) on the `tool_result` turn event: the UTF-8 byte length of the full result before the preview cap.
+- `ToolAuditHeader` is exported from the package entry.
+- `AGENT_SESSION_RATE_LIMITED` error code (a backend's rate-limited turn).
+- `tool_progress` turn event: a running tool's liveness beat (no content), for S1 callers such as nax's idle watchdog. The session facade does not forward it as a session event.
+
+### Fixed
+
+- `turn_end` of an errored, cancelled or timed-out turn carries `costSource` when the failed turn's spend says how it was priced (#2367).
+
 ## [0.3.0] - 2026-10-06
 
 The backend seam for S4. Breaking: `createAgentSession` takes a `SessionBackend`. nax behaviour unchanged.

package/dist/index.d.ts

@@ -37,8 +37,9 @@ export type { NativeBackendOptions } from "#src/session/native-backend-options";
 export type { ProtocolIds } from "#src/session/protocol-types";
 export type { ApprovalRequest, BackendInfo, BackendOpenContext, OpenedBackend, SessionAskPort, SessionBackend, TurnContribution, } from "#src/session/session-backend";
 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 { attachTurnSpend, type FailedTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 export type { JSONSchema, ToolDescriptor, } from "#src/session/tool-descriptor";
 export { createTurnDeadline, type TurnDeadline, } from "#src/session/turn-deadline";
 export type { TurnEvent, TurnEventSink } from "#src/session/turn-event";
-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";
+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 ToolAuditHeader, 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";
 export { EMPTY_OWNED_PATHS_POLICY, type OwnedBashCandidate, type OwnedPathsPolicy, } from "#src/tools/owned-paths";

package/dist/index.js

@@ -26,6 +26,7 @@ export { AgentSessionError } from "#src/session/agent-session-errors";
 export { NO_OP_INTERACTION_HANDLER, } from "#src/session/interaction-handler";
 export { nativeBackend } from "#src/session/native-backend";
 export { SessionTurnError, } from "#src/session/session-types";
+export { attachTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 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";
 export { EMPTY_OWNED_PATHS_POLICY, } from "#src/tools/owned-paths";

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

@@ -6,11 +6,10 @@
  * algorithm and the file under the 600-line hard limit (see
  * .nax/rules/project-conventions.md).
  *
- * The failure-usage ledger (`failureUsageByError` WeakMap +
- * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
- * here: it is module-level state with a process-lifetime scope, and the
- * loop's catch block only ever calls the write side through this file's
- * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * The failure-usage ledger's native API (`recordNativeTurnFailureUsage` /
+ * `readNativeTurnFailureUsage`) also lives here; the WeakMap itself lives in
+ * `#src/session/turn-spend`, shared with ACP backends (#2367). The loop's
+ * catch block only ever calls the write side through this file's public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
  * attribute round-trip spend to the error a failed turn threw (nax#1840).
  */
 import type { ConversationMessage, ThinkingBlock, ToolCall } from "@nathapp/nax-ai";

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

@@ -6,21 +6,21 @@
  * algorithm and the file under the 600-line hard limit (see
  * .nax/rules/project-conventions.md).
  *
- * The failure-usage ledger (`failureUsageByError` WeakMap +
- * `recordNativeTurnFailureUsage` / `readNativeTurnFailureUsage`) also lives
- * here: it is module-level state with a process-lifetime scope, and the
- * loop's catch block only ever calls the write side through this file's
- * public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
+ * The failure-usage ledger's native API (`recordNativeTurnFailureUsage` /
+ * `readNativeTurnFailureUsage`) also lives here; the WeakMap itself lives in
+ * `#src/session/turn-spend`, shared with ACP backends (#2367). The loop's
+ * catch block only ever calls the write side through this file's public API. Adapter.ts reads through `readNativeTurnFailureUsage` to
  * attribute round-trip spend to the error a failed turn threw (nax#1840).
  */
-const failureUsageByError = new WeakMap();
+import { attachTurnSpend, readTurnSpend } from "#src/session/turn-spend";
 /** Writes the spend a failed turn accumulated, keyed on the error's own identity. */
 export function recordNativeTurnFailureUsage(err, usage) {
-    failureUsageByError.set(err, usage);
+    attachTurnSpend(err, usage);
 }
 /** Reads back what the catch block recorded, if anything did. */
 export function readNativeTurnFailureUsage(err) {
-    return typeof err === "object" && err !== null ? failureUsageByError.get(err) : undefined;
+    const spend = readTurnSpend(err);
+    return spend === undefined ? undefined : { tokenUsage: spend.tokenUsage, costUsd: spend.costUsd };
 }
 /**
  * Translate a `TokenUsage`'s cache fields into the spread that the

package/dist/session/agent-session-errors.d.ts

@@ -4,7 +4,7 @@
  * or registerCodingTool's TOOL_NAME_RESERVED.
  */
 import { NaxError } from "#src/infra/nax-error";
-export type AgentSessionErrorCode = "AGENT_SESSION_INVALID_OPTIONS" | "AGENT_SESSION_EXISTS" | "AGENT_SESSION_BUSY" | "AGENT_SESSION_CLOSED" | "AGENT_SESSION_INVALID_ANSWER" | "AGENT_SESSION_NOT_FOUND" | "AGENT_SESSION_SCHEMA_UNSUPPORTED" | "AGENT_SESSION_MODEL_MISMATCH" | "AGENT_SESSION_SANDBOX_UNAVAILABLE" | "AGENT_SESSION_TOOL_NAME_RESERVED" | "AGENT_SESSION_BACKEND_UNAVAILABLE" | "AGENT_SESSION_AUTH_REQUIRED" | "AGENT_SESSION_CAPABILITY_UNSUPPORTED" | "AGENT_SESSION_BACKEND_MISMATCH";
+export type AgentSessionErrorCode = "AGENT_SESSION_INVALID_OPTIONS" | "AGENT_SESSION_EXISTS" | "AGENT_SESSION_BUSY" | "AGENT_SESSION_CLOSED" | "AGENT_SESSION_INVALID_ANSWER" | "AGENT_SESSION_NOT_FOUND" | "AGENT_SESSION_SCHEMA_UNSUPPORTED" | "AGENT_SESSION_MODEL_MISMATCH" | "AGENT_SESSION_SANDBOX_UNAVAILABLE" | "AGENT_SESSION_TOOL_NAME_RESERVED" | "AGENT_SESSION_BACKEND_UNAVAILABLE" | "AGENT_SESSION_AUTH_REQUIRED" | "AGENT_SESSION_RATE_LIMITED" | "AGENT_SESSION_CAPABILITY_UNSUPPORTED" | "AGENT_SESSION_BACKEND_MISMATCH";
 export declare class AgentSessionError extends NaxError {
     readonly code: AgentSessionErrorCode;
     constructor(message: string, code: AgentSessionErrorCode, context?: Record<string, unknown>);

package/dist/session/agent-session-turn.js

@@ -1,10 +1,10 @@
 import { NaxError } from "#src/infra/nax-error";
 import { redactSecrets } from "#src/internal/redact";
-import { readNativeTurnFailureUsage } from "#src/native/session/turn-types";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { createSessionEventChannel } from "./session-event-channel.js";
 import { SessionTurnError } from "./session-types.js";
+import { readTurnSpend } from "./turn-spend.js";
 /** The ask_human budget per turn: nax's agent.maxInteractionTurns default. */
 export const ASK_HUMAN_BUDGET = 10;
 /** Codes of the turn signal's abort reasons. AbortSignal keeps the first reason, so the first cause wins. */
@@ -57,10 +57,13 @@ function errorOf(err) {
         return failure(err.code, message);
     return failure("AGENT_SESSION_TURN_FAILED", message);
 }
+/** A failed turn's spend: attached to its error (#2367), carried by a SessionTurnError, or zero. */
 function spendOf(err) {
-    const recorded = readNativeTurnFailureUsage(err);
-    if (recorded !== undefined)
-        return { usage: recorded.tokenUsage, costUsd: recorded.costUsd };
+    const attached = readTurnSpend(err);
+    if (attached !== undefined) {
+        const { tokenUsage: usage, costUsd, costSource } = attached;
+        return costSource === undefined ? { usage, costUsd } : { usage, costUsd, costSource };
+    }
     if (err instanceof SessionTurnError)
         return { usage: err.tokenUsage ?? ZERO_USAGE, costUsd: err.estimatedCostUsd ?? 0 };
     return { usage: ZERO_USAGE, costUsd: 0 };
@@ -84,7 +87,11 @@ function sendTurn(ctx, live, message) {
         maxInteractions: ASK_HUMAN_BUDGET,
         turnId: live.turnId,
         signal: live.signal,
-        onTurnEvent: (event) => live.emit(event),
+        // tool_progress is a liveness beat for S1 callers (nax's idle watchdog), not a session event.
+        onTurnEvent: (event) => {
+            if (event.type !== "tool_progress")
+                live.emit(event);
+        },
     });
 }
 /** Writes the turn marker; a failure is returned, not thrown. */

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

@@ -136,6 +136,16 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * scratch dir reaches the adapter otherwise. ACP ignores it.
      */
     transcriptDir?: string;
+    /**
+     * S4b spec 7.4: where an S1 adapter that writes its own tool-audit ledger (nax's
+     * ACP adapter) writes it, and the run-scoped header stamped on it. nax fills it
+     * from the same resolution the native coding tools use. nax-agent itself does not
+     * read it; native takes its sink from coding-tool support.
+     */
+    toolAudit?: {
+        readonly dir: string;
+        readonly header: import("#src/tools/tool-audit").ToolAuditHeader;
+    };
     /**
      * Native: identity that owns this session's transcript — the op invocation's
      * `scopeId ?? callId`. Stable across the retries and hops of one invocation,

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

@@ -43,6 +43,13 @@ export type TurnEvent = {
     readonly callId: string;
     readonly isError: boolean;
     readonly preview: string;
+    /** UTF-8 byte length of the full result before the preview cap (S4b spec 7.4). Absent when unknown. */
+    readonly resultBytes?: number;
+}
+/** A running tool's liveness beat (an ACP heartbeat); carries no content. Not a session event. */
+ | {
+    readonly type: "tool_progress";
+    readonly callId: string;
 } | {
     readonly type: "usage";
     readonly round: number;

package/dist/session/turn-spend.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The spend a failed turn had already incurred, attached to the error it throws
+ * (#2367). Keyed on the error's identity, so the error itself is rethrown
+ * unchanged and keeps its own code. The facade's turn_end reads it on every
+ * error path; the native loop writes it through recordNativeTurnFailureUsage
+ * (nax#1840), an ACP backend through attachTurnSpend.
+ */
+import type { TokenUsage } from "#src/cost/standard-types";
+import type { CostSource } from "./agent-session-types.ts";
+export interface FailedTurnSpend {
+    readonly tokenUsage: TokenUsage;
+    readonly costUsd: number;
+    readonly costSource?: CostSource;
+}
+/** Attaches the spend a failed turn had already incurred to the error it throws. */
+export declare function attachTurnSpend(err: object, spend: FailedTurnSpend): void;
+/** The spend attached to `err`, if any. */
+export declare function readTurnSpend(err: unknown): FailedTurnSpend | undefined;

package/dist/session/turn-spend.js

@@ -0,0 +1,9 @@
+const spendByError = new WeakMap();
+/** Attaches the spend a failed turn had already incurred to the error it throws. */
+export function attachTurnSpend(err, spend) {
+    spendByError.set(err, Object.freeze({ ...spend }));
+}
+/** The spend attached to `err`, if any. */
+export function readTurnSpend(err) {
+    return typeof err === "object" && err !== null ? spendByError.get(err) : undefined;
+}

package/dist/tools/index.d.ts

@@ -28,7 +28,7 @@ export type { CodingToolOutcome, CodingToolRuntime, ToolCallContext } from "./ru
 export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.ts";
 export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.ts";
 export { _spillDeps, applyModelTruncationPolicy, type ModelTruncationOptions, SPILL_DIR, type SpillRequest, spillRelativePath, writeSpill, } from "./spill.ts";
-export type { RegisteredSink, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
+export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
 export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.ts";
 export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, } from "./truncate.ts";
 export type { CodingToolName, PolicyVerdict, ToolGrant, ToolPolicy, ToolScope } from "./types.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",