@nathapp/nax-agent 0.91.6 → 0.91.7-canary.10

package/dist/mcp/connect.js

@@ -6,7 +6,8 @@
  * once the process is gone. A failed connect is closed the same way.
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCode, ListToolsResultSchema, McpError, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { McpCallError, McpConnectError } from "#src/mcp/errors";
 import { resultText } from "#src/mcp/result-text";
 import { waitForStdioExit } from "#src/mcp/stdio-close";
@@ -53,13 +54,35 @@ function toolInfo(raw) {
     if (!isRaw(raw) || typeof raw.name !== "string" || raw.name.length === 0)
         return undefined;
     const inputSchema = isRaw(raw.inputSchema) ? { ...raw.inputSchema } : {};
-    return { name: raw.name, description: typeof raw.description === "string" ? raw.description : "", inputSchema };
+    const readOnly = isRaw(raw.annotations) && raw.annotations.readOnlyHint === true;
+    return {
+        name: raw.name,
+        description: typeof raw.description === "string" ? raw.description : "",
+        inputSchema,
+        ...(readOnly ? { readOnly: true } : {}),
+    };
+}
+/**
+ * The SDK's own tools/list schema, except that a tool's `annotations` are not
+ * type-checked: the SDK would reject the WHOLE page over one server's
+ * `readOnlyHint: "yes"`, which would cost the connection every tool. `toolInfo`
+ * reads the hint strictly (`=== true`), so a malformed one just means "not
+ * read-only" and every other field is still validated.
+ */
+const LenientListToolsSchema = ListToolsResultSchema.extend({
+    tools: z.array(ToolSchema.extend({ annotations: z.record(z.string(), z.unknown()).optional() })),
+});
+async function listPage(client, cursor, signal, timeout) {
+    const page = await client.request({ method: "tools/list", ...(cursor !== undefined ? { params: { cursor } } : {}) }, LenientListToolsSchema, { signal, timeout });
+    // What Client.listTools does after its own request: the SDK reads these caches in callTool.
+    client["cacheToolMetadata"](page.tools);
+    return page;
 }
 async function listAll(client, signal, timeout) {
     const tools = [];
     let cursor;
     do {
-        const page = await client.listTools(cursor !== undefined ? { cursor } : undefined, { signal, timeout });
+        const page = await listPage(client, cursor, signal, timeout);
         for (const raw of page.tools ?? []) {
             const info = toolInfo(raw);
             if (info !== undefined)

package/dist/mcp/types.d.ts

@@ -15,6 +15,13 @@ export interface McpToolInfo {
     readonly name: string;
     readonly description: string;
     readonly inputSchema: JSONSchema;
+    /**
+     * Present (as `true`) only when the server annotated the tool
+     * `readOnlyHint: true`. Absent in every other case, so an unannotated tool
+     * keeps its `{ name, description, inputSchema }` shape. Trusted as the server
+     * states it; the lock pins input schemas, not this hint.
+     */
+    readonly readOnly?: true;
 }
 export interface McpCallResult {
     readonly text: string;

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

@@ -16,6 +16,8 @@ export declare function isProtocolStreamError(err: unknown): err is {
 export declare const _adapterDeps: {
     listStoredProviders: typeof listStoredProviders;
     anyAmbientCredential: typeof anyAmbientCredential;
+    /** Environment lookup for custom providers not covered by pi's ambient probe. */
+    readEnv: (name: string) => string | undefined;
     /**
      * US-004: whether the global auth config points at an exec helper. Injectable
      * so a test can pin the credential-source decision without writing

package/dist/native/adapter-deps.js

@@ -12,6 +12,8 @@ export function isProtocolStreamError(err) {
 export const _adapterDeps = {
     listStoredProviders,
     anyAmbientCredential,
+    /** Environment lookup for custom providers not covered by pi's ambient probe. */
+    readEnv: (name) => process.env[name],
     /**
      * US-004: whether the global auth config points at an exec helper. Injectable
      * so a test can pin the credential-source decision without writing

package/dist/native/models.js

@@ -103,6 +103,7 @@ export function toProviderOverrides(overrides) {
         // `!== undefined` as a declaration and checks it against the protocol
         // entries (nax#2019).
         ...(override.baseUrl !== undefined ? { baseUrl: override.baseUrl } : {}),
+        ...(override.authEnv !== undefined ? { authEnv: override.authEnv } : {}),
         // Copied, not aliased: nax-ai's client catalog assigns this reference
         // straight onto ResolvedProvider.headers (providers/catalog.ts) without a
         // copy of its own, so forwarding the live config object would let a later
@@ -117,6 +118,7 @@ export function toProviderOverrides(overrides) {
             // Omitted when the override declares none: nax-ai then falls back to the
             // template sibling's ceiling, which is the only honest value available.
             ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+            ...(model.thinkingFormat !== undefined ? { thinkingFormat: model.thinkingFormat } : {}),
             supportsTools: model.supportsTools,
             thinkingLevels: model.thinkingLevels,
             // nax#2191: forwarded verbatim. nax-ai's `assertOverrideModelRouting`

package/dist/native/session/loop-events/types.d.ts

@@ -128,6 +128,11 @@ export interface BeforeRequestPatch {
  * parameter, not a new concept.
  */
 export interface CompleteCallOptions {
+    /**
+     * `false` asks for no thinking on this request; on a model that cannot
+     * disable thinking it gets the least thinking the model supports instead.
+     * `true` keeps the session's resolved level.
+     */
     readonly thinking?: boolean;
     readonly temperature?: number;
 }

package/dist/native/session-adapter.js

@@ -128,6 +128,9 @@ export class NativeSessionAdapter {
                 return true;
             if ((await _adapterDeps.listStoredProviders()).length > 0)
                 return true;
+            if (this.catalogOverrides.some((override) => override.authEnv !== undefined && !!_adapterDeps.readEnv(override.authEnv))) {
+                return true;
+            }
             return await _adapterDeps.anyAmbientCredential();
         }
         catch {
@@ -271,6 +274,12 @@ export class NativeSessionAdapter {
                             messages: [...span, { role: "user", content: summaryPrompt(previousSummary) }],
                             sessionId,
                             signal,
+                            // A summary restates the transcript; it does not need reasoning.
+                            // "off", not an absent level: absent means the backend default,
+                            // which on a model that cannot disable thinking is adaptive at
+                            // effort high (#2686). The client clamps "off" to the least
+                            // thinking such a model allows.
+                            thinking: "off",
                         });
                         const summaryUsage = res.usage;
                         const { costUsd, resolvedRates } = priceCall(summaryUsage, rates);
@@ -299,11 +308,16 @@ export class NativeSessionAdapter {
                     const signal = AbortSignal.any(opts.signal !== undefined
                         ? [opts.signal, controller.signal, turnController.signal, deadlineController.signal]
                         : [controller.signal, turnController.signal, deadlineController.signal]);
-                    // The loop-event bag speaks in booleans: `false` explicitly drops
-                    // the session's inherited thinking level for this request, while
-                    // `true` leaves that resolved level in place. nax-ai accepts a
-                    // thinking LEVEL rather than a boolean, so normalize at this boundary.
-                    const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
+                    // The loop-event bag speaks in booleans: `false` turns thinking off
+                    // for this request, while `true` leaves the session's resolved level
+                    // in place. nax-ai accepts a thinking LEVEL rather than a boolean, so
+                    // normalize at this boundary. `false` must become "off", not an
+                    // absent level: absent means the backend default, which on a model
+                    // that cannot disable thinking is adaptive at effort high (#2686).
+                    // nax-ai clamps "off" to the lowest level such a model supports, so
+                    // there `false` still enables thinking, and a `temperature` set
+                    // alongside it is dropped by the backend as for any thinking request.
+                    const requestThinking = requestOptions?.thinking === false ? "off" : thinking;
                     try {
                         instructionInteraction.acknowledge();
                         const res = await billedOnFailure(rates, () => streamComplete(client, resolved, {

package/dist/permissions/approval-memory.d.ts

@@ -0,0 +1,18 @@
+/** Shared session approval-memory policy, ported from the ACP server (nax#2553). */
+export interface ApprovalMemoryRequest {
+    readonly tool: string;
+    readonly command?: string;
+}
+export type ApprovalMemoryDecision = "allow" | "deny";
+/**
+ * Tool key, or execute tool plus command/subcommand. Unsafe, masked, wrapper and
+ * flag-second-word requests have no key. A key alone never authorizes a command:
+ * callers must also check approvalMemoryApplies against the remembered decision.
+ */
+export declare function approvalMemoryKey(request: ApprovalMemoryRequest): string | undefined;
+/**
+ * Whether a decision found under this request's key may answer without asking.
+ * Allows cover only simple commands with plain, non-flag words after the key;
+ * denies cover their matching key regardless. Does not validate key eligibility.
+ */
+export declare function approvalMemoryApplies(request: ApprovalMemoryRequest, decision: ApprovalMemoryDecision): boolean;

package/dist/permissions/approval-memory.js

@@ -0,0 +1,88 @@
+/** Keep aligned with the ACP display's execute tools, without depending on that transport. */
+const APPROVAL_EXECUTE_TOOLS = new Set(["Bash", "RunCommand", "Git", "GitCommit"]);
+/** Chaining, pipes, substitution, subshells, redirection and line breaks. */
+const SHELL_METACHARACTERS = /[;&|`$()<>\n\r]/;
+/** First words that run another command or arbitrary code. */
+const WRAPPERS = new Set([
+    "sh",
+    "bash",
+    "zsh",
+    "dash",
+    "ksh",
+    "fish",
+    "env",
+    "xargs",
+    "sudo",
+    "doas",
+    "su",
+    "command",
+    "builtin",
+    "eval",
+    "exec",
+    "source",
+    ".",
+    "nohup",
+    "time",
+    "timeout",
+    "nice",
+    "ionice",
+    "stdbuf",
+    "watch",
+    "find",
+    "node",
+    "bun",
+    "deno",
+    "npx",
+    "bunx",
+    "pnpx",
+    "python",
+    "python3",
+    "perl",
+    "ruby",
+    "php",
+    "uv",
+    "uvx",
+]);
+/** A plain command name or path: no quotes, escapes, globs or expansions the shell would rewrite. */
+const PLAIN_WORD = /^[A-Za-z0-9._/-]+$/;
+/** The masking prefix S3 puts in place of a secret in a shown command. */
+const MASK_MARKER = "[REDACTED";
+/**
+ * Tool key, or execute tool plus command/subcommand. Unsafe, masked, wrapper and
+ * flag-second-word requests have no key. A key alone never authorizes a command:
+ * callers must also check approvalMemoryApplies against the remembered decision.
+ */
+export function approvalMemoryKey(request) {
+    if (!APPROVAL_EXECUTE_TOOLS.has(request.tool))
+        return request.tool;
+    const command = request.command ?? "";
+    if (command.includes(MASK_MARKER))
+        return undefined;
+    const [first = "", second] = command.trim().split(/\s+/);
+    if (!PLAIN_WORD.test(first))
+        return undefined;
+    const name = first.slice(first.lastIndexOf("/") + 1).toLowerCase();
+    if (name === "" || WRAPPERS.has(name))
+        return undefined;
+    if (second === undefined)
+        return `${request.tool}:${first}`;
+    // A flag can change what the command does (`rm -f`, `git -C repo`): remembering the bare command would
+    // approve every later invocation of it, so a flag second word is never remembered (nax#2553).
+    if (second.startsWith("-"))
+        return undefined;
+    return PLAIN_WORD.test(second) ? `${request.tool}:${first} ${second}` : undefined;
+}
+/**
+ * Whether a decision found under this request's key may answer without asking.
+ * Allows cover only simple commands with plain, non-flag words after the key;
+ * denies cover their matching key regardless. Does not validate key eligibility.
+ */
+export function approvalMemoryApplies(request, decision) {
+    if (decision === "deny" || !APPROVAL_EXECUTE_TOOLS.has(request.tool))
+        return true;
+    const command = request.command ?? "";
+    if (SHELL_METACHARACTERS.test(command))
+        return false;
+    const rest = command.trim().split(/\s+/).slice(2);
+    return rest.every((word) => PLAIN_WORD.test(word) && !word.startsWith("-"));
+}

package/dist/permissions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./approval-audit.ts";
+export { type ApprovalMemoryDecision, type ApprovalMemoryRequest, approvalMemoryApplies, approvalMemoryKey, } from "./approval-memory.ts";
 export * from "./approvals-link.ts";
 export * from "./approvals-store.ts";
 export * from "./approvals-taint.ts";

package/dist/permissions/index.js

@@ -1,4 +1,5 @@
 export * from "./approval-audit.js";
+export { approvalMemoryApplies, approvalMemoryKey, } from "./approval-memory.js";
 export * from "./approvals-link.js";
 export * from "./approvals-store.js";
 export * from "./approvals-taint.js";

package/dist/permissions/types.d.ts

@@ -36,6 +36,12 @@ export interface AskRequest {
      * hide shell syntax (review #9). The human link denies without prompting.
      */
     readonly unshowable?: true;
+    /**
+     * US-004: the call wants to run OUTSIDE the OS sandbox (the sandbox is never
+     * turned off for the whole session). A host that keys on it can offer a
+     * distinct decision; one that ignores it shows the ordinary approval prompt.
+     */
+    readonly unsandboxed?: true;
     /** The permitted root -- where the shell actually starts (src/tools/bash.ts:165). */
     readonly root?: string;
     /** The verdict's original reason, NOT rewritten as `matched ask rule "..."`. */

package/dist/runtime/node-runtime.js

@@ -67,6 +67,11 @@ function exitStatus(code, signal) {
         return code;
     return 128 + (signal !== null ? (osConstants.signals[signal] ?? 0) : 0);
 }
+/**
+ * `Readable.toWeb` is declared against `node:stream/web`'s `ReadableStream`, while
+ * `AgentSpawnResult` carries the global one. They are the same class at runtime and differ
+ * only in how their `getReader` overloads are written, so the bridge has to go via `unknown`.
+ */
 function toWeb(stream) {
     return stream === null ? emptyStream() : Readable.toWeb(stream);
 }

package/dist/sandbox/claude-settings.d.ts

@@ -41,6 +41,7 @@ export declare const CLAUDE_SETTINGS_FILES: readonly string[];
  * policy compile time, so a symlink created mid-session is still seen.
  *
  * Segment-exact on the full path — a sibling such as `settings.json.bak`, or any
- * other file under `.claude/`, is an ordinary path a tool must still reach.
+ * other file under `.claude/`, is an ordinary path a tool must still reach. The
+ * compare ignores case: `.Claude/settings.json` is the same file on macOS and Windows.
  */
 export declare function claudeSettingsWriteRefusal(tool: string, rel: string, resolvedRoot: string): string | undefined;

package/dist/sandbox/claude-settings.js

@@ -53,15 +53,19 @@ const CLAUDE_SETTINGS_WRITE_TOOLS = new Set(["Write", "Edit", "Delete"]);
  * policy compile time, so a symlink created mid-session is still seen.
  *
  * Segment-exact on the full path — a sibling such as `settings.json.bak`, or any
- * other file under `.claude/`, is an ordinary path a tool must still reach.
+ * other file under `.claude/`, is an ordinary path a tool must still reach. The
+ * compare ignores case: `.Claude/settings.json` is the same file on macOS and Windows.
  */
 export function claudeSettingsWriteRefusal(tool, rel, resolvedRoot) {
     if (!CLAUDE_SETTINGS_WRITE_TOOLS.has(tool))
         return undefined;
-    const entry = CLAUDE_SETTINGS_FILES.find((e) => e === rel || resolvedSettingsRel(resolvedRoot, e) === rel);
+    // Case-folded for the same reason as the `.git/` ban: on a case-insensitive filesystem
+    // `.Claude/settings.json` is the settings file, under a spelling a literal compare misses.
+    const folded = rel.toLowerCase();
+    const entry = CLAUDE_SETTINGS_FILES.find((e) => e.toLowerCase() === folded || resolvedSettingsRel(resolvedRoot, e).toLowerCase() === folded);
     if (entry === undefined)
         return undefined;
-    const subject = entry === rel
+    const subject = entry.toLowerCase() === folded
         ? `"${rel}" is a Claude Code settings file`
         : `"${rel}" is the target of the Claude Code settings file "${entry}"`;
     return (`${subject}: Claude loads allow rules, hooks and MCP servers from it for every ` +

package/dist/sandbox/defaults.js

@@ -44,4 +44,5 @@ export const BUILTIN_CREDENTIAL_READ_DENIES = [
     ".pypirc",
     ".git-credentials",
     ".config/gh",
+    ".config/glab-cli",
 ];

package/dist/sandbox/launcher.js

@@ -66,6 +66,8 @@ async function runUnwrapped(req, sandbox, env) {
         stripEnvVars: [...req.stripEnvVars],
         ...(overlay !== undefined ? { env: overlay } : {}),
         ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        ...(req.releaseDeadline !== undefined ? { releaseDeadline: req.releaseDeadline } : {}),
+        ...(req.onOutput !== undefined ? { onOutput: req.onOutput } : {}),
     });
     return { ...result, executed: argv, sandbox };
 }
@@ -102,6 +104,8 @@ async function runWrapped(req, backend, policy, env) {
             stripEnvVars: [...req.stripEnvVars],
             ...(req.env !== undefined ? { env: req.env } : {}),
             ...(req.signal !== undefined ? { signal: req.signal } : {}),
+            ...(req.releaseDeadline !== undefined ? { releaseDeadline: req.releaseDeadline } : {}),
+            ...(req.onOutput !== undefined ? { onOutput: req.onOutput } : {}),
         });
         const denied = result.exitCode !== 0 && LIKELY_SANDBOX_DENIAL.test(result.stderr);
         const violations = backend.annotate(commandId, result.stderr);
@@ -137,6 +141,9 @@ export function createCommandLauncher(opts) {
         state,
         async run(req) {
             const tmpDir = env.tmpDir !== undefined && (await ensureTmpDir(env.tmpDir)) ? env.tmpDir : undefined;
+            if (req.unwrapped === true) {
+                return runUnwrapped(req, { backend: "none", wrapped: false, reason: "requested" }, { ...env, tmpDir });
+            }
             if (state.kind === "disabled")
                 return runUnwrapped(req, { backend: "none", wrapped: false }, { ...env, tmpDir });
             if (state.kind === "unavailable") {

package/dist/sandbox/types.d.ts

@@ -112,8 +112,14 @@ export interface LaunchRequest {
     readonly stripEnvVars: readonly string[];
     /** The CALLER's own overlay (Exec's Yarn no-scripts env). Never the backend's. */
     readonly env?: Readonly<Record<string, string>>;
+    /** Explicitly run this command outside the sandbox without changing launcher state. */
+    readonly unwrapped?: true;
     /** Aborts the run: forwarded to runArgv, which SIGKILLs the process group. US-001. */
     readonly signal?: AbortSignal;
+    /** Releases the deadline without cancelling the run. Forwarded to runArgv. */
+    readonly releaseDeadline?: AbortSignal;
+    /** Best-effort per-chunk observer, forwarded before bounded output capture. */
+    readonly onOutput?: (stream: "stdout" | "stderr", chunk: Uint8Array) => void;
 }
 export interface LaunchResult extends ArgvExecResult {
     /** The logical argv (what the tool asked to run), not the sandbox wrapper argv. */

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

@@ -0,0 +1,19 @@
+import type { ClaimedTurn, LiveTurn, TurnRunContext } from "./agent-session-turn.ts";
+import type { CommandRunResult, SessionEvent } from "./agent-session-types.ts";
+import type { OpenedBackend } from "./session-backend.ts";
+interface CommandHooks {
+    onStart(live: LiveTurn): void;
+    onSettle(): void;
+}
+export interface ClaimedCommand extends Pick<ClaimedTurn, "turnId" | "settled" | "cancel"> {
+    readonly result: Promise<CommandRunResult>;
+}
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export declare function claimCommand(options: {
+    ctx: TurnRunContext;
+    run: NonNullable<OpenedBackend["runCommand"]>;
+    command: string;
+    onEvent(event: SessionEvent): void;
+    hooks: CommandHooks;
+}): ClaimedCommand;
+export {};

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

@@ -0,0 +1,38 @@
+import { NaxError } from "#src/infra/nax-error";
+import { displayToolInput, toolResultPreview } from "#src/native/session/turn-event-emitter";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export function claimCommand(options) {
+    const { ctx, run, command, onEvent, hooks } = options;
+    const turnId = _agentSessionDeps.randomUUID();
+    const callId = _agentSessionDeps.randomUUID();
+    const controller = new AbortController();
+    const emit = (body) => onEvent({
+        sessionId: ctx.sessionId,
+        turnId,
+        at: new Date(_agentSessionDeps.now()).toISOString(),
+        metadata: ctx.metadata,
+        ...body,
+    });
+    const abort = (code, reason) => controller.abort(new NaxError(reason, code, { stage: "agent-session" }));
+    const result = Promise.resolve().then(async () => {
+        const timer = _agentSessionDeps.setTimeout(() => abort("AGENT_SESSION_TURN_TIMEOUT", "turn deadline"), ctx.turnTimeoutSeconds * 1000);
+        try {
+            hooks.onStart({ turnId, signal: controller.signal, emit });
+            emit({ type: "tool_call", name: "Bash", input: displayToolInput({ command }), callId });
+            const outcome = await run({ command, callId, signal: controller.signal });
+            emit({ type: "tool_result", callId, isError: outcome.isError, preview: toolResultPreview(outcome.content) });
+            return outcome;
+        }
+        finally {
+            _agentSessionDeps.clearTimeout(timer);
+            hooks.onSettle();
+        }
+    });
+    return {
+        turnId,
+        result,
+        settled: result.then(() => { }, () => { }),
+        cancel: (reason) => abort("AGENT_SESSION_CANCELLED", reason),
+    };
+}

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

@@ -4,8 +4,10 @@
  * @nathapp/nax-agent-acp backend (S4) reuses these types unchanged.
  */
 import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/types";
 import type { TokenUsage } from "#src/cost/standard-types";
 import type { TranscriptStore } from "#src/native/session/transcript-types";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
 import type { BackendInfo, SessionBackend } from "./session-backend.ts";
 import type { JSONSchema } from "./tool-descriptor.ts";
@@ -43,6 +45,9 @@ export interface AgentSessionHostPorts {
     /** Paths the sandbox and the read tools deny. Default: the configured credentials directory, if any. */
     readonly protectedPaths?: ProtectedPathsPolicy;
     readonly commandInterceptor?: CommandInterceptor;
+    readonly commandShadow?: CommandShadow;
+    /** Opt in to host-owned background Bash commands. */
+    readonly backgroundCommands?: BackgroundCommandPort;
 }
 export interface CreateAgentSessionOptions {
     /** The driver: `nativeBackend({ model })`, or an ACP backend. Native-only options live on the backend. */
@@ -117,6 +122,8 @@ export type SessionEventBody = {
     readonly command?: string;
     readonly reason: string;
     readonly expiresAt: string;
+    /** US-004: the call wants to run outside the OS sandbox. Absent on every ordinary ask. */
+    readonly unsandboxed?: true;
     /** `false`: decided already (by the profile); informational. Absent: a person's answer is awaited. */
     readonly answerable?: false;
 } | {
@@ -167,7 +174,26 @@ export type AnswerReply = {
     readonly text: string;
 };
 export type AnswerStatus = "accepted" | "expired" | "cancelled" | "unknown";
+export interface CommandRunResult {
+    /** The Bash tool's result text as the model would see it (capped by the tool runtime). */
+    readonly content: string;
+    readonly isError: boolean;
+}
+/** What `AgentSession.configure` changes on a live session; at least one field, never an empty string. */
+export interface SessionConfigureInput {
+    readonly model?: string;
+    readonly effort?: string;
+}
 export interface AgentSession {
+    /**
+     * Sets the model and/or effort on the live session without a new process. Refuses, in order:
+     * `AGENT_SESSION_CLOSED`, `AGENT_SESSION_BUSY` (a turn, a command or another configure is in
+     * flight), `AGENT_SESSION_INVALID_OPTIONS` (neither field, or an empty string), then
+     * `AGENT_SESSION_CAPABILITY_UNSUPPORTED` (the backend cannot). The facade always provides this method.
+     */
+    configure?(input: SessionConfigureInput): Promise<void>;
+    /** 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>;
     readonly id: string;
     /** The backend that opened this session (`kind` and its capability summary). */
     readonly backend: BackendInfo;

package/dist/session/agent-session.js

@@ -1,3 +1,4 @@
+import { claimCommand } from "./agent-session-command.js";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { resolveAgentSessionOptions } from "./agent-session-options.js";
@@ -7,11 +8,24 @@ import { createPendingAskTable } from "./pending-asks.js";
 import { createSessionAskPort } from "./session-ask-port.js";
 /** The handler's turn signal between turns: never aborts. */
 const IDLE_SIGNAL = new AbortController().signal;
+/**
+ * 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
+ * record out of the embedder's reach; freezing keeps the embedder from editing
+ * the record of what its commands ran under (US-001).
+ */
+function frozenSandbox(state) {
+    if (state.kind !== "available" || typeof state.network === "string")
+        return Object.freeze({ ...state });
+    return Object.freeze({ ...state, network: Object.freeze([...state.network]) });
+}
 class FacadeAgentSession {
     parts;
     active;
     last;
     closing;
+    /** True while the backend's configure is pending: send, runCommand and configure refuse BUSY. */
+    configuring = false;
     constructor(parts, last) {
         this.parts = parts;
         this.last = last;
@@ -21,7 +35,13 @@ class FacadeAgentSession {
     }
     get backend() {
         const info = this.parts.opened.info;
-        return Object.freeze({ kind: info.kind, capabilities: Object.freeze({ ...info.capabilities }) });
+        // US-001: the sandbox state rides through the facade frozen, so an embedder
+        // cannot edit the record of what its commands ran under.
+        return Object.freeze({
+            kind: info.kind,
+            capabilities: Object.freeze({ ...info.capabilities }),
+            ...(info.sandbox !== undefined ? { sandbox: frozenSandbox(info.sandbox) } : {}),
+        });
     }
     get lastTurn() {
         return this.last;
@@ -35,6 +55,11 @@ class FacadeAgentSession {
                 sessionId: this.id,
             });
         }
+        if (this.configuring) {
+            throw new AgentSessionError(`Session "${this.id}" is being configured`, "AGENT_SESSION_BUSY", {
+                sessionId: this.id,
+            });
+        }
         const turn = claimTurn(this.parts.ctx, message, {
             onStart: (live) => {
                 this.parts.slot.turn = live;
@@ -49,6 +74,66 @@ class FacadeAgentSession {
         this.active = turn;
         return turn.iterable;
     }
+    async configure(input) {
+        const refusal = this.configureRefusal(input);
+        if (refusal !== undefined)
+            throw refusal;
+        const configure = this.parts.opened.configure;
+        if (configure === undefined)
+            throw this.refusal("AGENT_SESSION_CAPABILITY_UNSUPPORTED", { capability: "configure" });
+        this.configuring = true;
+        try {
+            await configure.call(this.parts.opened, input);
+        }
+        finally {
+            this.configuring = false;
+        }
+    }
+    /** The refusals that precede the backend call, in the documented order; the backend check is last and separate. */
+    configureRefusal(input) {
+        if (this.closing !== undefined)
+            return this.refusal("AGENT_SESSION_CLOSED");
+        if (this.active !== undefined || this.configuring)
+            return this.refusal("AGENT_SESSION_BUSY");
+        const { model, effort } = input;
+        if ((model === undefined && effort === undefined) || model === "" || effort === "") {
+            return this.refusal("AGENT_SESSION_INVALID_OPTIONS", { path: "configure" });
+        }
+        return undefined;
+    }
+    refusal(code, context = {}) {
+        return new AgentSessionError(`Session "${this.id}" cannot be configured`, code, { sessionId: this.id, ...context });
+    }
+    async runCommand(command, onEvent) {
+        const code = this.closing !== undefined
+            ? "AGENT_SESSION_CLOSED"
+            : this.active !== undefined || this.configuring
+                ? "AGENT_SESSION_BUSY"
+                : this.parts.opened.runCommand === undefined
+                    ? "AGENT_SESSION_CAPABILITY_UNSUPPORTED"
+                    : undefined;
+        const run = this.parts.opened.runCommand;
+        if (code !== undefined || run === undefined) {
+            throw new AgentSessionError(`Session "${this.id}" cannot run a command`, code ?? "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { sessionId: this.id });
+        }
+        const claim = claimCommand({
+            ctx: this.parts.ctx,
+            command,
+            onEvent,
+            run: (request) => run.call(this.parts.opened, request),
+            hooks: {
+                onStart: (live) => {
+                    this.parts.slot.turn = live;
+                },
+                onSettle: () => {
+                    this.parts.slot.turn = undefined;
+                    this.active = undefined;
+                },
+            },
+        });
+        this.active = claim;
+        return claim.result;
+    }
     answer(requestId, reply) {
         return this.parts.table.answer(requestId, reply);
     }