@nathapp/nax-agent 0.91.7 → 0.91.8-canary.2

package/dist/sandbox/srt-backend.js

@@ -52,7 +52,6 @@ function customConfig(policy) {
 export function createSrtBackend(network) {
     let initialized;
     let loaded;
-    let inFlight = 0;
     function initialize() {
         initialized ??= (async () => {
             const mod = await _srtBackendDeps.load();
@@ -75,15 +74,9 @@ export function createSrtBackend(network) {
         },
         async wrap(req) {
             const mod = await initialize();
-            inFlight += 1;
-            try {
-                const { argv } = await mod.SandboxManager.wrapWithSandboxArgv(req.command, req.shell, customConfig(req.policy), undefined, req.cwd, { commandId: req.commandId });
-                return argv;
-            }
-            catch (err) {
-                inFlight -= 1;
-                throw err;
-            }
+            // A wrap that throws undoes srt's own count, so it needs no cleanup call.
+            const { argv } = await mod.SandboxManager.wrapWithSandboxArgv(req.command, req.shell, customConfig(req.policy), undefined, req.cwd, { commandId: req.commandId });
+            return argv;
         },
         annotate(commandId, stderr) {
             if (loaded === undefined)
@@ -92,18 +85,18 @@ export function createSrtBackend(network) {
             return annotated.startsWith(stderr) ? annotated.slice(stderr.length).trim() : "";
         },
         commandFinished() {
-            inFlight = Math.max(0, inFlight - 1);
-            // Removes bwrap mount placeholders (Linux). Never while another wrapped
-            // command runs: a running sandbox may still depend on them.
-            if (inFlight === 0)
-                loaded?.SandboxManager.cleanupAfterCommand();
+            // Removes bwrap mount placeholders (Linux: `.bashrc`, `.profile`,
+            // `.claude/commands`, ...). srt counts every wrap itself and defers the
+            // deletion while another wrapped command still runs, so it must hear about
+            // EVERY finished command. A second, nax-side gate here leaked srt's count
+            // after any overlap and left the placeholders in the user's directory.
+            loaded?.SandboxManager.cleanupAfterCommand();
         },
         async reset() {
             if (loaded !== undefined)
                 await loaded.SandboxManager.reset();
             initialized = undefined;
             loaded = undefined;
-            inFlight = 0;
         },
     };
 }

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

@@ -31,6 +31,7 @@ const EmbedderToolSchema = z.object({
     run: z.custom(isFunction, "must be a function"),
 });
 const OptionsSchema = z.strictObject({
+    openSignal: z.instanceof(AbortSignal).optional(),
     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()

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

@@ -3,6 +3,7 @@ import type { SessionEvent, SessionEventBody, TurnEndStatus } from "./agent-sess
 import type { SendInput } from "./image-input.ts";
 import type { TurnContribution } from "./session-backend.ts";
 import { type AgentSessionAdapter, type SessionHandle, type TurnResult } from "./session-types.ts";
+import type { SteerChannel } from "./steer-channel.ts";
 /** The ask_human budget per turn: nax's agent.maxInteractionTurns default. */
 export declare const ASK_HUMAN_BUDGET = 10;
 export interface TurnRunContext {
@@ -32,6 +33,11 @@ export interface ClaimTurnHooks extends SendInput {
     readonly onStart: (live: LiveTurn) => void;
     /** Runs before turn_end is emitted. `status` is undefined for a voided claim. */
     readonly onSettle: (turnId: string, status: TurnEndStatus | undefined) => void;
+    /**
+     * US-001: this turn's steer channel, when the backend is steerable. Absent
+     * otherwise, so the adapter's `sendTurn` options carry no `steers` key at all.
+     */
+    readonly steers?: SteerChannel;
 }
 type TurnEndBody = Extract<SessionEventBody, {
     readonly type: "turn_end";

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

@@ -81,9 +81,10 @@ function fromError(err, signal) {
         return { ...base, status: "cancelled" };
     return { ...base, status: "errored", error: errorOf(err) };
 }
-function sendTurn(ctx, live, input) {
+function sendTurn(ctx, live, input, steers) {
     return ctx.adapter.sendTurn(ctx.handle, input.message, {
         ...ctx.turnOpts(),
+        ...(steers !== undefined ? { steers } : {}),
         ...(input.images?.length ? { images: input.images } : {}),
         maxInteractions: ASK_HUMAN_BUDGET,
         turnId: live.turnId,
@@ -105,14 +106,14 @@ async function markTurn(ctx, turnId, state) {
         return { error };
     }
 }
-async function runTurn(ctx, live, input) {
+async function runTurn(ctx, live, input, steers) {
     live.emit({ type: "turn_start" });
     const started = await markTurn(ctx, live.turnId, "running");
     if (started !== undefined)
         return fromError(started.error, live.signal);
     let end;
     try {
-        end = turnEndFromResult(await sendTurn(ctx, live, input));
+        end = turnEndFromResult(await sendTurn(ctx, live, input, steers));
     }
     catch (err) {
         end = fromError(err, live.signal);
@@ -168,7 +169,7 @@ export function claimTurn(ctx, message, hooks) {
         state = "running";
         const timer = _agentSessionDeps.setTimeout(() => controller.abort(abortReason(TIMED_OUT, "turn deadline")), ctx.turnTimeoutSeconds * 1000);
         hooks.onStart(live);
-        void runTurn(ctx, live, { message, images: hooks.images })
+        void runTurn(ctx, live, { message, images: hooks.images }, hooks.steers)
             .catch((err) => fromError(err, controller.signal))
             .then((end) => {
             _agentSessionDeps.clearTimeout(timer);

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

@@ -53,6 +53,8 @@ export interface AgentSessionHostPorts {
 export interface CreateAgentSessionOptions {
     /** The driver: `nativeBackend({ model })`, or an ACP backend. Native-only options live on the backend. */
     readonly backend: SessionBackend;
+    /** Cancels creation/resume only while opening; ignored once the backend has opened. */
+    readonly openSignal?: AbortSignal;
     /** The store key. Generated when absent. Letters, digits, `.`, `_`, `-`; starts with a letter or digit; at most 128 characters. */
     readonly sessionId?: string;
     readonly profile: AgentSessionProfile;
@@ -185,6 +187,23 @@ export interface SessionConfigureInput {
     readonly model?: string;
     readonly effort?: string;
 }
+/**
+ * What one manual compaction cost and what it bought (US-002).
+ *
+ * `tokensBefore`/`tokensAfter` are estimates over the stored history
+ * (`estimateContextTokens`), so they are comparable with each other and with the
+ * compaction threshold, not with a provider's billed count. `usage` and
+ * `costUsd` are the summarizer call's own, unchanged: nothing else was spent.
+ * A no-op compaction reports `compacted: false`, equal token counts, zero usage
+ * and zero cost — no model call was made, so zero is the honest answer.
+ */
+export interface CompactResult {
+    readonly compacted: boolean;
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+    readonly usage: TokenUsage;
+    readonly costUsd: number;
+}
 export interface AgentSession {
     /**
      * Sets the model and/or effort on the live session without a new process. Refuses, in order:
@@ -193,8 +212,27 @@ export interface AgentSession {
      * `AGENT_SESSION_CAPABILITY_UNSUPPORTED` (the backend cannot). The facade always provides this method.
      */
     configure?(input: SessionConfigureInput): Promise<void>;
+    /**
+     * Compacts the stored conversation history on demand (US-002): the finished
+     * exploration is replaced by one summary plus the recent window, so the next
+     * turn starts small without waiting for the context limit. Refuses, in order:
+     * `AGENT_SESSION_CLOSED`, `AGENT_SESSION_BUSY` (a turn, a command, a configure
+     * or another compact is in flight), then `AGENT_SESSION_CAPABILITY_UNSUPPORTED`
+     * (the backend cannot). Holds the session's single slot while it runs, so
+     * `send()` refuses `AGENT_SESSION_BUSY`. The facade always provides this method.
+     */
+    compact?(): Promise<CompactResult>;
     /** Run through the session's Bash tool without a model turn. The facade always provides this method. */
     runCommand?(command: string, onEvent: (event: SessionEvent) => void): Promise<CommandRunResult>;
+    /**
+     * Adds text to the running TURN's pending steers (US-001), injected as a user
+     * message at the turn's next safe boundary. Throws `AGENT_SESSION_CLOSED` on a
+     * closed session and `AGENT_SESSION_INVALID_OPTIONS` for empty or
+     * whitespace-only text; answers `unsupported` for a backend with no mid-turn
+     * input, and `no_turn` when no turn claim is active (a `runCommand` or
+     * `compact` in flight is not a turn). The facade always provides this method.
+     */
+    steer?(text: string): import("./steer-channel.ts").SteerResult;
     readonly id: string;
     /** The backend that opened this session (`kind` and its capability summary). */
     readonly backend: BackendInfo;

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

@@ -1,3 +1,11 @@
+/**
+ * createAgentSession: the conversational session facade (S3 spec 4, 5.1). The
+ * facade drives any SessionBackend: it resolves the shared options and the
+ * session root, opens the backend, and runs turns through the S1
+ * AgentSessionAdapter the backend returns. The native backend lives in
+ * native-backend.ts and the ACP backend (S4) satisfies the same seam.
+ * resumeAgentSession reopens a stored session (spec 4.2, 6.4).
+ */
 import type { AgentSession, CreateAgentSessionOptions } from "./agent-session-types.ts";
 export declare function createAgentSession(input: CreateAgentSessionOptions): Promise<AgentSession>;
 /**

package/dist/session/agent-session.js

@@ -1,3 +1,12 @@
+/**
+ * createAgentSession: the conversational session facade (S3 spec 4, 5.1). The
+ * facade drives any SessionBackend: it resolves the shared options and the
+ * session root, opens the backend, and runs turns through the S1
+ * AgentSessionAdapter the backend returns. The native backend lives in
+ * native-backend.ts and the ACP backend (S4) satisfies the same seam.
+ * resumeAgentSession reopens a stored session (spec 4.2, 6.4).
+ */
+import { NaxError } from "#src/infra/nax-error";
 import { claimCommand } from "./agent-session-command.js";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
@@ -7,8 +16,43 @@ import { claimTurn } from "./agent-session-turn.js";
 import { validateImageAttachments } from "./image-input.js";
 import { createPendingAskTable } from "./pending-asks.js";
 import { createSessionAskPort } from "./session-ask-port.js";
+import { createSteerQueue } from "./steer-channel.js";
 /** The handler's turn signal between turns: never aborts. */
 const IDLE_SIGNAL = new AbortController().signal;
+/**
+ * US-002: claim the session's single slot for one compaction.
+ *
+ * Same shape as `claimCommand` — the slot is taken synchronously, the work
+ * starts on a microtask, and the deadline timer is armed here — with one
+ * difference that matters: the signal handed to the backend fans in the
+ * session's own close signal as well as this call's deadline, so a `close()`
+ * stops a summarizer call instead of leaving it running past the session.
+ *
+ * The timer is armed BEFORE the work starts (not inside the microtask) because
+ * the deadline belongs to the claim: a compaction that has been claimed but not
+ * yet dispatched is still bounded by it.
+ */
+function claimCompact(options) {
+    const { ctx, closeSignal, run, hooks } = options;
+    const turnId = _agentSessionDeps.randomUUID();
+    const controller = new AbortController();
+    const timer = _agentSessionDeps.setTimeout(() => controller.abort(new NaxError("compaction deadline", "AGENT_SESSION_TURN_TIMEOUT", { stage: "agent-session" })), ctx.turnTimeoutSeconds * 1000);
+    const signal = AbortSignal.any([controller.signal, closeSignal]);
+    const result = Promise.resolve()
+        .then(() => run({ signal }))
+        .finally(() => {
+        _agentSessionDeps.clearTimeout(timer);
+        hooks.onSettle();
+    });
+    const claim = {
+        kind: "compact",
+        turnId,
+        settled: result.then(() => { }, () => { }),
+        cancel: (reason) => controller.abort(reason),
+    };
+    hooks.onStart(claim);
+    return { claim, result };
+}
 /**
  * The sandbox state as the embedder sees it: a frozen COPY, down to the
  * `network` list an `available` state carries. Copying keeps the backend's own
@@ -78,21 +122,60 @@ class FacadeAgentSession {
                 capability: "images",
             });
         }
+        // US-001: this turn's pending steers. Built only for a backend that can take
+        // one mid-turn, so an ACP-backed session allocates nothing and its
+        // `sendTurn` options stay identical.
+        const steers = this.parts.opened.steerable === true ? createSteerQueue() : undefined;
         const turn = claimTurn(this.parts.ctx, message, {
             images,
+            ...(steers !== undefined ? { steers } : {}),
             onStart: (live) => {
                 this.parts.slot.turn = live;
             },
             onSettle: (turnId, status) => {
+                // US-001: before `turn_end` is emitted, so a steer still pending resolves
+                // `false` first and can never carry into the next `send()`.
+                steers?.close();
                 this.active = undefined;
                 this.parts.slot.turn = undefined;
                 if (status !== undefined)
                     this.last = { turnId, status };
             },
         });
-        this.active = turn;
+        this.active = {
+            kind: "turn",
+            turnId: turn.turnId,
+            settled: turn.settled,
+            cancel: turn.cancel,
+            ...(steers !== undefined ? { steers } : {}),
+        };
         return turn.iterable;
     }
+    /**
+     * US-001: adds text to the running turn's pending steers. The check order is
+     * the documented one — the session's own state first, then the text, then the
+     * backend's capability, then the claim — so a caller learns what it can fix
+     * (its text) before what it cannot (the backend, the claim).
+     */
+    steer(text) {
+        if (this.closing !== undefined) {
+            throw new AgentSessionError(`Session "${this.id}" is closed`, "AGENT_SESSION_CLOSED", { sessionId: this.id });
+        }
+        if (text.trim() === "") {
+            throw new AgentSessionError(`Session "${this.id}" cannot steer empty text`, "AGENT_SESSION_INVALID_OPTIONS", {
+                sessionId: this.id,
+                path: "steer",
+            });
+        }
+        if (this.parts.opened.steerable !== true)
+            return { status: "unsupported" };
+        const active = this.active;
+        const steers = active?.kind === "turn" ? active.steers : undefined;
+        if (steers === undefined)
+            return { status: "no_turn" };
+        const { steerId, applied } = steers.add(text);
+        return { status: "accepted", steerId, applied };
+    }
     async configure(input) {
         const refusal = this.configureRefusal(input);
         if (refusal !== undefined)
@@ -123,6 +206,44 @@ class FacadeAgentSession {
     refusal(code, context = {}) {
         return new AgentSessionError(`Session "${this.id}" cannot be configured`, code, { sessionId: this.id, ...context });
     }
+    /**
+     * US-002: compact the stored history now, holding the session's single slot
+     * for the whole call so a `send()` during it refuses BUSY rather than running
+     * a turn against a transcript the compaction is rewriting.
+     *
+     * The order of refusals is the documented one: the session's own state first
+     * (closed), then its claim (busy), then the backend's capability (last,
+     * because it is the one the caller can do nothing about). The signal the
+     * backend receives aborts on this call's own deadline — the session's
+     * `turnTimeoutSeconds`, the same budget a turn gets — and on `close()`.
+     */
+    async compact() {
+        const run = this.parts.opened.compact;
+        const code = this.closing !== undefined
+            ? "AGENT_SESSION_CLOSED"
+            : this.active !== undefined || this.configuring
+                ? "AGENT_SESSION_BUSY"
+                : run === undefined
+                    ? "AGENT_SESSION_CAPABILITY_UNSUPPORTED"
+                    : undefined;
+        if (code !== undefined || run === undefined) {
+            throw new AgentSessionError(`Session "${this.id}" cannot be compacted`, code ?? "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { sessionId: this.id, capability: "compact" });
+        }
+        const claim = claimCompact({
+            ctx: this.parts.ctx,
+            closeSignal: this.parts.closeController.signal,
+            run: run.bind(this.parts.opened),
+            hooks: {
+                onStart: (claimed) => {
+                    this.active = claimed;
+                },
+                onSettle: () => {
+                    this.active = undefined;
+                },
+            },
+        });
+        return claim.result;
+    }
     async runCommand(command, onEvent) {
         const code = this.closing !== undefined
             ? "AGENT_SESSION_CLOSED"
@@ -150,7 +271,7 @@ class FacadeAgentSession {
                 },
             },
         });
-        this.active = claim;
+        this.active = { kind: "command", turnId: claim.turnId, settled: claim.settled, cancel: claim.cancel };
         return claim.result;
     }
     answer(requestId, reply) {
@@ -193,28 +314,49 @@ async function sessionRoot(options) {
     }
     return { dir: workdir, cleanup: async () => { } };
 }
+/** Refuse cancellation with the session contract, not the caller's arbitrary abort reason. */
+function checkOpenSignal(signal) {
+    if (signal?.aborted) {
+        throw new AgentSessionError("Agent session open was cancelled", "AGENT_SESSION_CLOSED");
+    }
+}
+/** The caller owns only the open phase; never retain its signal for reconnects. */
+function linkOpenSignal(signal, controller) {
+    checkOpenSignal(signal);
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    return () => signal?.removeEventListener("abort", abort);
+}
 async function assemble(options, sessionId, root, opening) {
     const raw = options.raw;
     const table = createPendingAskTable(options.approvalTimeoutMs);
     const slot = { turn: undefined };
     const closeController = new AbortController();
     const asks = createSessionAskPort({ table, emit: (body) => slot.turn?.emit(body), turn: () => slot.turn });
-    const opened = await raw.backend.open({
-        sessionId,
-        workdir: root.dir,
-        profile: raw.profile,
-        instructions: raw.instructions,
-        tools: options.tools,
-        transcriptStore: raw.transcriptStore,
-        resume: opening.doc === undefined ? undefined : { doc: opening.doc },
-        asks,
-        turnSignal: () => slot.turn?.signal ?? IDLE_SIGNAL,
-        currentTurnId: () => slot.turn?.turnId,
-        turnTimeoutSeconds: options.turnTimeoutSeconds,
-        metadata: options.metadata,
-        openSignal: closeController.signal,
-    });
+    const unlink = linkOpenSignal(raw.openSignal, closeController);
+    let opened;
+    try {
+        opened = await raw.backend.open({
+            sessionId,
+            workdir: root.dir,
+            profile: raw.profile,
+            instructions: raw.instructions,
+            tools: options.tools,
+            transcriptStore: raw.transcriptStore,
+            resume: opening.doc === undefined ? undefined : { doc: opening.doc },
+            asks,
+            turnSignal: () => slot.turn?.signal ?? IDLE_SIGNAL,
+            currentTurnId: () => slot.turn?.turnId,
+            turnTimeoutSeconds: options.turnTimeoutSeconds,
+            metadata: options.metadata,
+            openSignal: closeController.signal,
+        });
+    }
+    finally {
+        unlink();
+    }
     try {
+        checkOpenSignal(closeController.signal);
         const ctx = {
             sessionId,
             adapter: opened.adapter,
@@ -227,9 +369,8 @@ async function assemble(options, sessionId, root, opening) {
         return new FacadeAgentSession({ ctx, table, slot, opened, closeController, cleanup: root.cleanup }, opening.lastTurn);
     }
     catch (err) {
-        // No step after backend.open throws today; a future backend's must not leak
-        // the opened resources. open() still removes the root and lets open()'s own
-        // failure propagate untouched.
+        // Includes a backend that resolved despite cancellation. Close exactly once;
+        // open() removes the root and preserves the original failure.
         await opened.close().catch(() => undefined);
         throw err;
     }
@@ -247,6 +388,7 @@ async function open(options, sessionId, opening) {
 }
 export async function createAgentSession(input) {
     const options = resolveAgentSessionOptions(input);
+    checkOpenSignal(options.raw.openSignal);
     const sessionId = options.raw.sessionId ?? _agentSessionDeps.randomUUID();
     if ((await options.raw.transcriptStore.load(sessionId)) !== null) {
         throw new AgentSessionError(`Session "${sessionId}" already exists in the transcript store; resume it instead`, "AGENT_SESSION_EXISTS", { sessionId });
@@ -274,6 +416,7 @@ async function endInterruptedTurn(session, store, sessionId, turnId) {
  */
 export async function resumeAgentSession(sessionId, input) {
     const options = resolveAgentSessionOptions(resumeInput(sessionId, input));
+    checkOpenSignal(options.raw.openSignal);
     const store = options.raw.transcriptStore;
     const doc = await loadResumable(store, sessionId);
     checkBackendKind(doc, sessionId, options.raw.backend.kind);

package/dist/session/native-backend.js

@@ -151,6 +151,14 @@ async function openNative(resolved, ctx) {
             }
         },
         info: { kind: NATIVE_BACKEND_KIND, capabilities: {}, sandbox },
+        // US-001: nax owns the conversation here, so a turn can take a steer at its
+        // next round boundary. The ACP backend declares nothing — its protocol has
+        // no mid-turn user input.
+        steerable: true,
+        // US-002: the history is nax's own transcript, so it can be compacted without
+        // a turn. The ACP backend implements neither this nor `steerable`: the agent
+        // on the other side of the protocol owns the conversation.
+        compact: (request) => adapter.compactHistory(handle, request),
         turnOpts: () => ({
             interactionHandler,
             codingTools,

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

@@ -7,7 +7,7 @@
  */
 import type { TranscriptDoc, TranscriptStore } from "#src/native/session/transcript-types";
 import type { SandboxState } from "#src/sandbox/types";
-import type { AgentSessionProfile, ApprovalDecidedBy, CommandRunResult, EmbedderTool, SessionConfigureInput } from "./agent-session-types.ts";
+import type { AgentSessionProfile, ApprovalDecidedBy, CommandRunResult, CompactResult, EmbedderTool, SessionConfigureInput } from "./agent-session-types.ts";
 import type { AgentSessionAdapter, SendTurnOpts, SessionHandle } from "./session-types.ts";
 export interface BackendInfo {
     /** "native" or "acp:<agent>"; recorded in the transcript document. */
@@ -99,6 +99,24 @@ export interface OpenedBackend {
         callId: string;
         signal: AbortSignal;
     }): Promise<CommandRunResult>;
+    /**
+     * US-002: compact the session's stored history now. Absent on a backend that
+     * has no history of its own to compact (ACP keeps the conversation), which is
+     * what `AgentSession.compact()` reports as
+     * `AGENT_SESSION_CAPABILITY_UNSUPPORTED`. The signal aborts on the session's
+     * turn deadline or on close; a summarizer failure rejects, and the stored
+     * history is then unchanged.
+     */
+    compact?(request: {
+        signal: AbortSignal;
+    }): Promise<CompactResult>;
+    /**
+     * US-001: this backend can take a steer mid-turn, so the facade builds each
+     * turn a `SteerChannel` and `steer()` may answer `accepted`. Absent on a
+     * backend with no mid-turn user input (ACP): `steer()` then answers
+     * `unsupported` without ever looking at the claim.
+     */
+    readonly steerable?: true;
     readonly adapter: AgentSessionAdapter;
     readonly handle: SessionHandle;
     readonly info: BackendInfo;

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

@@ -288,6 +288,12 @@ export interface SendTurnOpts {
      * nax sets none.
      */
     onTurnEvent?: import("./turn-event.ts").TurnEventSink;
+    /**
+     * Native: the facade's pending steers for THIS turn (US-001), drained by the
+     * loop at a round boundary or at turn end. Set only when the backend declares
+     * `steerable`; ACP has no mid-turn user input and never sees it.
+     */
+    steers?: import("./steer-channel.ts").SteerChannel;
 }
 /**
  * A single mid-turn interactive Q&A exchange between the agent and a human

package/dist/session/steer-channel.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What `AgentSession.steer` answers (US-001).
+ *
+ * `accepted` is not "injected": the text is pending until the turn reaches a
+ * boundary. `applied` resolves `true` when the loop took the text, and `false`
+ * when the turn ended with it still pending — a cancelled, stopped, timed-out
+ * or failed turn, or a turn that finished before the steer arrived.
+ */
+export type SteerResult = {
+    readonly status: "accepted";
+    readonly steerId: string;
+    readonly applied: Promise<boolean>;
+} | {
+    readonly status: "unsupported";
+} | {
+    readonly status: "no_turn";
+};
+/**
+ * What a turn's `sendTurn` options carry (US-001). The loop reads it; nothing
+ * in the loop writes to it.
+ */
+export interface SteerChannel {
+    /** Removes every pending steer, in arrival order. `[]` once the channel closed. */
+    take(): readonly string[];
+}
+/** The facade's side of a turn's channel. */
+export interface SteerQueue extends SteerChannel {
+    /** Appends one text, in arrival order. */
+    add(text: string): {
+        readonly steerId: string;
+        readonly applied: Promise<boolean>;
+    };
+    /** Closes the channel: everything still pending resolves `false` and is discarded. */
+    close(): void;
+}
+export declare function createSteerQueue(): SteerQueue;

package/dist/session/steer-channel.js

@@ -0,0 +1,39 @@
+/**
+ * Per-turn steering (US-001). The facade owns each session's pending steers:
+ * `steer()` appends to the ACTIVE turn claim's queue, the native turn loop
+ * drains it through `take()` at a safe boundary, and the queue closes when the
+ * claim settles so a steer can never carry into the next `send()`.
+ *
+ * Ordering is arrival order and every pending text is handed over on one
+ * `take()`: the loop injects them as consecutive user messages, so splitting a
+ * drain across calls would interleave model output between them.
+ *
+ * The queue is deliberately transport-neutral: ACP has no mid-turn user input,
+ * so its backend never declares `steerable` and never receives a channel.
+ */
+import { _agentSessionDeps } from "./agent-session-deps.js";
+export function createSteerQueue() {
+    let pending = [];
+    let closed = false;
+    /** Hand over everything pending, resolving each entry with `applied`. */
+    function drain(applied) {
+        const taken = pending;
+        pending = [];
+        for (const steer of taken)
+            steer.resolve(applied);
+        return taken.map((steer) => steer.text);
+    }
+    return {
+        add(text) {
+            const steerId = _agentSessionDeps.randomUUID();
+            const settled = Promise.withResolvers();
+            pending = [...pending, { text, resolve: settled.resolve, applied: settled.promise }];
+            return { steerId, applied: settled.promise };
+        },
+        take: () => (closed ? [] : drain(true)),
+        close: () => {
+            closed = true;
+            drain(false);
+        },
+    };
+}

package/dist/session-store/index.d.ts

@@ -1,3 +1,3 @@
-export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export { acquireSessionLock, LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
 export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, type SessionMeta, type SessionMetaMode, } from "./session-meta.ts";
 export { createSessionStorage, LIST_PAGE_SIZE, processAlive, type SessionListEntry, type SessionListPage, type SessionLockHolder, type SessionLockHolderState, type SessionStorage, type SessionStorageDeps, } from "./storage.ts";

package/dist/session-store/index.js

@@ -1,3 +1,3 @@
-export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
+export { acquireSessionLock, LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
 export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, } from "./session-meta.js";
 export { createSessionStorage, LIST_PAGE_SIZE, processAlive, } from "./storage.js";

package/dist/session-store/session-lock.d.ts

@@ -20,8 +20,8 @@ declare const LockSchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     pid: z.ZodNumber;
     startedAt: z.ZodString;
-    nonce: z.ZodUndefined;
-    heartbeatAt: z.ZodUndefined;
+    nonce: z.ZodOptional<z.ZodUndefined>;
+    heartbeatAt: z.ZodOptional<z.ZodUndefined>;
 }, z.core.$strip>]>;
 type Body = z.infer<typeof LockSchema>;
 export declare const _lockDeps: {

package/dist/session-store/session-lock.js

@@ -17,8 +17,10 @@ const LockSchema = z.union([
     z.object({
         pid: z.number().int().positive(),
         startedAt: z.string(),
-        nonce: z.undefined(),
-        heartbeatAt: z.undefined(),
+        // A legacy lock OMITS these keys. zod >=4.6 treats a bare `z.undefined()` key as
+        // required-present, so `.optional()` is what keeps an absent key parsing.
+        nonce: z.undefined().optional(),
+        heartbeatAt: z.undefined().optional(),
     }),
 ]);
 export const _lockDeps = { rename: renameSync, link: linkSync, remove: rmSync };

package/dist/tools/ask-request.d.ts

@@ -23,6 +23,14 @@ export interface AskSummary {
  * a Write, a commit message, whatever a provider tool takes -- and an
  * AskResolver is by definition an outbound channel to a human. A summary is
  * what approval needs; the payload is what the audit sink already holds.
+ *
+ * Two kinds of declared field, and only these: the parts that say WHAT the
+ * call will do (command, argv, verb, paths), and the summary-only fields a tool
+ * adds for legibility (`ToolScope.summaryFields`) -- a memory tool's `slug`,
+ * so the person reads which note is about to be written instead of the same
+ * line the tool always rendered. Neither kind is grant-checked here, and
+ * neither is ever widened into the payload: a summary field renders only a
+ * string, number or boolean.
  */
 export declare function askSummary(tool: string, scope: ToolScope, input: Record<string, unknown>): AskSummary;
 /**