@nathapp/nax-agent 0.1.0 → 0.2.0

package/dist/native/session/turn-tool-batch.js

@@ -22,7 +22,7 @@ import { withNudge } from "./nudge.js";
 import { buildToolResult } from "./tool-result.js";
 import { handleAskHumanCall } from "./turn-ask-human.js";
 export async function runToolBatch(args) {
-    const { toolCalls, tools, codingToolNames, roundTrips, opts, deps, loopEvents, invalidCallBudget, spinBreaker, maxInteractions, spinWarned, interactionsSoFar, } = args;
+    const { toolCalls, tools, codingToolNames, roundTrips, opts, deps, loopEvents, invalidCallBudget, spinBreaker, maxInteractions, spinWarned, interactionsSoFar, turnEvents, } = args;
     let messages = [...args.messages];
     const interactions = [];
     const codingToolsCalled = [];
@@ -124,7 +124,10 @@ export async function runToolBatch(args) {
                 // invalid-call repair's redacted call), written before the answer.
                 if (outcome.input !== undefined)
                     messages = rewriteToolCallInput(messages, call.id, outcome.input);
-                messages.push(buildToolResult({ toolCallId: call.id, content: outcome.content, isError: outcome.isError }));
+                turnEvents.toolCall(call, outcome.input);
+                const blocked = buildToolResult({ toolCallId: call.id, content: outcome.content, isError: outcome.isError });
+                messages.push(blocked);
+                turnEvents.toolResult(blocked);
                 continue;
             }
             // `allow` and `nudge` may rewrite the call's input; the rewritten value
@@ -138,6 +141,7 @@ export async function runToolBatch(args) {
             const kind = codingToolNames.has(call.name) ? "coding-tool" : "context-tool";
             if (kind === "coding-tool")
                 codingToolsCalled.push(call.name);
+            turnEvents.toolCall(call, rewritten);
             const answer = await opts.interactionHandler.onInteraction(kind === "coding-tool"
                 ? {
                     kind,
@@ -212,12 +216,14 @@ export async function runToolBatch(args) {
             });
             const finalContent = withNudge(nudgeText, patch.content ?? answerText);
             answer?.finalizeAudit?.(finalContent);
-            messages.push(buildToolResult({
+            const result = buildToolResult({
                 toolCallId: call.id,
                 content: finalContent,
                 isError: patch.isError,
                 denied: answer?.denied,
-            }));
+            });
+            messages.push(result);
+            turnEvents.toolResult(result);
             // The breaker observed the call through the seam, i.e. with whatever
             // input a handler rewrote in place — so the result has to be noted
             // against that same input, or the key misses and result-based
@@ -236,11 +242,13 @@ export async function runToolBatch(args) {
                 toolName: call.name,
                 callId: call.id,
             });
-            messages.push(buildToolResult({
+            const failed = buildToolResult({
                 toolCallId: call.id,
                 content: patch.content ?? errorText,
                 isError: patch.isError ?? true,
-            }));
+            });
+            messages.push(failed);
+            turnEvents.toolResult(failed);
         }
     }
     return {

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

@@ -19,8 +19,11 @@ import type { SpinBreaker } from "#src/infra/spin-breaker/index";
 import type { TurnDeadline } from "#src/session/turn-deadline";
 import type { TranscriptMessage as NativeTranscriptMessage, ResolvedCompaction } from "./compaction.ts";
 import type { CompleteCallOptions, LoopEventRegistry, LoopHandlerContext, LoopHandlerSet } from "./loop-events/index.ts";
+import type { NativeSessionState } from "./session.ts";
 import type { toToolDefinitions } from "./tool-mapping.ts";
+import type { StreamDeltaSink } from "./turn-event-emitter.ts";
 import type { TurnRetryConfig } from "./turn-retry.ts";
+export type { StreamDelta, StreamDeltaSink } from "./turn-event-emitter.ts";
 export interface NativeTurnResponse {
     readonly text: string;
     readonly toolCalls?: readonly ToolCall[];
@@ -47,7 +50,15 @@ export interface NativeSummaryResponse {
     readonly rates?: PricingRates;
 }
 export interface TurnDeps {
-    complete(messages: readonly ConversationMessage[], tools: ReturnType<typeof toToolDefinitions>, options?: CompleteCallOptions): Promise<NativeTurnResponse>;
+    /** The owning adapter's per-session state (S3 spec 5.2). Required: there is no process-global fallback. */
+    readonly sessionState: NativeSessionState;
+    /**
+     * One round-trip model call. `onDelta` (S3-3) receives the call's text and
+     * thinking deltas as they stream. The loop builds it per attempt from the
+     * turn's emitter, already stamped with the round, and leaves it absent when
+     * the turn has no `onTurnEvent` sink. Fakes may ignore it.
+     */
+    complete(messages: readonly ConversationMessage[], tools: ReturnType<typeof toToolDefinitions>, options?: CompleteCallOptions, onDelta?: StreamDeltaSink): Promise<NativeTurnResponse>;
     /**
      * One model call, no tools, used only to summarize a dropped span. Separate
      * from complete() because it must not advertise tools, must not count as a
@@ -132,6 +143,11 @@ export interface TurnDeps {
      * `SendTurnOpts`. Read at dispatch, like the rest of the per-turn state.
      */
     loopHandlerContext?: LoopHandlerContext;
+    /**
+     * S3-3: the turn's event sink, forwarded from `SendTurnOpts`. `runNativeTurn`
+     * wraps it once in a `TurnEventEmitter`; nothing else calls it.
+     */
+    onTurnEvent?: import("#src/session/turn-event").TurnEventSink;
 }
 /**
  * nax#1840: round trips completed before a turn fails still spent real money.

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

@@ -2,14 +2,32 @@
  * The native session adapter: openSession / sendTurn / closeSession over
  * nax-ai, no subprocess. openSession/closeSession are transcript-file
  * bookkeeping, and sendTurn maps the native turn loop (session/turn-loop.ts)
- * over complete() — nax owns the conversation because nax-ai's client is
+ * over streamed model calls (`stream-complete.ts`; the compaction summary uses
+ * complete()) — nax owns the conversation because nax-ai's client is
  * stateless (ADR-027 section 10, ADR-028).
  */
 import { type AgentSessionAdapter, type OpenSessionOpts, type SendTurnOpts, type SessionHandle, type TurnResult } from "#src/session/session-types";
 import { type NativeCatalogOverrides } from "./client.ts";
+import { type CredentialSource } from "./credentials/session-source.ts";
+import { type NativeSessionState } from "./session/session.ts";
+/** The adapter's per-session state. `/internal` only: tests and the S3 facade read it; nax never does. */
+export declare function nativeSessionStateOf(adapter: NativeSessionAdapter): NativeSessionState;
+/** Options for an adapter that owns its client and/or its credentials (S3 5.2). */
+export interface NativeSessionAdapterOptions {
+    /** A credential source owned by this adapter. Implies an owned client. */
+    readonly credentials?: CredentialSource;
+    /** Build and own a client even without `credentials` (for per-session catalog overrides). */
+    readonly ownClient?: boolean;
+}
 export declare class NativeSessionAdapter implements AgentSessionAdapter {
     private readonly catalogOverrides;
-    constructor(catalogOverrides?: NativeCatalogOverrides);
+    private readonly ownStore;
+    private ownClient;
+    private readonly owns;
+    constructor(catalogOverrides?: NativeCatalogOverrides, options?: NativeSessionAdapterOptions);
+    /** The module memo for nax (one client per process, as before); an owned client for an embedder session. */
+    private client;
+    private get state();
     /**
      * Can this agent authenticate to at least one provider?
      *
@@ -46,8 +64,8 @@ export declare class NativeSessionAdapter implements AgentSessionAdapter {
      * stayed behind for the process lifetime.
      *
      * The ACP contract takes a handle string and closeNativeSession takes a
-     * SessionHandle, but the maps are keyed by the session-name string both
-     * carry, so clear by name rather than synthesising a handle.
+     * SessionHandle, but this adapter's state is keyed by the session-name string
+     * both carry, so clear by name rather than synthesising a handle.
      */
     closePhysicalSession(handle: string, _workdir?: string, _options?: {
         force?: boolean;

package/dist/native/session-adapter.js

@@ -2,23 +2,26 @@
  * The native session adapter: openSession / sendTurn / closeSession over
  * nax-ai, no subprocess. openSession/closeSession are transcript-file
  * bookkeeping, and sendTurn maps the native turn loop (session/turn-loop.ts)
- * over complete() — nax owns the conversation because nax-ai's client is
+ * over streamed model calls (`stream-complete.ts`; the compaction summary uses
+ * complete()) — nax owns the conversation because nax-ai's client is
  * stateless (ADR-027 section 10, ADR-028).
  */
 import { randomUUID } from "node:crypto";
 import { priceCall } from "#src/cost/core/index";
-import { getSafeLogger } from "#src/infra/index";
+import { getSafeLogger, NaxError } from "#src/infra/index";
 import { SessionTurnError, } from "#src/session/session-types";
 import { createTurnDeadline } from "#src/session/turn-deadline";
 import { _adapterDeps, authFields, isProtocolStreamError } from "./adapter-deps.js";
-import { getNativeClient } from "./client.js";
+import { _clientDeps, getNativeClient } from "./client.js";
+import { createSessionCredentialStore } from "./credentials/session-source.js";
 import { toAdapterFailure } from "./errors.js";
 import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
-import { closeNativeSession, markNativeTurnOutcome, nativeSessionCompaction, nativeSessionSpinBreaker, nativeSessionStreamHooks, nativeSessionTimeouts, nativeSessionTranscriptOwners, nativeSessionTransportRetry, openNativeSession, } from "./session/session.js";
+import { closeNativeSession, createNativeSessionState, markNativeTurnOutcome, openNativeSession, systemFieldFor, } from "./session/session.js";
 import { buildNativeStreamEvent } from "./session/turn-events.js";
 import { runNativeTurn } from "./session/turn-loop.js";
 import { readNativeTurnFailureUsage } from "./session/turn-types.js";
 import { nativeSessionId } from "./session-affinity.js";
+import { streamComplete } from "./stream-complete.js";
 /**
  * Fallback whole-turn budget when a session's timeout entry is missing.
  *
@@ -39,23 +42,57 @@ function summaryPrompt(previousSummary) {
         `rather than repeating or discarding it:\n\n${previousSummary}`);
 }
 /**
- * US-003: the plugin-contributed loop handlers a turn carries, in the shape
- * `runNativeTurn` takes them in. Built here rather than inline in `sendTurn`
- * because those two conditional spreads are what pushed that method past its
- * recorded cognitive complexity; each field is omitted entirely when the
- * caller supplied none, so a session that loaded no `loop-handlers` plugin
- * carries neither key.
+ * US-003: the per-turn inputs the adapter forwards verbatim into `TurnDeps`:
+ * the plugin-contributed loop handlers and the facts their handlers read, plus
+ * (S3-3) the turn's `onTurnEvent` sink. Built here rather than inline in
+ * `sendTurn` because those conditional spreads are what pushed that method past
+ * its recorded cognitive complexity; each field is omitted entirely when the
+ * caller supplied none, so a session that loaded no `loop-handlers` plugin and
+ * sets no sink carries none of these keys.
  */
-function loopHandlerDeps(opts) {
+function perTurnDeps(opts) {
     return {
         ...(opts.loopHandlers !== undefined ? { loopHandlers: opts.loopHandlers } : {}),
         ...(opts.loopHandlerContext !== undefined ? { loopHandlerContext: opts.loopHandlerContext } : {}),
+        ...(opts.onTurnEvent !== undefined ? { onTurnEvent: opts.onTurnEvent } : {}),
     };
 }
+const adapterStates = new WeakMap();
+/** The adapter's per-session state. `/internal` only: tests and the S3 facade read it; nax never does. */
+export function nativeSessionStateOf(adapter) {
+    const state = adapterStates.get(adapter);
+    if (state === undefined) {
+        throw new NaxError("NativeSessionAdapter has no session state", "NATIVE_SESSION_STATE_MISSING", {
+            stage: "native-session",
+        });
+    }
+    return state;
+}
 export class NativeSessionAdapter {
     catalogOverrides;
-    constructor(catalogOverrides = []) {
+    ownStore;
+    ownClient;
+    owns;
+    constructor(catalogOverrides = [], options = {}) {
         this.catalogOverrides = catalogOverrides;
+        adapterStates.set(this, createNativeSessionState());
+        this.ownStore = options.credentials !== undefined ? createSessionCredentialStore(options.credentials) : undefined;
+        this.owns = this.ownStore !== undefined || options.ownClient === true;
+    }
+    /** The module memo for nax (one client per process, as before); an owned client for an embedder session. */
+    client() {
+        if (!this.owns)
+            return getNativeClient(this.catalogOverrides);
+        this.ownClient ??= _clientDeps
+            .build(this.catalogOverrides, this.ownStore !== undefined ? { credentials: this.ownStore } : {})
+            .catch((err) => {
+            this.ownClient = undefined;
+            throw err;
+        });
+        return this.ownClient;
+    }
+    get state() {
+        return nativeSessionStateOf(this);
     }
     /**
      * Can this agent authenticate to at least one provider?
@@ -83,6 +120,8 @@ export class NativeSessionAdapter {
      */
     async hasCredentials() {
         try {
+            if (this.ownStore !== undefined)
+                return true;
             if (await _adapterDeps.authSourceIsExec())
                 return true;
             if ((await _adapterDeps.listStoredProviders()).length > 0)
@@ -94,16 +133,16 @@ export class NativeSessionAdapter {
         }
     }
     openSession(name, opts) {
-        return openNativeSession(name, opts);
+        return openNativeSession(this.state, name, opts);
     }
     async sendTurn(handle, prompt, opts) {
         const { provider, model, effort } = parseNativeModel(handle.modelDef?.model ?? "");
         const thinking = toThinkingLevel(effort);
-        const client = await getNativeClient(this.catalogOverrides);
+        const client = await this.client();
         const resolved = await client.model(provider, model);
         const catalog = client.pricing(resolved);
         const { rates, source: pricingSource } = buildRateCard(catalog, handle.modelDef?.pricing);
-        const storedTimeoutSeconds = nativeSessionTimeouts.get(handle.id);
+        const storedTimeoutSeconds = this.state.timeouts.get(handle.id);
         if (storedTimeoutSeconds === undefined) {
             getSafeLogger()?.warn("native-adapter", "session has no recorded timeout; falling back to the default budget", {
                 sessionName: handle.id,
@@ -114,20 +153,23 @@ export class NativeSessionAdapter {
         // Keyed on the session, so every turn of one conversation carries the same
         // id and the provider can keep its cache warm across them.
         const sessionId = nativeSessionId(handle.id);
+        // S3-4: the session's system prompt (facade `instructions`), or `{}`.
+        // Resolved here so the `complete` closure spreads it without a branch.
+        const systemField = systemFieldFor(this.state, handle.id);
         // One budget for the whole turn, not one per round-trip. Created here
         // because this is where `timeoutSeconds` is known; consulted by the loop.
         const deadline = createTurnDeadline(timeoutSeconds);
-        const hooks = nativeSessionStreamHooks.get(handle.id);
+        const hooks = this.state.streamHooks.get(handle.id);
         // One callId per turn, mirroring SpawnAcpSession.prompt(). `runId` is
         // backfilled by the runtime's forwarding closure, which is the only place
         // that knows it — see runtime/index.ts.
         const callId = randomUUID();
-        // The transcript/ledger join key, not a stream id. `nativeSessionTranscriptOwners`
+        // The transcript/ledger join key, not a stream id. `this.state.transcriptOwners`
         // is keyed on this same `handle.id` and already holds the session's
         // `transcriptOwner` (`scopeId ?? callId` from session-run-hop.ts). Omitted
         // entirely when the session declared no owner, so an absent key reads as
         // "unknown" rather than as a wrong one.
-        const owner = nativeSessionTranscriptOwners.get(handle.id);
+        const owner = this.state.transcriptOwners.get(handle.id);
         const eventBase = {
             callId,
             runId: "",
@@ -170,23 +212,24 @@ export class NativeSessionAdapter {
             // so a settled turn must drop its timer to avoid keeping it armed past
             // the turn boundary.
             result = await runNativeTurn(handle, prompt, opts, {
+                sessionState: this.state,
                 deadline,
                 contextWindow: resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow),
-                ...(nativeSessionCompaction.get(handle.id) !== undefined
-                    ? { compaction: nativeSessionCompaction.get(handle.id) }
+                ...(this.state.compaction.get(handle.id) !== undefined
+                    ? { compaction: this.state.compaction.get(handle.id) }
                     : {}),
-                ...(nativeSessionTransportRetry.get(handle.id) !== undefined
-                    ? { transportRetry: nativeSessionTransportRetry.get(handle.id) }
+                ...(this.state.transportRetry.get(handle.id) !== undefined
+                    ? { transportRetry: this.state.transportRetry.get(handle.id) }
                     : {}),
-                ...(nativeSessionSpinBreaker.get(handle.id) !== undefined
-                    ? { spinBreaker: nativeSessionSpinBreaker.get(handle.id) }
+                ...(this.state.spinBreakers.get(handle.id) !== undefined
+                    ? { spinBreaker: this.state.spinBreakers.get(handle.id) }
                     : {}),
                 ...(opts.loopEvents !== undefined ? { loopEvents: opts.loopEvents } : {}),
                 // US-003: the run's plugin-contributed loop handlers and the facts
                 // their handlers read travel the same way as `loopEvents` — both are
                 // per-turn inputs the loop installs onto its registry rather than
                 // state the adapter owns.
-                ...loopHandlerDeps(opts),
+                ...perTurnDeps(opts),
                 // US-002: the one per-turn signal threaded into the batch and the
                 // in-flight coding-tool runtime. When `opts.signal` and the watchdog
                 // and the deadline are all absent, `turnSignal` is a non-aborted
@@ -231,7 +274,7 @@ export class NativeSessionAdapter {
                             _adapterDeps.clearTimeout(timer);
                     }
                 },
-                complete: async (messages, tools, requestOptions) => {
+                complete: async (messages, tools, requestOptions, onDelta) => {
                     // The controller is armed with what is LEFT of the turn, so N
                     // round-trips can no longer add up to N x timeoutSeconds. Still
                     // combined with any caller-supplied opts.signal via AbortSignal.any so
@@ -250,10 +293,11 @@ export class NativeSessionAdapter {
                     // thinking LEVEL rather than a boolean, so normalize at this boundary.
                     const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
                     try {
-                        const res = await client.complete(resolved, {
+                        const res = await streamComplete(client, resolved, {
                             messages,
                             ...(tools.length > 0 ? { tools } : {}),
                             sessionId,
+                            ...systemField,
                             signal,
                             ...(requestThinking !== undefined ? { thinking: requestThinking } : {}),
                             ...(requestOptions?.temperature !== undefined ? { temperature: requestOptions.temperature } : {}),
@@ -268,7 +312,7 @@ export class NativeSessionAdapter {
                             // to reuse the entry, so a cache write there costs more than it
                             // saves.
                             cacheRetention: "short",
-                        });
+                        }, onDelta);
                         const usage = res.usage;
                         // Single `priceCall` invocation: `costUsd` and `resolvedRates`
                         // come from the same call so they cannot diverge — the
@@ -304,7 +348,7 @@ export class NativeSessionAdapter {
                 status: turnController.signal.aborted ? "cancelled" : "error",
                 timestamp: Date.now(),
             });
-            markNativeTurnOutcome(handle.id, true);
+            markNativeTurnOutcome(this.state, handle.id, true);
             // The same treatment complete() gives a protocol fault, on the path that
             // was missing it (nax#1838). Rethrowing untouched left build-hop-callback
             // to synthesise a generic fail-adapter-error, which cost a rate limit its
@@ -340,17 +384,17 @@ export class NativeSessionAdapter {
             status: result.timedOut === true ? "timeout" : turnController.signal.aborted ? "cancelled" : "success",
             timestamp: Date.now(),
         });
-        markNativeTurnOutcome(handle.id, false);
+        markNativeTurnOutcome(this.state, handle.id, false);
         // US-006: the store only observes `provider` while a request is in flight,
         // so the stamp is read here, after the loop.
-        return { ...result, ...authFields(provider) };
+        return { ...result, ...authFields(provider, this.ownStore) };
     }
     closeSession(handle) {
         // The adapter interface has no failure signal, so the verdict comes from the
         // session's last turn (markNativeTurnOutcome) rather than from this call.
         // Passing a literal false here is what deleted the transcript of a failed
         // session -- the one the retry reloads and a human reads (nax#1838).
-        return closeNativeSession(handle);
+        return closeNativeSession(this.state, handle);
     }
     /**
      * Run teardown addresses a session the process no longer has a handle for,
@@ -360,10 +404,10 @@ export class NativeSessionAdapter {
      * stayed behind for the process lifetime.
      *
      * The ACP contract takes a handle string and closeNativeSession takes a
-     * SessionHandle, but the maps are keyed by the session-name string both
-     * carry, so clear by name rather than synthesising a handle.
+     * SessionHandle, but this adapter's state is keyed by the session-name string
+     * both carry, so clear by name rather than synthesising a handle.
      */
     async closePhysicalSession(handle, _workdir, _options) {
-        return closeNativeSession({ id: handle, agentName: NATIVE_AGENT });
+        return closeNativeSession(this.state, { id: handle, agentName: NATIVE_AGENT });
     }
 }

package/dist/native/stream-complete.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One streamed model call (S3 spec 5.3, R7).
+ *
+ * nax-ai's `Client.complete()` is `collectStream(streamFrom(...))`, so the wire
+ * was always a stream; this calls the same `stream()` and folds it with the
+ * same `collectStream`, tapping text and thinking deltas on the way. The fold
+ * is deliberately not reimplemented: last-usage-wins, the required `done` and
+ * `ProtocolStreamError` on an `error` event are what the turn loop's retry and
+ * overflow classifiers key on.
+ *
+ * `async` on purpose: `client.stream()` throws synchronously on an invalid
+ * header or session id, and an async function turns that into a rejection,
+ * exactly as `complete()` does. Without `onDelta` there is no tap at all.
+ */
+import { type Client, type ClientRequest, type CompleteResult, type ResolvedModel } from "@nathapp/nax-ai";
+import type { StreamDeltaSink } from "./session/turn-types.ts";
+export declare function streamComplete(client: Client, model: ResolvedModel, req: ClientRequest, onDelta?: StreamDeltaSink): Promise<CompleteResult>;

package/dist/native/stream-complete.js

@@ -0,0 +1,40 @@
+/**
+ * One streamed model call (S3 spec 5.3, R7).
+ *
+ * nax-ai's `Client.complete()` is `collectStream(streamFrom(...))`, so the wire
+ * was always a stream; this calls the same `stream()` and folds it with the
+ * same `collectStream`, tapping text and thinking deltas on the way. The fold
+ * is deliberately not reimplemented: last-usage-wins, the required `done` and
+ * `ProtocolStreamError` on an `error` event are what the turn loop's retry and
+ * overflow classifiers key on.
+ *
+ * `async` on purpose: `client.stream()` throws synchronously on an invalid
+ * header or session id, and an async function turns that into a rejection,
+ * exactly as `complete()` does. Without `onDelta` there is no tap at all.
+ */
+import { collectStream, } from "@nathapp/nax-ai";
+function deltaOf(event) {
+    if (event.type === "text-delta")
+        return { type: "text_delta", text: event.text };
+    if (event.type === "thinking-delta")
+        return { type: "thinking_delta", text: event.text };
+    return undefined;
+}
+async function* tap(events, onDelta) {
+    for await (const event of events) {
+        const delta = deltaOf(event);
+        if (delta !== undefined) {
+            try {
+                onDelta(delta);
+            }
+            catch {
+                // A display sink must not break the call; the emitter already logs its own failures.
+            }
+        }
+        yield event;
+    }
+}
+export async function streamComplete(client, model, req, onDelta) {
+    const events = client.stream(model, req);
+    return collectStream(onDelta === undefined ? events : tap(events, onDelta));
+}

package/dist/permissions/approvals-link.js

@@ -2,10 +2,11 @@
  * The approvals cache as the FIRST link of the ask chain (P2 design 4.3, 6.6).
  *
  * TRUST BOUNDARY. Living outside repoRoot protects this file from the TYPED
- * path-bearing tools, but NOT from Bash: nax-owned-writes.ts:52-58 excludes
- * Bash by design, and under `raw` mode screenRawBashCommand's protectedHit
- * skips every path outside the root (policy-bash-raw.ts:84), so the file is
- * never screened. A raw shell can forge entries.
+ * path-bearing tools, but NOT from Bash: the `OwnedPathsPolicy` port's
+ * `writeRefusal` (`tools/owned-paths.ts`) excludes
+ * Bash by design, and under `raw` mode screenRawBashCommand's owned-path
+ * candidates skip every path outside the root (policy-bash-raw.ts), so the
+ * file is never screened. A raw shell can forge entries.
  *
  * That is not a new vulnerability -- a raw shell needs no forged permission to
  * run a command -- but it IS a cross-stage escalation in a MIXED-mode run,

package/dist/sandbox/policy-builder.d.ts

@@ -1,4 +1,5 @@
 import { type SandboxConfig } from "../config/schemas-sandbox.ts";
+import type { OwnedPathsPolicy } from "../tools/owned-paths.ts";
 import type { GitLayout } from "./policy-inputs.ts";
 import type { SandboxPolicy } from "./types.ts";
 export interface SandboxPolicyInput {
@@ -6,8 +7,12 @@ export interface SandboxPolicyInput {
     readonly git: GitLayout;
     /** Redirecting git files present now, every worktree included (listGitGuardFiles, #2198). */
     readonly gitGuardFiles: readonly string[];
-    /** Top-level entry names under `<root>/.nax` right now (listNaxEntries). */
+    /** Top-level entry names under `<root>/<projectStateDir>` right now (listNaxEntries). */
     readonly naxEntries: readonly string[];
+    /** S3-2: host-owned path rules; supplies the always-denied project-state entries and root files. */
+    readonly ownedPaths: OwnedPathsPolicy;
+    /** Project-relative state directory (ProtectedPathsPolicy.projectStateDir); absent: no project-state denies. */
+    readonly projectStateDir?: string;
     readonly credentialFiles: readonly string[];
     readonly approvalsFile?: string;
     /** US-006 — the trust store (`trustStorePath()`), denied so a command cannot rewrite its own trust. */

package/dist/sandbox/policy-builder.js

@@ -10,7 +10,6 @@ import { isAbsolute, join, resolve } from "node:path";
 import { NaxError } from "#src/infra/index";
 import { realOrRaw } from "#src/internal/realpath";
 import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
-import { NAX_ALWAYS_DENIED_ENTRIES, NAX_SCRATCHPAD_ENTRY, naxWriteOptIns, QUEUE_CONTROL_FILES, } from "../tools/nax-owned-writes.js";
 import { BUILTIN_CACHE_WRITE_ROOTS, BUILTIN_CREDENTIAL_READ_DENIES, MACOS_CACHE_WRITE_ROOT, SRT_MACOS_TMPDIR, SRT_MACOS_TMPDIR_DENIES, } from "./defaults.js";
 import { WORKTREE_COMMON_WRITE_DIRS, WORKTREE_CONFIG_FILE } from "./git-guards.js";
 function expandHome(p, home) {
@@ -62,13 +61,15 @@ function worktreeGitWriteRoots(git) {
     return [git.gitDir, ...WORKTREE_COMMON_WRITE_DIRS.map((dir) => join(git.commonDir, dir))];
 }
 /**
- * nax#2260: every top-level `.nax/` entry, whole, plus the ones nax reads even
- * when absent -- except the scratchpad and entries opted in via allowWrite.
- * srt applies deny over allow and on Linux turns every literal deny into a
- * bind mount, so whole entries (one `features` deny, not one per PRD) keep
- * both the protection and the per-command cost bounded.
+ * nax#2260: every top-level project-state entry, whole, plus the ones the host
+ * loads even when absent (`ownedPaths.deniedEntries`) -- except the scratchpad
+ * and entries opted in via allowWrite. The ENTRIES come from the owned-paths
+ * port; the DIRECTORY comes from `projectStateDir`, and its absence denies
+ * nothing. srt applies deny over allow and on Linux turns every literal deny
+ * into a bind mount, so whole entries (one `features` deny, not one per PRD)
+ * keep both the protection and the per-command cost bounded.
  *
- * Only `<root>/.nax` is covered. A monorepo package's own `.nax/`
+ * Only `<root>/<projectStateDir>` is covered. A monorepo package's own `.nax/`
  * (`packages/<pkg>/.nax/`) is deliberately excluded: what lives there --
  * cache/, scratchpad/, status.json, the features' acceptance tests and run
  * artifacts -- is gitignored and rebuilt or regenerated, so deleting it is
@@ -77,11 +78,14 @@ function worktreeGitWriteRoots(git) {
  * into prompts; covering it needs package discovery, because a `.nax/` at any
  * depth also matches test-fixture projects (`test/fixtures/<p>/.nax/`).
  */
-function naxDenies(root, entries, allowWrite) {
-    const optIns = naxWriteOptIns(root, allowWrite);
-    return [...new Set([...entries, ...NAX_ALWAYS_DENIED_ENTRIES])]
-        .filter((name) => name !== NAX_SCRATCHPAD_ENTRY && !optIns.has(name))
-        .map((name) => join(root, ".nax", name));
+function projectStateDenies(input) {
+    const { root, projectStateDir, ownedPaths } = input;
+    if (projectStateDir === undefined)
+        return [];
+    const optIns = ownedPaths.writeOptIns(root, input.config.filesystem.allowWrite);
+    return [...new Set([...input.naxEntries, ...ownedPaths.deniedEntries])]
+        .filter((name) => name !== ownedPaths.scratchpadEntry && !optIns.has(name))
+        .map((name) => join(root, projectStateDir, name));
 }
 export function buildSandboxPolicy(input) {
     const { root, home, config } = input;
@@ -131,8 +135,8 @@ export function buildSandboxPolicy(input) {
         }),
     ]);
     const denyWrite = literal([
-        ...naxDenies(root, input.naxEntries, config.filesystem.allowWrite),
-        ...[...QUEUE_CONTROL_FILES].map((name) => join(root, name)),
+        ...projectStateDenies(input),
+        ...input.ownedPaths.rootWriteDenies.map((name) => join(root, name)),
         ...gitDenies(root, input.git),
         ...input.gitGuardFiles,
         ...(input.approvalsFile !== undefined ? [input.approvalsFile] : []),

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

@@ -0,0 +1,12 @@
+/** Undelivered control events a turn may queue before it is cancelled as stalled (spec 4.4). */
+export declare const MAX_UNDELIVERED_CONTROL_EVENTS = 1000;
+export declare const _agentSessionDeps: {
+    now: () => number;
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+    randomUUID: () => string;
+    isDirectory: (path: string) => Promise<boolean>;
+    makeScratchRoot: () => Promise<string>;
+    removeScratchRoot: (dir: string) => Promise<void>;
+    controlEventCap: number;
+};

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

@@ -0,0 +1,28 @@
+/**
+ * Injectable clock, timers, ids and filesystem for the agent session facade.
+ * Tests replace members (paired with withDepsRestore) to fire deadlines
+ * without sleeping and to lower the control-event cap. Exported on ./internal.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Undelivered control events a turn may queue before it is cancelled as stalled (spec 4.4). */
+export const MAX_UNDELIVERED_CONTROL_EVENTS = 1000;
+export const _agentSessionDeps = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    randomUUID: () => randomUUID(),
+    isDirectory: async (path) => {
+        try {
+            return (await stat(path)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    makeScratchRoot: () => mkdtemp(join(tmpdir(), "nax-agent-session-")),
+    removeScratchRoot: (dir) => rm(dir, { recursive: true, force: true }),
+    controlEventCap: MAX_UNDELIVERED_CONTROL_EVENTS,
+};

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

@@ -0,0 +1,11 @@
+/**
+ * The agent session facade's public error (S3 spec section 7). Every code is
+ * namespaced AGENT_SESSION_* so it cannot collide with nax's SESSION_* codes
+ * 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 declare class AgentSessionError extends NaxError {
+    readonly code: AgentSessionErrorCode;
+    constructor(message: string, code: AgentSessionErrorCode, context?: Record<string, unknown>);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The agent session facade's public error (S3 spec section 7). Every code is
+ * namespaced AGENT_SESSION_* so it cannot collide with nax's SESSION_* codes
+ * or registerCodingTool's TOOL_NAME_RESERVED.
+ */
+import { NaxError } from "#src/infra/nax-error";
+export class AgentSessionError extends NaxError {
+    constructor(message, code, context = {}) {
+        super(message, code, { stage: "agent-session", ...context });
+        this.name = "AgentSessionError";
+    }
+}