@nathapp/nax-agent 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.
+
+### Changed
+
+- **Breaking:** `CreateAgentSessionOptions.backend` is a `SessionBackend` (was `"native"`). `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval` and `allowUnsandboxed` move into `nativeBackend({ ... })`. A native-only key at the top level is `AGENT_SESSION_INVALID_OPTIONS`.
+- `resumeAgentSession` refuses a document written by another backend kind (`AGENT_SESSION_BACKEND_MISMATCH`); documents without a `backend` field are native.
+
+### Added
+
+- `SessionBackend`, `BackendOpenContext`, `OpenedBackend`, `BackendInfo`, `TurnContribution`, `SessionAskPort`, `ApprovalRequest`, and `nativeBackend` with `NativeBackendOptions`. `AgentSession.backend` reports the backend's kind and capabilities.
+- The `ask` profile: every Write, Edit, Delete, GitCommit and Bash is approved through `answer()`; it requires `bashApproval: "gated"` and the sandbox floor of `full`.
+- `ApprovalDecidedBy` gains `"profile"`; `usage` and `turn_end` gain `costSource` (`computed` | `reported` | `unpriced`; `CostSource`); `TurnResult` gains `costSource`.
+- Error codes `AGENT_SESSION_BACKEND_UNAVAILABLE`, `AGENT_SESSION_AUTH_REQUIRED`, `AGENT_SESSION_CAPABILITY_UNSUPPORTED`, `AGENT_SESSION_BACKEND_MISMATCH`.
+- `TranscriptDoc.backend` and `TranscriptDoc.acp` (`TranscriptAcpRecord`), optional and additive (schemaVersion stays 1).
+- `TranscriptAcpRecord.costUsd`: the ACP agent's cumulative cost reading at the session's last priced turn, so a resumed ACP session prices its next turn from it.
+- Backend kit on `.`: `redactSecrets`, `capStrings`, `killProcessGroup`, `isProcessAlive`, `TOOL_CALL_INPUT_BYTES`, `TOOL_RESULT_PREVIEW_BYTES`, `createStderrTail` (`StderrTail`), and `NaxError`, the base class of `AgentSessionError`, so a backend can throw codes outside `AgentSessionErrorCode` (S4 spec §5.7).
+- `getLogger` on `.`: the logger the host installed with `setAgentLogger`, or a silent no-op, so a backend can log through the host's logger.
+- `SessionAskPort.askQuestion(text, { signal })`: an extra abort source combined with the turn signal, as `ApprovalRequest.signal` is for approvals, so a backend can settle a question when its own request scope ends (S4 spec §6.3 step 5).
+
 ## [0.2.0] - 2026-10-05
 
 The conversational session API for embedders. nax behaviour unchanged.

package/README.md

@@ -42,7 +42,7 @@ Three pieces of host knowledge are passed in as data or functions, because the p
 `createAgentSession` gives an embedder (for example a long-running Node service) a multi-turn chat with a person in the loop. Events stream, tools come from the embedder, history lives in a store the embedder supplies, and a turn can be cancelled or answered with an approval.
 
 ```ts
-import { createAgentSession, createFileTranscriptStore, type EmbedderTool } from "@nathapp/nax-agent";
+import { createAgentSession, createFileTranscriptStore, type EmbedderTool, nativeBackend } from "@nathapp/nax-agent";
 
 const lookupOrder: EmbedderTool = {
   name: "lookup_order",
@@ -55,14 +55,11 @@ const lookupOrder: EmbedderTool = {
 };
 
 const session = await createAgentSession({
-  backend: "native",
-  sessionId: "ticket-1234",
-  model: "anthropic/claude-sonnet-5-5",
-  profile: "none", // "none" | "read" | "full"
-  instructions: "You are a support assistant.",
+  backend: nativeBackend({ model: "anthropic/claude-sonnet-5-5" }),
+  profile: "ask",
+  workdir: "/abs/project",
   tools: [lookupOrder],
-  transcriptStore: createFileTranscriptStore("/var/lib/my-app/sessions"),
-  credentials: { kind: "memory", credentials: { anthropic: { kind: "api-key", key: process.env.ANTHROPIC_API_KEY! } } },
+  transcriptStore: createFileTranscriptStore("/abs/state/sessions"),
 });
 
 for await (const event of session.send("Where is order 42?")) {
@@ -73,18 +70,30 @@ for await (const event of session.send("Where is order 42?")) {
 await session.close();
 ```
 
+Profiles set what a session may do:
+
+| Profile | Side effects |
+|:--------|:-------------|
+| `none` | no side effects; |
+| `read` | read-only; |
+| `ask` | every Write, Edit, Delete, GitCommit and Bash is put to `answer()`; |
+| `full` | no prompts; `bashApproval` and the sandbox floor apply. |
+
+`createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval` and `allowUnsandboxed`. The ACP backend ships in `@nathapp/nax-agent-acp`.
+
+`usage.costSource` is `computed` (native), `reported` or `unpriced`; never sum `unpriced` rows as cost.
+
 - **One turn at a time.** `send()` claims the session's turn slot at once. A second `send()` while a turn runs throws `AGENT_SESSION_BUSY`. The returned iterable is single-use, and the turn starts on its first `next()`. Breaking out of the loop cancels the turn.
-- **Events.** `turn_start`, `text_delta`, `thinking_delta`, `stream_reset`, `tool_call`, `tool_result`, `approval_requested`, `approval_resolved`, `question`, `usage`, `compaction` and `turn_end`. In 0.2.0 sessions do not compact, so `compaction` is not emitted and a conversation that outgrows the model's context window ends `errored`. Each carries `sessionId`, `turnId`, `at` and your `metadata`. `turn_end` is always last, and a failed turn arrives as `turn_end`, never as a throw.
+- **Events.** `turn_start`, `text_delta`, `thinking_delta`, `stream_reset`, `tool_call`, `tool_result`, `approval_requested`, `approval_resolved`, `question`, `usage`, `compaction` and `turn_end`. Sessions do not compact, so `compaction` is not emitted and a conversation that outgrows the model's context window ends `errored`. Each carries `sessionId`, `turnId`, `at` and your `metadata`. `turn_end` is always last, and a failed turn arrives as `turn_end`, never as a throw.
 - **Deltas are provisional.** `stream_reset` means the deltas of that round so far are void: the provider call was retried after a transient fault (up to 3 attempts; a rate-limit retry waits the provider's `retryAfter` silently, and `cancel()` ends the wait). `turn_end.output` and the stored transcript are authoritative. While your consumer lags, adjacent deltas are merged; control events are never merged or dropped.
 - **Approvals and questions.** Answer them with `session.answer(requestId, { decision: "allow" | "deny" })` or `{ text }`. An unanswered one is denied after `approvalTimeoutMs` (default 600000, range 30000..3600000). `answer` returns `"accepted"`, `"expired"`, `"cancelled"` or `"unknown"`.
-- **Profiles.** `none` gives your tools, a private scratchpad and `ask_human`. `read` adds Read, Glob, Grep and read-only Git over `workdir`. `full` adds writes and Bash, under the OS sandbox and `bashApproval` (default `"gated"`: every command is put to the person).
 - **Credentials.** A session's `credentials` (`memory` or `exec`) and `catalogOverrides` give it its own client. Without them it uses the process-wide `configureCredentials` slot.
-- **History and restarts.** The store holds one document per session, saved at the end of every turn. `close()` keeps it. After a restart, `resumeAgentSession(sessionId, options)` reopens it with the same options you created it with; pass `instructions` and `tools` again, since they are not stored. If the process died mid-turn, `session.lastTurn` is `{ turnId, status: "interrupted" }`, and that turn's message is not in history. A resume with a different model throws `AGENT_SESSION_MODEL_MISMATCH`; a different reasoning effort (`[high]`) is the same model. Do not open one session id twice at once: the store has no lock.
-- **Errors.** Every error is an `AgentSessionError` with a code `AGENT_SESSION_*`: `INVALID_OPTIONS`, `EXISTS`, `BUSY`, `CLOSED`, `INVALID_ANSWER`, `NOT_FOUND`, `SCHEMA_UNSUPPORTED`, `MODEL_MISMATCH`, `SANDBOX_UNAVAILABLE` or `TOOL_NAME_RESERVED`. A stored document that cannot be read is a `NaxError` with `TRANSCRIPT_CORRUPT`.
+- **History and restarts.** The store holds one document per session, saved at the end of every turn. `close()` keeps it. After a restart, `resumeAgentSession(sessionId, options)` reopens it with the same options you created it with; pass `instructions` and `tools` again, since they are not stored. If the process died mid-turn, `session.lastTurn` is `{ turnId, status: "interrupted" }`, and that turn's message is not in history. A resume with a different model throws `AGENT_SESSION_MODEL_MISMATCH`; a different reasoning effort (`[high]`) is the same model. Resuming with a different backend kind throws `AGENT_SESSION_BACKEND_MISMATCH`; a stored document with no `backend` field is native. Do not open one session id twice at once: the store has no lock.
+- **Errors.** Every error is an `AgentSessionError` with a code `AGENT_SESSION_*`: `INVALID_OPTIONS`, `EXISTS`, `BUSY`, `CLOSED`, `INVALID_ANSWER`, `NOT_FOUND`, `SCHEMA_UNSUPPORTED`, `MODEL_MISMATCH`, `SANDBOX_UNAVAILABLE`, `TOOL_NAME_RESERVED`, `BACKEND_UNAVAILABLE`, `AUTH_REQUIRED`, `CAPABILITY_UNSUPPORTED` or `BACKEND_MISMATCH`. A stored document that cannot be read is a `NaxError` with `TRANSCRIPT_CORRUPT`.
 
 ## Status and roadmap
 
-`0.x` may reshape `.` with a minor bump. An ACP backend for the same session API is planned. See [`CHANGELOG.md`](CHANGELOG.md).
+`0.x` may reshape `.` with a minor bump. `@nathapp/nax-agent-acp` provides an ACP backend for the same API (0.3.0). See [`CHANGELOG.md`](CHANGELOG.md).
 
 Maintainers: see the [release procedure](https://github.com/nathapp-io/nax/blob/main/packages/nax-agent/RELEASING.md)
 for the manual 0.1.0 publish and OTP step, trusted-publisher setup and subsequent tagged releases.

package/dist/index.d.ts

@@ -12,24 +12,34 @@ export { appendCommandSafetyRow, type BuildCommandShadowOptions, buildCommandSha
 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 { configureCredentials, getLogger, setAgentLogger } from "#src/infra/index";
+export { createStderrTail, type StderrTail } from "#src/infra/stderr-tail";
+export { isProcessAlive } from "#src/internal/process-alive";
+export { killProcessGroup } from "#src/internal/process-kill";
+export { capStrings, redactSecrets } from "#src/internal/redact";
+export { NaxError } from "#src/infra/nax-error";
 export type { CredentialSource } from "#src/native/credentials/session-source";
-export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, 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, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
+export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, 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, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
 export type { NativeSessionAdapterOptions } from "#src/native/session-adapter";
 export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToolPayload, BeforeCompactionPatch, BeforeCompactionPayload, BeforeRequestPatch, BeforeRequestPayload, BeforeToolOutcome, BeforeToolPayload, BeforeTurnEndPatch, BeforeTurnEndPayload, BeforeTurnPatch, BeforeTurnPayload, CompleteCallOptions, ExternalHandlerOf, LoopEvent, LoopEventMap, LoopHandlerContext, LoopHandlerEntry, LoopHandlerSet, PatchOf, PayloadOf, TransformContextPatch, TransformContextPayload, } from "#src/native/session/loop-events/types";
-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 { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_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 { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 export { AgentSessionError, type AgentSessionErrorCode } from "#src/session/agent-session-errors";
-export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
+export type { AgentSession, AgentSessionHostPorts, AgentSessionProfile, AnswerReply, AnswerStatus, ApprovalDecidedBy, CostSource, CreateAgentSessionOptions, EmbedderTool, EmbedderToolContext, EmbedderToolResult, SessionEvent, SessionEventBase, SessionEventBody, TurnEndStatus, } from "#src/session/agent-session-types";
 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 { nativeBackend } from "#src/session/native-backend";
+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

@@ -10,15 +10,23 @@
 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 { configureCredentials, getLogger, setAgentLogger } from "#src/infra/index";
+export { createStderrTail } from "#src/infra/stderr-tail";
+export { isProcessAlive } from "#src/internal/process-alive";
+export { killProcessGroup } from "#src/internal/process-kill";
+export { capStrings, redactSecrets } from "#src/internal/redact";
+export { NaxError } from "#src/infra/nax-error";
 export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, 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 { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_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 { createAgentSession, resumeAgentSession } from "#src/session/agent-session";
 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/infra/stderr-tail.d.ts

@@ -0,0 +1,8 @@
+export interface StderrTail {
+    push(chunk: string | Uint8Array): void;
+    excerpt(opts?: {
+        readonly maxBytes?: number;
+        readonly secrets?: readonly string[];
+    }): string;
+}
+export declare function createStderrTail(capacityBytes?: number): StderrTail;

package/dist/infra/stderr-tail.js

@@ -0,0 +1,48 @@
+/**
+ * A bounded tail of a child process's stderr (S4 spec 5.6, 7). Backends keep
+ * the last bytes for error excerpts; excerpt() strips control characters,
+ * redacts caller-known secrets and known token shapes, and returns at most
+ * maxBytes from the end, so an error never carries a raw agent log.
+ */
+import { redactSecrets } from "#src/internal/redact";
+const DEFAULT_CAPACITY = 65_536;
+const DEFAULT_EXCERPT = 4096;
+const MIN_SECRET_LENGTH = 4;
+// C0 controls and DEL, except tab (\u0009) and newline (\u000A).
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point of this regex
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F]/g;
+function lastBytes(text, maxBytes) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    // A cut inside a multi-byte character decodes to U+FFFD; drop it.
+    return bytes
+        .subarray(bytes.byteLength - maxBytes)
+        .toString("utf8")
+        .replace(/^�+/, "");
+}
+function scrub(text, secrets) {
+    let out = text.replace(CONTROL, "");
+    for (const secret of secrets) {
+        if (secret.length >= MIN_SECRET_LENGTH)
+            out = out.split(secret).join("[REDACTED]");
+    }
+    return redactSecrets(out);
+}
+export function createStderrTail(capacityBytes = DEFAULT_CAPACITY) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    return {
+        push(chunk) {
+            buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+            // Known limitation: trimming at the raw capacity boundary can cut a
+            // caller secret in two, leaving the older half as a suffix in the buffer;
+            // excerpt() redacts only whole occurrences it sees. Capacity semantics are
+            // deliberate and stay as they are.
+            buffer = lastBytes(buffer, capacityBytes);
+        },
+        excerpt(opts = {}) {
+            return lastBytes(scrub(buffer, opts.secrets ?? []), opts.maxBytes ?? DEFAULT_EXCERPT);
+        },
+    };
+}

package/dist/native/index.d.ts

@@ -21,7 +21,7 @@ export { type ResolveResult, type ResolveStatus, resolveNativeId, } from "./mode
 export { NATIVE_AGENT } from "./models.ts";
 export { createMemoryTranscriptStore, type MemoryTranscriptStore } from "./session/memory-transcript-store.ts";
 export { createFileTranscriptStore, MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.ts";
-export type { TranscriptDoc, TranscriptStore, TurnMarker } from "./session/transcript-types.ts";
+export type { TranscriptAcpRecord, TranscriptDoc, TranscriptStore, TurnMarker } from "./session/transcript-types.ts";
 export { NativeSessionAdapter } from "./session-adapter.ts";
 export { newSessionKey } from "./session-affinity.ts";
 export { type NativeTierConfig, nativeTierProviders } from "./tier-providers.ts";

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

@@ -10,9 +10,25 @@ export interface TurnMarker {
     readonly turnId: string;
     readonly state: "running" | "ended";
 }
+/** An ACP backend's record of the agent-side session (S4 spec 5.5). */
+export interface TranscriptAcpRecord {
+    readonly agentSessionId: string;
+    readonly agent: string;
+    readonly agentVersion?: string;
+    readonly cwd: string;
+    /**
+     * The agent's cumulative cost reading (USD) at the end of the session's last
+     * priced turn. A resumed ACP session measures its next turn's cost from it,
+     * because the agent's running total survives a resume (S4-6 D6-a).
+     */
+    readonly costUsd?: number;
+}
 export interface TranscriptDoc {
     /** Absent means 1. nax-agent does not write it in S3-1. */
     readonly schemaVersion?: 1;
+    /** Absent means "native". */
+    readonly backend?: string;
+    readonly acp?: TranscriptAcpRecord;
     readonly owner?: string;
     readonly model?: string;
     readonly savedAt: string;

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/permissions/ask-chain.d.ts

@@ -14,7 +14,7 @@ import type { AskRequest } from "./types.ts";
 /** A link's answer. `abstain` means "no opinion, try the next link". */
 export type AskDecision = "allow" | "deny" | "abstain";
 /** Who actually decided. Carried into the ledger so it never has to be inferred. */
-export type AskDecidedBy = "cache" | "model" | "human" | "timeout" | "unavailable" | "cancelled" | "unshowable";
+export type AskDecidedBy = "cache" | "model" | "human" | "timeout" | "unavailable" | "cancelled" | "unshowable" | "profile";
 /**
  * Per-ask control (US-003), carried SEPARATELY from the `AskRequest` so the
  * request the ledger records stays the pure request and a resolver can react

package/dist/permissions/ask.d.ts

@@ -14,6 +14,12 @@ export declare const ASK_DENIED_REASON = "matched an ask rule requiring human ap
  */
 export declare const ASK_CANCELLED_REASON = "Not run: the turn was cancelled before anyone answered.";
 export declare const ASK_UNSHOWABLE_REASON = "Not run: the command contains a secret that cannot be shown to the approver safely; pass it through an environment variable instead.";
+/**
+ * The session profile's own policy refused the call (for example a tool the
+ * profile's ask rules put to a resolver that the profile itself denied). No
+ * person was asked and nobody timed out.
+ */
+export declare const ASK_PROFILE_REASON = "denied by the session profile's policy";
 /** Kept for compatibility with existing callers and tests. */
 export declare const ASK_UNAVAILABLE_REASON = "matched an ask rule requiring human approval; no approval channel is configured for this run, so the call is refused";
 /**

package/dist/permissions/ask.js

@@ -14,6 +14,12 @@ export const ASK_DENIED_REASON = "matched an ask rule requiring human approval;
  */
 export const ASK_CANCELLED_REASON = "Not run: the turn was cancelled before anyone answered.";
 export const ASK_UNSHOWABLE_REASON = "Not run: the command contains a secret that cannot be shown to the approver safely; pass it through an environment variable instead.";
+/**
+ * The session profile's own policy refused the call (for example a tool the
+ * profile's ask rules put to a resolver that the profile itself denied). No
+ * person was asked and nobody timed out.
+ */
+export const ASK_PROFILE_REASON = "denied by the session profile's policy";
 /** Kept for compatibility with existing callers and tests. */
 export const ASK_UNAVAILABLE_REASON = ASK_NO_CHANNEL_REASON;
 /**

package/dist/permissions/index.d.ts

@@ -2,7 +2,7 @@ export * from "./approval-audit.ts";
 export * from "./approvals-link.ts";
 export * from "./approvals-store.ts";
 export * from "./approvals-taint.ts";
-export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.ts";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.ts";
 export * from "./ask-chain.ts";
 export type { BashLexResult, BashRedirect, BashSegment, BashSegmentSeparator, BashToken } from "./bash-lex.ts";
 export { lexBashCommand } from "./bash-lex.ts";

package/dist/permissions/index.js

@@ -2,7 +2,7 @@ export * from "./approval-audit.js";
 export * from "./approvals-link.js";
 export * from "./approvals-store.js";
 export * from "./approvals-taint.js";
-export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.js";
+export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, headlessAskResolver, } from "./ask.js";
 export * from "./ask-chain.js";
 export { lexBashCommand } from "./bash-lex.js";
 export { parseRuleList, parseToolExpression } from "./grammar.js";

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";
+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-options.d.ts

@@ -1,15 +1,11 @@
-import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { CreateAgentSessionOptions, EmbedderTool } from "./agent-session-types.ts";
 export declare const DEFAULT_APPROVAL_TIMEOUT_MS = 600000;
 export declare const DEFAULT_TURN_TIMEOUT_SECONDS = 3600;
 export interface ResolvedAgentSessionOptions {
     /** The caller's object, unchanged (tool objects keep their `this`). */
     readonly raw: CreateAgentSessionOptions;
-    readonly provider: string;
     readonly approvalTimeoutMs: number;
     readonly turnTimeoutSeconds: number;
-    readonly bashApproval: BashApprovalMode;
-    readonly allowUnsandboxed: boolean;
     readonly metadata: Readonly<Record<string, string>>;
     readonly tools: readonly EmbedderTool[];
 }

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

@@ -1,11 +1,12 @@
 /**
- * Validates createAgentSession's options (spec 4.1, 7). zod checks the shape;
- * the result keeps the caller's own objects (zod returns copies, which would
- * detach a class-based tool's methods from `this`).
+ * Validates createAgentSession's shared options (spec 4.1, 7): the backend
+ * plus the options every backend reads. Native-only options live on
+ * `nativeBackend` (S4). zod checks the shape; the result keeps the caller's
+ * own objects (zod returns copies, which would detach a class-based tool's
+ * methods from `this`).
  */
 import { isAbsolute } from "node:path";
 import { z } from "zod";
-import { parseNativeModel } from "#src/native/models";
 import { ASK_HUMAN_TOOL_NAME } from "#src/native/session/ask-human";
 import { RESERVED_TOOL_NAMES } from "#src/tools/registry";
 import { AgentSessionError } from "./agent-session-errors.js";
@@ -21,7 +22,6 @@ function hasMethods(names) {
     return (value) => isRecord(value) && names.every((name) => typeof value[name] === "function");
 }
 const isFunction = (value) => typeof value === "function";
-const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const EmbedderToolSchema = z.object({
     name: z.string().regex(TOOL_NAME, "must be a letter, then letters, digits, _ or -, at most 64 characters"),
     description: z.string().min(1),
@@ -31,13 +31,12 @@ const EmbedderToolSchema = z.object({
     run: z.custom(isFunction, "must be a function"),
 });
 const OptionsSchema = z.strictObject({
-    backend: z.literal("native"),
+    backend: z.custom((value) => isRecord(value) && typeof value.kind === "string" && value.kind.length > 0 && typeof value.open === "function", "must be a SessionBackend (for example nativeBackend({ model }))"),
     sessionId: z
         .string()
         .regex(SESSION_ID, "must be 1-128 letters, digits, '.', '_' or '-', starting with a letter or digit")
         .optional(),
-    model: z.string().min(1),
-    profile: z.enum(["none", "read", "full"]),
+    profile: z.enum(["none", "read", "ask", "full"]),
     workdir: z
         .string()
         .refine((dir) => isAbsolute(dir), "must be an absolute path")
@@ -46,21 +45,6 @@ const OptionsSchema = z.strictObject({
     tools: z.array(EmbedderToolSchema).optional(),
     transcriptStore: z.custom(hasMethods(STORE_METHODS), `must implement ${STORE_METHODS.join(", ")}`),
     approvalTimeoutMs: z.number().int().min(30_000).max(3_600_000).optional(),
-    bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
-    allowUnsandboxed: z.boolean().optional(),
-    credentials: z
-        .custom((value) => isRecord(value) && (value.kind === "memory" || value.kind === "exec"), "must be a memory or exec source")
-        .optional(),
-    catalogOverrides: z.array(z.custom(isRecord, "must be a catalog override object")).optional(),
-    loopHandlers: z.array(z.custom(isRecord, "must be a loop handler entry")).optional(),
-    hostPorts: z
-        .strictObject({
-        protectedPaths: z
-            .custom((value) => isRecord(value) && isStringArray(value.gitExcludePathspecs) && isStringArray(value.gitIgnorePatterns), "must be a protected-paths policy with gitExcludePathspecs and gitIgnorePatterns string arrays")
-            .optional(),
-        commandInterceptor: z.custom(hasMethods(["intercept"]), "must implement intercept").optional(),
-    })
-        .optional(),
     metadata: z.record(z.string(), z.string()).optional(),
     turnTimeoutSeconds: z.number().int().min(1).max(86_400).optional(),
 });
@@ -73,11 +57,6 @@ function checkShape(input) {
             path: "mcpServers",
         });
     }
-    if (isRecord(input) && isRecord(input.hostPorts) && "runDeclaredCommand" in input.hostPorts) {
-        throw invalid("hostPorts.runDeclaredCommand is deferred to a later release", {
-            path: "hostPorts.runDeclaredCommand",
-        });
-    }
     const parsed = OptionsSchema.safeParse(input);
     if (parsed.success)
         return input;
@@ -89,15 +68,6 @@ function checkProfileRules(options) {
     if (options.profile !== "none" && options.workdir === undefined) {
         throw invalid(`workdir is required for profile "${options.profile}"`, { path: "workdir" });
     }
-    if (options.profile !== "full" && options.bashApproval !== undefined) {
-        throw invalid('bashApproval applies to profile "full" only', { path: "bashApproval" });
-    }
-    if (options.profile !== "full" && options.allowUnsandboxed !== undefined) {
-        throw invalid('allowUnsandboxed applies to profile "full" only', { path: "allowUnsandboxed" });
-    }
-    if (options.allowUnsandboxed === true && (options.bashApproval ?? "gated") !== "gated") {
-        throw invalid('allowUnsandboxed requires bashApproval "gated"', { path: "allowUnsandboxed" });
-    }
 }
 function checkToolNames(tools) {
     const reserved = new Set([...RESERVED_TOOL_NAMES, ASK_HUMAN_TOOL_NAME]);
@@ -111,14 +81,6 @@ function checkToolNames(tools) {
         seen.add(tool.name);
     }
 }
-function providerOf(model) {
-    try {
-        return parseNativeModel(model).provider;
-    }
-    catch {
-        throw invalid(`model: "${model}" is not "provider/model[effort]"`, { path: "model" });
-    }
-}
 export function resolveAgentSessionOptions(input) {
     const options = checkShape(input);
     checkProfileRules(options);
@@ -126,11 +88,8 @@ export function resolveAgentSessionOptions(input) {
     checkToolNames(tools);
     return {
         raw: options,
-        provider: providerOf(options.model),
         approvalTimeoutMs: options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
         turnTimeoutSeconds: options.turnTimeoutSeconds ?? DEFAULT_TURN_TIMEOUT_SECONDS,
-        bashApproval: options.bashApproval ?? "gated",
-        allowUnsandboxed: options.allowUnsandboxed === true,
         metadata: options.metadata ?? {},
         tools,
     };

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

@@ -7,6 +7,8 @@ import type { CreateAgentSessionOptions } from "./agent-session-types.ts";
  */
 export declare function resumeInput(sessionId: string, options: CreateAgentSessionOptions): unknown;
 /** The stored document a resume starts from. Throws when there is none or this session may not read it. */
-export declare function loadResumable(store: TranscriptStore, sessionId: string, model: string): Promise<TranscriptDoc>;
+export declare function loadResumable(store: TranscriptStore, sessionId: string): Promise<TranscriptDoc>;
+/** The stored document's backend (absent means native) must be the resuming backend's (S4 spec 5.5). */
+export declare function checkBackendKind(doc: TranscriptDoc, sessionId: string, kind: string): void;
 /** The turn a dead process left running (spec 6.4), or undefined. */
 export declare function interruptedTurnOf(doc: TranscriptDoc): string | undefined;

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

@@ -2,11 +2,10 @@
  * resumeAgentSession's checks on the stored document (S3 spec 4.2, 6.4). They
  * run before any backend opens: the id comes from the argument, the document
  * exists, this build reads its schema, its messages are an array, and the
- * model that wrote it is the one resuming. The model rule is the loop's own
- * (transcriptModelIdentity): an effort suffix is not a different model.
+ * backend that wrote it is the one resuming (S4 spec 5.5). A backend's own
+ * model rule (an effort suffix is not a different model) runs in its `open`.
  */
 import { NaxError } from "#src/infra/nax-error";
-import { transcriptModelIdentity } from "#src/native/session/transcript-identity";
 import { AgentSessionError } from "./agent-session-errors.js";
 /**
  * The options to validate for a resume: the argument is the session id. A
@@ -22,7 +21,7 @@ export function resumeInput(sessionId, options) {
     return { ...options, sessionId };
 }
 /** The stored document a resume starts from. Throws when there is none or this session may not read it. */
-export async function loadResumable(store, sessionId, model) {
+export async function loadResumable(store, sessionId) {
     const doc = await store.load(sessionId);
     if (doc === null) {
         throw new AgentSessionError(`Session "${sessionId}" has no document in the transcript store`, "AGENT_SESSION_NOT_FOUND", { sessionId });
@@ -34,12 +33,15 @@ export async function loadResumable(store, sessionId, model) {
     if (!Array.isArray(doc.messages)) {
         throw new NaxError(`transcript for session "${sessionId}" is unreadable: messages is not an array`, "TRANSCRIPT_CORRUPT", { stage: "agent-session", sessionId });
     }
-    const resuming = transcriptModelIdentity(model);
-    if (doc.model !== undefined && doc.model !== resuming) {
-        throw new AgentSessionError(`Session "${sessionId}" was written by model "${doc.model}"; resume it with that model, not "${resuming}"`, "AGENT_SESSION_MODEL_MISMATCH", { sessionId });
-    }
     return doc;
 }
+/** The stored document's backend (absent means native) must be the resuming backend's (S4 spec 5.5). */
+export function checkBackendKind(doc, sessionId, kind) {
+    const stored = doc.backend ?? "native";
+    if (stored !== kind) {
+        throw new AgentSessionError(`Session "${sessionId}" was written by backend "${stored}"; it cannot be resumed with "${kind}"`, "AGENT_SESSION_BACKEND_MISMATCH", { sessionId, stored, kind });
+    }
+}
 /** The turn a dead process left running (spec 6.4), or undefined. */
 export function interruptedTurnOf(doc) {
     const turn = doc.turn;