@nathapp/nax-agent 0.3.0 → 0.84.0

package/dist/permissions/approvals-store.js

@@ -19,8 +19,10 @@
  * primitive that surface calls into.
  */
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { NaxError } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
 import { withPathFileLock } from "#src/internal/path-file-lock";
 const EMPTY_FILE = { entries: [], taint: undefined };
 /**
@@ -146,11 +148,11 @@ export async function readApprovalsFile(path) {
 export async function readApprovals(path) {
     return (await readApprovalsFile(path)).entries;
 }
-/** Serialize the whole store. Callers hold the path lock. */
+/** Serialize the whole store, atomically (#16): a torn store would lose every remembered approval. Callers hold the path lock. */
 export async function writeApprovalsFile(path, file) {
     const body = file.taint === undefined ? { entries: file.entries } : { taint: file.taint, entries: file.entries };
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+    await writeFileAtomic(path, `${JSON.stringify(body, null, 2)}\n`);
 }
 /**
  * Lock the read-modify-write. Worktree-isolated parallel stories share one
@@ -161,12 +163,23 @@ export async function writeApprovalsFile(path, file) {
  *
  * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
  * lands in a store that stays untrusted.
+ *
+ * An unparseable store is refused, never replaced (the removal path does the same).
  */
 export async function appendApproval(path, entry) {
     await mkdir(dirname(path), { recursive: true });
     await withPathFileLock(path, async () => {
-        const existing = await readApprovalsFile(path);
-        await writeApprovalsFile(path, { taint: existing.taint, entries: [...existing.entries, entry] });
+        // Detailed read, not readApprovalsFile: that one reads failure AS empty (right for a
+        // lookup), and writing "empty + this entry" back would destroy the store (#16). A read
+        // error propagates; the caller logs it and still allows the approved call.
+        const read = await readApprovalsFileDetailed(path);
+        if (read.state === "unparseable") {
+            throw new NaxError("approvals.json could not be parsed; not rewriting it", "APPROVALS_STORE_UNPARSEABLE", {
+                stage: "permissions",
+                path,
+            });
+        }
+        await writeApprovalsFile(path, { taint: read.file.taint, entries: [...read.file.entries, entry] });
     });
 }
 /**

package/dist/sandbox/session-tmp.js

@@ -12,9 +12,11 @@
  * The parent is `/tmp/nax`, one shared directory that is easier to find and
  * list than a flat `/tmp/nax-<runId>`. It is shared, so it cannot be created
  * once and trusted: a `/tmp/nax` made by one OS user is not writable by
- * another. The parent is therefore re-resolved on EVERY call from three host
- * facts the `_sessionTmpDeps` seam exposes, with no cache, and anything nax
- * cannot vouch for falls back to a per-user `/tmp/nax-<uid>`.
+ * another. The parent is therefore re-resolved on EVERY call from four host
+ * facts the `_sessionTmpDeps` seam exposes — including the uid that owns it,
+ * because a world-writable directory another user created is still theirs to
+ * plant symlinks in — with no cache, and anything nax cannot vouch for falls
+ * back to a per-user `/tmp/nax-<uid>`.
  *
  * The root is the literal `/tmp` (not `os.tmpdir()`): callers record and assert
  * this machine-stable location, and the OS inherits the rest.
@@ -38,16 +40,20 @@ export const _sessionTmpDeps = {
     uid: () => process.getuid?.() ?? 0,
 };
 /**
- * True when `/tmp/nax` is a real directory the current user can write and
- * search. Absence is NOT this case: an absent parent is a usable shared parent
- * (the launcher creates it), and every other failure means the path is there in
- * a shape nax cannot vouch for.
+ * True when `/tmp/nax` is a real directory the current user OWNS and can write
+ * and search. Absence is NOT this case: an absent parent is a usable shared
+ * parent (the launcher creates it), and every other failure means the path is
+ * there in a shape nax cannot vouch for.
  */
 function isUsableSharedParent() {
     try {
         const stats = _sessionTmpDeps.lstat(SHARED_TMP_PARENT);
         if (!stats.isDirectory() || stats.isSymbolicLink())
             return false;
+        // Writability is not trust: a 0777 /tmp/nax another user created lets that user
+        // pre-create the run directories or read what sandboxed commands write there.
+        if (stats.uid !== _sessionTmpDeps.uid())
+            return false;
     }
     catch (err) {
         // ENOENT is the one failure that means "create /tmp/nax".

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

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

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

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

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

@@ -117,6 +117,8 @@ export type SessionEventBody = {
     readonly command?: string;
     readonly reason: string;
     readonly expiresAt: string;
+    /** `false`: decided already (by the profile); informational. Absent: a person's answer is awaited. */
+    readonly answerable?: false;
 } | {
     readonly type: "approval_resolved";
     readonly requestId: string;
@@ -127,6 +129,8 @@ export type SessionEventBody = {
     readonly requestId: string;
     readonly text: string;
     readonly expiresAt: string;
+    /** `false`: informational (`noteQuestion`); `answer()` on it does nothing. Absent: an answer is awaited. */
+    readonly answerable?: false;
 } | {
     readonly type: "usage";
     readonly round: number;

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

@@ -5,12 +5,16 @@ import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
 import type { AgentSessionHostPorts, AgentSessionProfile } from "./agent-session-types.ts";
 export interface NativeBackendOptions {
     readonly model: string;
+    /** Repository instruction basename; defaults to AGENTS.md. */
+    readonly instructionFileName?: string;
     readonly credentials?: CredentialSource;
     readonly catalogOverrides?: NativeCatalogOverrides;
     readonly loopHandlers?: LoopHandlerSet;
     readonly hostPorts?: AgentSessionHostPorts;
     readonly bashApproval?: BashApprovalMode;
     readonly allowUnsandboxed?: boolean;
+    /** Keep a resumed or continued conversation when the model differs (ACP server model switch, S5-3). */
+    readonly carryHistoryAcrossModels?: boolean;
 }
 export interface ResolvedNativeOptions {
     /** The caller's object, unchanged. */

package/dist/session/native-backend-options.js

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { parseNativeModel } from "#src/native/models";
+import { isInstructionFileName } from "#src/native/session/instruction-file-name";
 import { AgentSessionError } from "./agent-session-errors.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -16,6 +17,10 @@ function hasMethods(names) {
 const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const OptionsSchema = z.strictObject({
     model: z.string().min(1),
+    instructionFileName: z
+        .string()
+        .refine(isInstructionFileName, "must be a nonhidden Markdown basename without path separators, colon or control characters")
+        .optional(),
     credentials: z
         .custom((value) => isRecord(value) && (value.kind === "memory" || value.kind === "exec"), "must be a memory or exec source")
         .optional(),
@@ -31,6 +36,7 @@ const OptionsSchema = z.strictObject({
         .optional(),
     bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
     allowUnsandboxed: z.boolean().optional(),
+    carryHistoryAcrossModels: z.boolean().optional(),
 });
 function invalid(message, context = {}) {
     return new AgentSessionError(`Invalid agent session options: ${message}`, "AGENT_SESSION_INVALID_OPTIONS", context);

package/dist/session/native-backend.js

@@ -15,7 +15,10 @@ import { createSessionInteractionHandler, embedderToolDescriptor } from "./sessi
 import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } from "./session-tool-support.js";
 export const NATIVE_BACKEND_KIND = "native";
 /** nax's agent.native.transportRetry default (S3 spec 5.3). */
-const SESSION_TRANSPORT_RETRY = { maxAttempts: 3, baseDelayMs: 2000 };
+const SESSION_TRANSPORT_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 2000,
+};
 function createAdapter(raw) {
     const overrides = raw.catalogOverrides ?? [];
     const owns = overrides.length > 0 || raw.credentials !== undefined;
@@ -32,10 +35,13 @@ function checkResumeModel(doc, sessionId, model) {
 }
 async function openNative(resolved, ctx) {
     const raw = resolved.raw;
-    if (ctx.resume !== undefined)
+    if (ctx.resume !== undefined && raw.carryHistoryAcrossModels !== true)
         checkResumeModel(ctx.resume.doc, ctx.sessionId, raw.model);
     const { bashApproval, allowUnsandboxed } = nativeProfileRules(ctx.profile, raw);
-    const protectedPaths = { ...defaultProtectedPaths(raw.credentials !== undefined), ...raw.hostPorts?.protectedPaths };
+    const protectedPaths = {
+        ...defaultProtectedPaths(raw.credentials !== undefined),
+        ...raw.hostPorts?.protectedPaths,
+    };
     const launcher = await resolveSessionLauncher({
         profile: ctx.profile,
         root: ctx.workdir,
@@ -68,6 +74,8 @@ async function openNative(resolved, ctx) {
     const handle = await adapter.openSession(ctx.sessionId, {
         agentName: NATIVE_AGENT,
         workdir: ctx.workdir,
+        instructionProtectedPaths: protectedPaths,
+        instructionFileName: raw.instructionFileName,
         resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval },
         modelDef: { provider: resolved.provider, model: raw.model },
         timeoutSeconds: ctx.turnTimeoutSeconds,
@@ -76,6 +84,7 @@ async function openNative(resolved, ctx) {
         resume: ctx.resume !== undefined,
         spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
         transportRetry: SESSION_TRANSPORT_RETRY,
+        ...(raw.carryHistoryAcrossModels === true ? { carryHistoryAcrossModels: true } : {}),
         ...(ctx.instructions !== undefined && ctx.instructions !== "" ? { systemPrompt: ctx.instructions } : {}),
     });
     const codingTools = [...support.tools, ...ctx.tools.map(embedderToolDescriptor)];
@@ -102,5 +111,8 @@ async function openNative(resolved, ctx) {
 }
 export function nativeBackend(options) {
     const resolved = parseNativeBackendOptions(options);
-    return { kind: NATIVE_BACKEND_KIND, open: (ctx) => openNative(resolved, ctx) };
+    return {
+        kind: NATIVE_BACKEND_KIND,
+        open: (ctx) => openNative(resolved, ctx),
+    };
 }

package/dist/session/session-ask-port.js

@@ -41,6 +41,7 @@ export function createSessionAskPort(deps) {
                 summary: req.summary,
                 reason: req.reason,
                 expiresAt: now(),
+                answerable: false,
             });
             deps.emit({ type: "approval_resolved", requestId, decision, decidedBy: "profile" });
         },
@@ -58,7 +59,7 @@ export function createSessionAskPort(deps) {
             if (deps.turn() === undefined)
                 return;
             const { requestId } = deps.table.issue("question", ALREADY_ABORTED);
-            deps.emit({ type: "question", requestId, text, expiresAt: now() });
+            deps.emit({ type: "question", requestId, text, expiresAt: now(), answerable: false });
         },
     };
 }

package/dist/session/session-interaction.js

@@ -72,10 +72,29 @@ function runSafely(tool, input, ctx) {
         return { content: `Tool "${tool.name}" failed: ${cause}`, isError: true };
     });
 }
+/**
+ * Settle with `work`, or with `onAbort()` the moment `signal` aborts. The tool
+ * batch awaits interaction handlers with no abort race of its own, so a tool
+ * that ignores its signal would otherwise hang the turn (and `close()`, which
+ * awaits the turn). The abandoned work's late settlement is ignored.
+ */
+async function raceAbort(work, signal, onAbort) {
+    let listener = () => { };
+    const aborted = new Promise((resolve) => {
+        listener = () => resolve(onAbort());
+        signal.addEventListener("abort", listener, { once: true });
+    });
+    try {
+        return await Promise.race([work, aborted]);
+    }
+    finally {
+        signal.removeEventListener("abort", listener);
+    }
+}
 /**
  * Runs the tool, but answers at once when the turn aborts: the batch awaits
  * this handler with no abort race of its own, so a run that ignores its signal
- * would otherwise hang the turn. The abandoned run's late settlement is ignored.
+ * would otherwise hang the turn. See `raceAbort`.
  */
 async function invoke(tool, input, ctx) {
     const abandoned = {
@@ -84,17 +103,7 @@ async function invoke(tool, input, ctx) {
     };
     if (ctx.signal.aborted)
         return abandoned;
-    let onAbort = () => { };
-    const aborted = new Promise((resolve) => {
-        onAbort = () => resolve(abandoned);
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
-    });
-    try {
-        return await Promise.race([runSafely(tool, input, ctx), aborted]);
-    }
-    finally {
-        ctx.signal.removeEventListener("abort", onAbort);
-    }
+    return raceAbort(runSafely(tool, input, ctx), ctx.signal, () => abandoned);
 }
 async function runEmbedderTool(deps, tool, request) {
     const toolCallId = request.toolCallId ?? "";
@@ -131,7 +140,14 @@ function toolCallContext(request) {
 async function runCodingTool(deps, request) {
     deps.setCurrentCallId(request.toolCallId);
     try {
-        const outcome = await deps.runtime.callTool(request.name, request.input ?? {}, toolCallContext(request));
+        const signal = request.signal ?? deps.turnSignal();
+        const abandoned = {
+            kind: "error",
+            content: `Tool "${request.name}" was abandoned: the turn ended.`,
+        };
+        const outcome = signal.aborted
+            ? abandoned
+            : await raceAbort(deps.runtime.callTool(request.name, request.input ?? {}, { ...toolCallContext(request), signal }), signal, () => abandoned);
         if (outcome.kind === "denied") {
             return { answer: `Denied: ${outcome.reason}`, denied: { reason: outcome.reason, breach: outcome.breach } };
         }

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

@@ -136,6 +136,16 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * scratch dir reaches the adapter otherwise. ACP ignores it.
      */
     transcriptDir?: string;
+    /**
+     * S4b spec 7.4: where an S1 adapter that writes its own tool-audit ledger (nax's
+     * ACP adapter) writes it, and the run-scoped header stamped on it. nax fills it
+     * from the same resolution the native coding tools use. nax-agent itself does not
+     * read it; native takes its sink from coding-tool support.
+     */
+    toolAudit?: {
+        readonly dir: string;
+        readonly header: import("#src/tools/tool-audit").ToolAuditHeader;
+    };
     /**
      * Native: identity that owns this session's transcript — the op invocation's
      * `scopeId ?? callId`. Stable across the retries and hops of one invocation,
@@ -165,6 +175,14 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * facade sets it from `instructions`; nax leaves it unset. ACP ignores it.
      */
     systemPrompt?: string;
+    /** Native: repository-relative instruction scopes, independent of the file-tool root. */
+    instructionDirectories?: readonly string[];
+    /** Native: instruction Markdown basename; defaults to AGENTS.md and its legacy fallback chain. */
+    instructionFileName?: string;
+    /** Native: repository-relative paths excluded from automatic instruction reads. */
+    instructionDenyPaths?: readonly string[];
+    /** Native: host credential and trust-store paths excluded from instruction discovery. */
+    instructionProtectedPaths?: import("#src/tools/protected-paths").ProtectedPathsPolicy;
     /**
      * Native: resolved compaction settings. A resolved primitive, never NaxConfig —
      * src/agents/native/ must not read config (check:adapter-no-config-import).
@@ -182,6 +200,8 @@ export interface OpenSessionOpts extends TrackedSpawnDeadlineOptions {
      * NaxConfig. ACP ignores it; its loop is bounded by `maxInteractions`.
      */
     spinBreaker?: import("#src/infra/spin-breaker/index").ResolvedSpinBreakerSettings;
+    /** Native: keep history written by another model (S5-3). */
+    readonly carryHistoryAcrossModels?: boolean;
 }
 /** Options for sendTurn(). */
 export interface SendTurnOpts {

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

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

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

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

package/dist/session/turn-spend.js

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

package/dist/terminal-auth/index.d.ts

@@ -0,0 +1,4 @@
+/** Terminal login UI shared by `nax auth login` and `nax-agent login` (S5-4 M-28). */
+export { createTerminalAuthInteraction, type TerminalAuthOptions } from "./interaction.ts";
+export { _openUrlDeps, openUrl, spawnDetached } from "./open-url.ts";
+export { _terminalPromptDeps, PLAIN_STYLE, PromptCancelledError, type PromptStdin, promptForLine, promptForSecret, promptForSelect, type SelectChoice, type TerminalStyle, } from "./prompt.ts";

package/dist/terminal-auth/index.js

@@ -0,0 +1,4 @@
+/** Terminal login UI shared by `nax auth login` and `nax-agent login` (S5-4 M-28). */
+export { createTerminalAuthInteraction } from "./interaction.js";
+export { _openUrlDeps, openUrl, spawnDetached } from "./open-url.js";
+export { _terminalPromptDeps, PLAIN_STYLE, PromptCancelledError, promptForLine, promptForSecret, promptForSelect, } from "./prompt.js";

package/dist/terminal-auth/interaction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The terminal's side of a login (moved from nax's `terminalInteraction`, S5-4
+ * M-28). Shared by `nax auth login` and `nax-agent login`. Secrets go through
+ * the non-echoing prompt; any prompt type this mirror does not recognise is
+ * treated as a secret.
+ */
+import type { AuthInteraction } from "#src/native/auth-types";
+import { type TerminalStyle } from "#src/terminal-auth/prompt";
+export interface TerminalAuthOptions {
+    /** One line of output (no trailing newline). */
+    readonly log: (text: string) => void;
+    readonly style?: TerminalStyle;
+    readonly openUrl?: (url: string) => void;
+}
+export declare function createTerminalAuthInteraction(options: TerminalAuthOptions): AuthInteraction;

package/dist/terminal-auth/interaction.js

@@ -0,0 +1,55 @@
+import { openUrl as defaultOpenUrl } from "#src/terminal-auth/open-url";
+import { PLAIN_STYLE, promptForLine, promptForSecret, promptForSelect, } from "#src/terminal-auth/prompt";
+export function createTerminalAuthInteraction(options) {
+    const style = options.style ?? PLAIN_STYLE;
+    const open = options.openUrl ?? defaultOpenUrl;
+    // notify() is synchronous and the flow fires auth-url right before racing a
+    // manual-code prompt against its callback server, so the URL is parked and
+    // spent by the next prompt's Enter-on-empty.
+    let pendingUrl;
+    const manualCode = (message) => {
+        const url = pendingUrl;
+        if (url === undefined)
+            return promptForLine(message, undefined, style);
+        pendingUrl = undefined;
+        options.log(style.dim("Press Enter to open it in your browser."));
+        return promptForLine(message, () => {
+            options.log(style.dim("Opening your browser..."));
+            open(url);
+        }, style);
+    };
+    return {
+        prompt: async (prompt) => {
+            if (prompt.type === "manual-code")
+                return manualCode(prompt.message);
+            if (prompt.type === "text")
+                return promptForLine(prompt.message, undefined, style);
+            if (prompt.type === "select") {
+                return promptForSelect(prompt.message, prompt.options.map((option) => ({ id: option.id, label: option.label })), style);
+            }
+            return promptForSecret(prompt.message, style);
+        },
+        notify: (event) => {
+            switch (event.type) {
+                case "auth-url":
+                    // The flow's own instructions are dropped: nothing has opened a browser yet.
+                    options.log(`\n${style.bold("Open this URL to continue:")}\n  ${event.url}`);
+                    pendingUrl = event.url;
+                    return;
+                case "device-code":
+                    options.log(`\nGo to ${event.verificationUri} and enter code ${style.bold(event.userCode)}`);
+                    return;
+                case "info":
+                    options.log(event.message);
+                    for (const link of event.links ?? [])
+                        options.log(`  ${link.label ?? "Link"}: ${link.url}`);
+                    return;
+                case "progress":
+                    options.log(style.dim(event.message));
+                    return;
+                default:
+                // An event type this mirror does not recognise: say nothing.
+            }
+        },
+    };
+}

package/dist/terminal-auth/open-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opening a URL in the user's browser (moved from the nax CLI, S5-4 M-28).
+ *
+ * Best-effort: the caller always prints the URL first, so a failure costs a
+ * copy-paste, not the login. The URL is its own argv entry, never a shell
+ * string. Node reports a missing opener asynchronously (an `error` event), so
+ * the child gets an error listener; without it a container with no xdg-open
+ * would crash the login (S5-4 Review Focus 2).
+ */
+import { type ChildProcess } from "node:child_process";
+export declare function spawnDetached(command: readonly string[]): ChildProcess;
+/** Test seam. */
+export declare const _openUrlDeps: {
+    spawn: (command: readonly string[]) => void;
+    platform: () => string;
+};
+export declare function openUrl(url: string): void;

package/dist/terminal-auth/open-url.js

@@ -0,0 +1,44 @@
+/**
+ * Opening a URL in the user's browser (moved from the nax CLI, S5-4 M-28).
+ *
+ * Best-effort: the caller always prints the URL first, so a failure costs a
+ * copy-paste, not the login. The URL is its own argv entry, never a shell
+ * string. Node reports a missing opener asynchronously (an `error` event), so
+ * the child gets an error listener; without it a container with no xdg-open
+ * would crash the login (S5-4 Review Focus 2).
+ */
+import { spawn } from "node:child_process";
+export function spawnDetached(command) {
+    const [file, ...args] = command;
+    // nax-git-env-allow: not git: browser opener argv
+    const child = spawn(file ?? "", args, { stdio: "ignore", detached: true, windowsHide: true });
+    child.on("error", () => {
+        // The URL is already on screen; a missing opener is not news.
+    });
+    child.unref();
+    return child;
+}
+/** Test seam. */
+export const _openUrlDeps = {
+    spawn: (command) => {
+        spawnDetached(command);
+    },
+    platform: () => process.platform,
+};
+/** The opener for a platform. Windows needs the empty "" title argument. */
+function openerFor(platform, url) {
+    if (platform === "darwin")
+        return ["open", url];
+    if (platform === "win32")
+        return ["cmd", "/c", "start", "", url];
+    return ["xdg-open", url];
+}
+export function openUrl(url) {
+    try {
+        // nax-git-env-allow: not git: browser opener argv
+        _openUrlDeps.spawn(openerFor(_openUrlDeps.platform(), url));
+    }
+    catch {
+        // Deliberately silent: the URL is already on screen.
+    }
+}

package/dist/terminal-auth/prompt.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal prompts for credential entry (moved from the nax CLI, S5-4 M-28).
+ *
+ * Nothing typed into a secret prompt is echoed, and the terminal is restored on
+ * every exit path: submit, cancel, stream end and stream error. Ctrl+D cancels;
+ * it never submits (it once fell through to "submit" in nax's confirm prompt).
+ */
+/** Colours for the prompts; the caller supplies them (nax passes chalk). */
+export interface TerminalStyle {
+    accent(text: string): string;
+    dim(text: string): string;
+    bold(text: string): string;
+}
+export declare const PLAIN_STYLE: TerminalStyle;
+/** The slice of process.stdin these prompts drive. Injected so tests can stand one up. */
+export interface PromptStdin {
+    isTTY?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    setEncoding(encoding: string): unknown;
+    on(event: string, listener: (chunk: string) => void): unknown;
+    once(event: string, listener: () => void): unknown;
+    removeListener(event: string, listener: (...args: never[]) => void): unknown;
+}
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+/**
+ * Test seam. `stdin` is unset by default and resolved to `process.stdin` only
+ * when a prompt runs: this module is reachable from the public barrel, and
+ * touching `process.stdin` at import would open it for every consumer.
+ */
+export declare const _terminalPromptDeps: {
+    stdin: PromptStdin | undefined;
+    write: (text: string) => boolean;
+};
+/** Reads a secret. Nothing is echoed, not even a masking character. */
+export declare function promptForSecret(message: string, style?: TerminalStyle): Promise<string>;
+/** Reads a visible line, for non-secret answers such as a pasted auth code. */
+export declare function promptForLine(message: string, onEmptySubmit?: () => void, style?: TerminalStyle): Promise<string>;
+export interface SelectChoice {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * Reads a choice with the arrow keys and returns the chosen option's id. The
+ * option block is redrawn in place. Enter commits the highlighted row, so a
+ * value that is not an option can never be returned.
+ */
+export declare function promptForSelect(message: string, choices: readonly SelectChoice[], style?: TerminalStyle): Promise<string>;