@nathapp/nax-agent 0.85.0 → 0.86.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.86.0] - 2026-10-10
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
+## [0.85.1] - 2026-10-10
+
+### Added
+
+- `nativeBackend({ compaction })`: `{ enabled?, compactAtPercent?, keepRecentPercent? }`, validated with the same schema as nax's `execution.compaction` (integer percentages of the context window, 50-99 and 5-79, `keepRecentPercent` at least 20 points below `compactAtPercent`). An invalid value throws `AGENT_SESSION_INVALID_OPTIONS`. `compactionSettingsSchema`, `DEFAULT_COMPACTION` and `resolveCompaction` are on `./internal` for nax and the ACP server (#2427).
+
+### Changed
+
+- Behaviour change: conversational sessions (`createAgentSession`, `resumeAgentSession`) now compact their history by default, as `nax run` does. A history past `compactAtPercent` (default 90) of the window is summarised before the round trip, and a context-overflow error is compacted and retried once, so long chats no longer end `errored` at the window. Each compaction adds one billed summary call; it emits no `usage` event. The existing `compaction` event (`reason: "proactive" | "overflow"`) is now emitted on the session stream, and the stored transcript after the turn is the compacted history. Pass `compaction: { enabled: false }` to `nativeBackend` for the old behaviour (#2427).
+
+### Fixed
+
+- Secret redaction now masks values under secret-named keys in JSON text (`{"apiKey": "..."}`, including JSON escaped inside a JSON string) and in env, dotenv, shell and YAML-style lines (`API_TOKEN=...`, `export KEY="..."`, `password: ...`, `Authorization: Bearer ...`), keeping the key and structure. This reaches `tool_result.preview`, `tool_call.input` and the run log. Usage counts (`tokens`, `max_tokens`) and references (`$VAR`, `process.env.X`) are left alone (#2346).
+
 ## [0.85.0] - 2026-10-09
 
 ### Added

package/README.md

@@ -86,12 +86,13 @@ Profiles set what a session may do:
 | `ask` | every Write, Edit, Delete, GitCommit and Bash is put to `answer()`; |
 | `full` | no prompts; `bashApproval` and the sandbox floor apply. |
 
-`createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `instructionFileName` (default `AGENTS.md`), `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval` and `allowUnsandboxed`. The ACP backend ships in `@nathapp/nax-agent-acp`.
+`createAgentSession` takes a `SessionBackend`. `nativeBackend(opts)` takes `instructionFileName` (default `AGENTS.md`), `model`, `credentials`, `catalogOverrides`, `loopHandlers`, `hostPorts`, `bashApproval`, `allowUnsandboxed` and `compaction`. The ACP backend ships in `@nathapp/nax-agent-acp`.
 
 `usage.costSource` is `computed` (native), `reported` or `unpriced`; never sum `unpriced` rows as cost.
 
 - **One turn at a time.** `send()` claims the session's turn slot at once. A second `send()` while a turn runs throws `AGENT_SESSION_BUSY`. The returned iterable is single-use, and the turn starts on its first `next()`. Breaking out of the loop cancels the turn.
-- **Events.** `turn_start`, `text_delta`, `thinking_delta`, `stream_reset`, `tool_call`, `tool_result`, `approval_requested`, `approval_resolved`, `question`, `usage`, `compaction` and `turn_end`. Sessions do not compact, so `compaction` is not emitted and a conversation that outgrows the model's context window ends `errored`. Each carries `sessionId`, `turnId`, `at` and your `metadata`. `turn_end` is always last, and a failed turn arrives as `turn_end`, never as a throw.
+- **Events.** `turn_start`, `text_delta`, `thinking_delta`, `stream_reset`, `tool_call`, `tool_result`, `approval_requested`, `approval_resolved`, `question`, `usage`, `compaction` and `turn_end`. Each carries `sessionId`, `turnId`, `at` and your `metadata`. `turn_end` is always last, and a failed turn arrives as `turn_end`, never as a throw.
+- **Compaction (native only).** On by default, so a long chat keeps answering. When the history crosses `compactAtPercent` of the model's context window (default 90), the session summarises the older part with one extra model call, keeps the most recent `keepRecentPercent` of the window verbatim (default 30) and emits `compaction { reason: "proactive" }` before that round. A context-overflow error from the provider is compacted and retried once, emitting `compaction { reason: "overflow" }`. The summary call is billed but emits no `usage` event, so a turn's `usage` events cover the round trips only. The stored transcript after the turn is the compacted history, and `resumeAgentSession` loads it. Pass `nativeBackend({ model, compaction: { enabled, compactAtPercent, keepRecentPercent } })` to tune it, or `{ enabled: false }` to turn it off, in which case a conversation that outgrows the window ends `errored`. `compactAtPercent` is an integer from 50 to 99, `keepRecentPercent` an integer from 5 to 79 and at least 20 points below `compactAtPercent`; anything else throws `AGENT_SESSION_INVALID_OPTIONS`. The ACP backend ignores compaction: the external agent manages its own context.
 - **Deltas are provisional.** `stream_reset` means the deltas of that round so far are void: the provider call was retried after a transient fault (up to 3 attempts; a rate-limit retry waits the provider's `retryAfter` silently, and `cancel()` ends the wait). `turn_end.output` and the stored transcript are authoritative. While your consumer lags, adjacent deltas are merged; control events are never merged or dropped.
 - **Approvals and questions.** Answer them with `session.answer(requestId, { decision: "allow" | "deny" })` or `{ text }`. An unanswered one is denied after `approvalTimeoutMs` (default 600000, range 30000..3600000). `answer` returns `"accepted"`, `"expired"`, `"cancelled"` or `"unknown"`.
 - **Credentials.** A session's `credentials` (`memory` or `exec`) and `catalogOverrides` give it its own client. Without them it uses the process-wide `configureCredentials` slot.

package/dist/internal/redact-structured.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Key-aware redaction of secrets embedded in JSON- and env-shaped text.
+ *
+ * `SECRET_VALUE_PATTERNS` matches token *shapes*; it cannot see
+ * `{"client_secret": "plainvalue123"}` or `API_TOKEN=abc` because the value has
+ * no recognisable shape. These patterns key off the NAME instead, using the
+ * same unanchored-substring secret-key set as `SECRET_KEY_PATTERN` (a name
+ * merely containing a secret-ish word counts), and mask only the value so the
+ * key and the surrounding structure stay readable.
+ *
+ * These patterns are linear in the input (no nested quantifiers, no
+ * catastrophic backtracking): keys are capped at 64 characters either side of
+ * the keyword, and a value is the last element of its pattern so consuming it
+ * never backtracks. `redactSecrets` as a whole also runs the older
+ * `SECRET_VALUE_PATTERNS`, which carry their own cost profile. Values are not
+ * length-capped here; callers bound the scan (`capStrings`).
+ *
+ * `_URL` is not a text-side key: `avatar_url` / `BASE_URL` values stay visible,
+ * and credentials in a URL are masked by the userinfo pattern.
+ *
+ * Deliberately NOT here: `SECRET_VALUE_PATTERNS` stays the shell-command
+ * masker's list (approval prompts reject spans containing quotes), so these
+ * live in their own list that only `redactString` applies.
+ */
+/** Mask the value of every secret-named key in JSON-, dotenv-, shell- or YAML-shaped text. */
+export declare function redactStructured(text: string): string;

package/dist/internal/redact-structured.js

@@ -0,0 +1,72 @@
+/**
+ * Key-aware redaction of secrets embedded in JSON- and env-shaped text.
+ *
+ * `SECRET_VALUE_PATTERNS` matches token *shapes*; it cannot see
+ * `{"client_secret": "plainvalue123"}` or `API_TOKEN=abc` because the value has
+ * no recognisable shape. These patterns key off the NAME instead, using the
+ * same unanchored-substring secret-key set as `SECRET_KEY_PATTERN` (a name
+ * merely containing a secret-ish word counts), and mask only the value so the
+ * key and the surrounding structure stay readable.
+ *
+ * These patterns are linear in the input (no nested quantifiers, no
+ * catastrophic backtracking): keys are capped at 64 characters either side of
+ * the keyword, and a value is the last element of its pattern so consuming it
+ * never backtracks. `redactSecrets` as a whole also runs the older
+ * `SECRET_VALUE_PATTERNS`, which carry their own cost profile. Values are not
+ * length-capped here; callers bound the scan (`capStrings`).
+ *
+ * `_URL` is not a text-side key: `avatar_url` / `BASE_URL` values stay visible,
+ * and credentials in a URL are masked by the userinfo pattern.
+ *
+ * Deliberately NOT here: `SECRET_VALUE_PATTERNS` stays the shell-command
+ * masker's list (approval prompts reject spans containing quotes), so these
+ * live in their own list that only `redactString` applies.
+ */
+const REDACTED = "[REDACTED]";
+// Text-side keyword set. Same intent as SECRET_KEY_PATTERN; TOKEN(?!s\b) keeps
+// plural usage counts (tokens, inputTokens, max_tokens) out. The key separator
+// may be `-` as well as `_` (x-api-key). `_URI`/`_DSN` need a character before
+// the underscore, as in SECRET_KEY_PATTERN.
+const KEYWORD = String.raw `(?:SECRET|TOKEN(?!s\b)|API[_-]?KEY|PASSWORD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|WEBHOOK|AUTHORIZATION|COOKIE|CREDENTIAL|PASSWD|(?<=[\w.-])_(?:URI|DSN)|CONNECTION_?STRING)`;
+const KEY = String.raw `[\w.-]{0,64}?${KEYWORD}[\w.-]{0,64}`;
+/** A double-quoted JSON/YAML string body: escapes consumed pairwise, never past the closing quote. */
+const DQ_BODY = String.raw `(?:[^"\\\r\n]|\\.)+`;
+/** The body of a string inside JSON-in-a-string, where the closing quote is itself escaped (`\"`). */
+const ESCAPED_BODY = String.raw `(?:[^"\\\r\n]|\\(?!\\*"))+`;
+const SQ_BODY = String.raw `[^'\r\n]+`;
+/**
+ * An unquoted value is left alone when it is a reference or a type rather than
+ * a credential: `$VAR`, `${VAR}`, `process.env.X`, `: string`, `=true`, and an
+ * already-masked span.
+ */
+const NOT_A_REFERENCE = String.raw `(?!["'$<{(\[]|process\.|import\.meta|os\.|env\.|await\b|new\b|[\w.]+\(|(?:string|number|boolean|str|int|any|unknown|undefined|null|true|false|none)(?![\w-]))`;
+/** `token_count: 5` is a usage figure, not a credential. */
+const NOT_A_TOKEN_COUNT = String.raw `(?![\w.-]{0,64}?TOKEN(?!s\b)[\w.-]{0,64}[ \t]{0,8}[=:][ \t]{0,8}\d+(?![\w.-]))`;
+const AUTH_SCHEME = String.raw `(?:(?:Bearer|Basic|Digest|Token)[ \t]+)?`;
+/** Each pattern captures the text to keep as group 1 and the value to mask as group 2. */
+const STRUCTURED_PATTERNS = [
+    // {"apiKey": "v"}, any whitespace around the colon.
+    { re: new RegExp(String.raw `("${KEY}"\s{0,256}:\s{0,256}")(${DQ_BODY})`, "gi") },
+    // Python reprs / single-quoted JSON: {'apiKey': 'v'}, {'apiKey': "v"}.
+    { re: new RegExp(String.raw `('${KEY}'\s{0,256}:\s{0,256}')(${SQ_BODY})`, "gi") },
+    { re: new RegExp(String.raw `('${KEY}'\s{0,256}:\s{0,256}")(${DQ_BODY})`, "gi") },
+    // JSON inside a JSON string: {\"apiKey\": \"v\"}.
+    { re: new RegExp(String.raw `(\\{1,3}"${KEY}\\{1,3}"\s{0,256}:\s{0,256}\\{1,3}")(${ESCAPED_BODY})`, "gi") },
+    // export OPENAI_API_KEY="v", secret_key: "v".
+    { re: new RegExp(String.raw `(?<![\w.-])(${KEY}[ \t]{0,8}[=:][ \t]{0,8}")(${DQ_BODY})`, "gi") },
+    // SECRET_KEY='v'
+    { re: new RegExp(String.raw `(?<![\w.-])(${KEY}[ \t]{0,8}[=:][ \t]{0,8}')(${SQ_BODY})`, "gi") },
+    // API_TOKEN=v, password: v, x-api-key: v, Authorization: Bearer v.
+    {
+        re: new RegExp(String.raw `(?<![\w.-])${NOT_A_TOKEN_COUNT}(${KEY}[ \t]{0,8}[=:][ \t]{0,8})${NOT_A_REFERENCE}(${AUTH_SCHEME}[^\s"',]+)`, "gi"),
+    },
+];
+/** Mask the value of every secret-named key in JSON-, dotenv-, shell- or YAML-shaped text. */
+export function redactStructured(text) {
+    let out = text;
+    for (const { re } of STRUCTURED_PATTERNS) {
+        re.lastIndex = 0;
+        out = out.replace(re, (_match, keep) => `${keep}${REDACTED}`);
+    }
+    return out;
+}

package/dist/internal/redact.d.ts

@@ -1,13 +1,6 @@
 /**
- * Secret-redaction helper for the JSONL logger write path.
- *
- * Two layers of protection:
- *  1. Key-based: any field whose name matches SECRET_KEY_PATTERN gets its value
- *     replaced with "[REDACTED]" regardless of content.
- *  2. Pattern-based: free-text strings (in values that did NOT trigger layer 1)
- *     are scanned for token-shaped substrings (API keys, PATs, etc.).
- */
-/**
+ * Matches must pass `acceptMatch`, when present, before masking: the URL scanner also
+ * consumes scheme-only runs to avoid rescanning them on failure.
  * Patterns are reset via `re.lastIndex = 0` before every call because they carry
  * the `/g` flag (required for `String.replace`). Resetting prevents the stale
  * `lastIndex` bug that skips matches on subsequent calls.
@@ -16,6 +9,8 @@
 export interface SecretValuePattern {
     readonly kind: string;
     readonly re: RegExp;
+    /** Reject scanner-only matches that advance past a non-secret run. */
+    readonly acceptMatch?: (match: string) => boolean;
 }
 export declare const SECRET_VALUE_PATTERNS: readonly SecretValuePattern[];
 /**

package/dist/internal/redact.js

@@ -7,6 +7,7 @@
  *  2. Pattern-based: free-text strings (in values that did NOT trigger layer 1)
  *     are scanned for token-shaped substrings (API keys, PATs, etc.).
  */
+import { redactStructured } from "#src/internal/redact-structured";
 // TOKEN(?!s\b) prevents matching plural metric keys like "tokens", "inputTokens",
 // "totalTokens" (which are counts, not credentials) while still matching "token",
 // "GITHUB_TOKEN", "accessToken", etc.
@@ -90,16 +91,33 @@ export const SECRET_VALUE_PATTERNS = [
     //   postgres://admin:s3cret@db.internal:5432/prod  →  "postgres://admin:s3cret@"
     //   redis://:hunter2@cache.internal:6379/0          →  "redis://:hunter2@"     (empty user)
     //   mongodb://root:mongoPwd@mongo.internal:27017    →  "mongodb://root:mongoPwd@"
-    { kind: "url-credentials", re: /\b[a-z][a-z0-9+.-]*:\/\/(?:[^/\s@]*:[^/\s@]+)@/gi },
+    // Issue #2428: requiring the credential suffix made a failed scheme run
+    // rescan at every word boundary (quadratic on "a-b-c-..."). Consume the
+    // whole run even without credentials; acceptMatch leaves those
+    // non-secret matches visible. This preserves the original word boundary
+    // and supports arbitrary scheme lengths without rescanning the run.
+    {
+        kind: "url-credentials",
+        re: /\b[a-z][a-z0-9+.-]*(?::\/\/(?:[^/\s@]*:[^/\s@]+)@)?/gi,
+        acceptMatch: (match) => match.endsWith("@"),
+    },
 ];
 const REDACTED = "[REDACTED]";
+/**
+ * Kinds that `redactStructured` supersedes for text redaction. They consume
+ * the key (`API_TOKEN=abc` -> `API_[REDACTED]`); the structured pass masks only
+ * the value. They stay in `SECRET_VALUE_PATTERNS` for the shell-span masker.
+ */
+const STRUCTURED_KINDS = new Set(["assignment", "api-key-header"]);
 function redactString(value) {
     let out = value;
-    for (const { re } of SECRET_VALUE_PATTERNS) {
+    for (const { kind, re, acceptMatch } of SECRET_VALUE_PATTERNS) {
+        if (STRUCTURED_KINDS.has(kind))
+            continue;
         re.lastIndex = 0;
-        out = out.replace(re, REDACTED);
+        out = out.replace(re, (match) => (acceptMatch && !acceptMatch(match) ? match : REDACTED));
     }
-    return out;
+    return redactStructured(out);
 }
 /**
  * Recursively walk `input` and return a new value with secrets removed.

package/dist/internal.d.ts

@@ -59,6 +59,7 @@ export * from "#src/native/model-resolver";
 export * from "#src/native/models";
 export * from "#src/native/provider-models";
 export * from "#src/native/session/compaction";
+export { compactionSettingsSchema, DEFAULT_COMPACTION, resolveCompaction, } from "#src/native/session/compaction-settings";
 export { DEFAULT_INSTRUCTION_FILE_NAME, isInstructionFileName } from "#src/native/session/instruction-file-name";
 export * from "#src/native/session/loop-events/external-handler";
 export * from "#src/native/session/loop-events/index";

package/dist/internal.js

@@ -59,6 +59,7 @@ export * from "#src/native/model-resolver";
 export * from "#src/native/models";
 export * from "#src/native/provider-models";
 export * from "#src/native/session/compaction";
+export { compactionSettingsSchema, DEFAULT_COMPACTION, resolveCompaction, } from "#src/native/session/compaction-settings";
 export { DEFAULT_INSTRUCTION_FILE_NAME, isInstructionFileName } from "#src/native/session/instruction-file-name";
 export * from "#src/native/session/loop-events/external-handler";
 export * from "#src/native/session/loop-events/index";

package/dist/native/session/compaction-settings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The compaction settings schema, shared by nax (`execution.compaction`) and the
+ * facade's native backend (`NativeBackendOptions.compaction`). One definition,
+ * so the two surfaces cannot drift on ranges, defaults or messages.
+ *
+ * Percentages of the model's window rather than absolute token counts:
+ * nax-ai's catalog spans 4095 to 3.5M tokens, and an absolute reserve is
+ * negative on the smallest windows -- compaction would fire every round trip
+ * and shrink nothing.
+ */
+import { z } from "zod";
+import type { ResolvedCompaction } from "./compaction.ts";
+export declare const DEFAULT_COMPACTION: ResolvedCompaction;
+export declare const compactionSettingsSchema: z.ZodDefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    compactAtPercent: z.ZodDefault<z.ZodNumber>;
+    keepRecentPercent: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+/** Applies the defaults to a raw settings object. Throws a ZodError on an invalid one. */
+export declare function resolveCompaction(input?: unknown): ResolvedCompaction;

package/dist/native/session/compaction-settings.js

@@ -0,0 +1,26 @@
+/**
+ * The compaction settings schema, shared by nax (`execution.compaction`) and the
+ * facade's native backend (`NativeBackendOptions.compaction`). One definition,
+ * so the two surfaces cannot drift on ranges, defaults or messages.
+ *
+ * Percentages of the model's window rather than absolute token counts:
+ * nax-ai's catalog spans 4095 to 3.5M tokens, and an absolute reserve is
+ * negative on the smallest windows -- compaction would fire every round trip
+ * and shrink nothing.
+ */
+import { z } from "zod";
+export const DEFAULT_COMPACTION = { enabled: true, compactAtPercent: 90, keepRecentPercent: 30 };
+export const compactionSettingsSchema = z
+    .object({
+    enabled: z.boolean().default(DEFAULT_COMPACTION.enabled),
+    compactAtPercent: z.number().int().min(50).max(99).default(DEFAULT_COMPACTION.compactAtPercent),
+    keepRecentPercent: z.number().int().min(5).max(79).default(DEFAULT_COMPACTION.keepRecentPercent),
+})
+    .refine((c) => c.keepRecentPercent <= c.compactAtPercent - 20, {
+    message: "keepRecentPercent must be at least 20 points below compactAtPercent",
+})
+    .default({ ...DEFAULT_COMPACTION });
+/** Applies the defaults to a raw settings object. Throws a ZodError on an invalid one. */
+export function resolveCompaction(input) {
+    return compactionSettingsSchema.parse(input);
+}

package/dist/permissions/secret-spans.js

@@ -28,13 +28,14 @@ function referencesVariable(kind, match) {
             .startsWith("$"));
 }
 function rawSpans(text) {
-    return SECRET_VALUE_PATTERNS.flatMap(({ kind, re }) => {
+    return SECRET_VALUE_PATTERNS.flatMap(({ kind, re, acceptMatch }) => {
         // A private copy: the shared /g regex carries lastIndex between callers.
         const scan = new RegExp(re.source, re.flags);
         const found = [];
         for (let m = scan.exec(text); m !== null; m = scan.exec(text)) {
-            if (!referencesVariable(kind, m[0]))
+            if ((!acceptMatch || acceptMatch(m[0])) && !referencesVariable(kind, m[0])) {
                 found.push({ start: m.index, end: m.index + m[0].length, kind });
+            }
         }
         return found;
     });

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

@@ -15,6 +15,18 @@ export interface NativeBackendOptions {
     readonly allowUnsandboxed?: boolean;
     /** Keep a resumed or continued conversation when the model differs (ACP server model switch, S5-3). */
     readonly carryHistoryAcrossModels?: boolean;
+    /**
+     * Context compaction for the session's history. On by default: a history that
+     * crosses `compactAtPercent` of the model's window is summarised (one billed
+     * model call) and a context overflow is compacted and retried once. Percentages
+     * are of the window; `keepRecentPercent` must sit at least 20 points below
+     * `compactAtPercent`. `{ enabled: false }` turns it off.
+     */
+    readonly compaction?: {
+        readonly enabled?: boolean;
+        readonly compactAtPercent?: number;
+        readonly keepRecentPercent?: number;
+    };
 }
 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 { compactionSettingsSchema } from "#src/native/session/compaction-settings";
 import { isInstructionFileName } from "#src/native/session/instruction-file-name";
 import { AgentSessionError } from "./agent-session-errors.js";
 function isRecord(value) {
@@ -37,6 +38,7 @@ const OptionsSchema = z.strictObject({
     bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
     allowUnsandboxed: z.boolean().optional(),
     carryHistoryAcrossModels: z.boolean().optional(),
+    compaction: compactionSettingsSchema.optional(),
 });
 function invalid(message, context = {}) {
     return new AgentSessionError(`Invalid agent session options: ${message}`, "AGENT_SESSION_INVALID_OPTIONS", context);

package/dist/session/native-backend.js

@@ -6,6 +6,7 @@
  */
 import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
 import { NATIVE_AGENT } from "#src/native/models";
+import { resolveCompaction } from "#src/native/session/compaction-settings";
 import { transcriptModelIdentity } from "#src/native/session/transcript-identity";
 import { NativeSessionAdapter } from "#src/native/session-adapter";
 import { AgentSessionError } from "./agent-session-errors.js";
@@ -84,6 +85,7 @@ async function openNative(resolved, ctx) {
         resume: ctx.resume !== undefined,
         spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
         transportRetry: SESSION_TRANSPORT_RETRY,
+        compaction: resolveCompaction(raw.compaction),
         ...(raw.carryHistoryAcrossModels === true ? { carryHistoryAcrossModels: true } : {}),
         ...(ctx.instructions !== undefined && ctx.instructions !== "" ? { systemPrompt: ctx.instructions } : {}),
     });

package/dist/terminal-auth/interaction.js

@@ -25,7 +25,11 @@ export function createTerminalAuthInteraction(options) {
             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 promptForSelect(prompt.message, prompt.options.map((option) => ({
+                    id: option.id,
+                    label: option.label,
+                    ...(option.description !== undefined ? { description: option.description } : {}),
+                })), style);
             }
             return promptForSecret(prompt.message, style);
         },

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

@@ -42,10 +42,15 @@ export declare function promptForLine(message: string, onEmptySubmit?: () => voi
 export interface SelectChoice {
     readonly id: string;
     readonly label: string;
+    readonly description?: 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.
+ * option block is redrawn in place, so a value that is not an option can never
+ * be returned. Typed characters narrow the block rather than answering it: a
+ * catalog-sized list is scrolled by filtering, not printed whole, and the redraw
+ * moves up only by the rows it drew — a block taller than the terminal cannot be
+ * repainted, because the cursor-up cannot cross the scrollback. Enter with no
+ * match commits nothing.
  */
 export declare function promptForSelect(message: string, choices: readonly SelectChoice[], style?: TerminalStyle): Promise<string>;

package/dist/terminal-auth/prompt.js

@@ -120,10 +120,95 @@ export function promptForSecret(message, style = PLAIN_STYLE) {
 export function promptForLine(message, onEmptySubmit, style = PLAIN_STYLE) {
     return read(message, true, onEmptySubmit, style);
 }
+/** Rows drawn at once. A longer list is narrowed by typing, never printed whole. */
+const MAX_VISIBLE_ROWS = 12;
+/** Case-insensitive label match; an empty filter matches everything. */
+function matchedRows(choices, filter) {
+    const needle = filter.toLowerCase();
+    return needle === "" ? [...choices] : choices.filter((c) => c.label.toLowerCase().includes(needle));
+}
+/** The first row index the window must show so that `active` is visible. */
+function windowStart(active, total) {
+    return Math.min(active, Math.max(0, total - MAX_VISIBLE_ROWS));
+}
+function drawSelectLine(run, text) {
+    _terminalPromptDeps.write(`\r\u001b[2K${text}\n`);
+    run.drawn += 1;
+}
+function drawSelectRow(run, choice, isActive) {
+    const marker = isActive ? run.style.accent(">") : " ";
+    const label = isActive ? run.style.accent(choice.label) : choice.label;
+    const note = isActive && choice.description !== undefined ? ` ${run.style.dim(choice.description)}` : "";
+    drawSelectLine(run, `${marker} ${label}${note}`);
+}
+function renderSelect(run) {
+    const rows = matchedRows(run.choices, run.filter);
+    if (run.active >= rows.length)
+        run.active = 0;
+    const start = windowStart(run.active, rows.length);
+    if (run.drawn > 0)
+        _terminalPromptDeps.write(`\u001b[${run.drawn}A`);
+    run.drawn = 0;
+    drawSelectLine(run, run.style.dim(run.filter));
+    for (const [i, choice] of rows.slice(start, start + MAX_VISIBLE_ROWS).entries()) {
+        drawSelectRow(run, choice, start + i === run.active);
+    }
+}
+function moveSelect(run, delta) {
+    const rows = matchedRows(run.choices, run.filter);
+    if (rows.length > 0)
+        run.active = (run.active + delta + rows.length) % rows.length;
+    renderSelect(run);
+}
+function cleanupSelect(run) {
+    if (run.settled)
+        return;
+    run.settled = true;
+    run.stdin.removeListener("data", run.onData);
+    run.stdin.removeListener("end", run.onEnd);
+    run.stdin.removeListener("error", run.onEnd);
+    run.stdin.setRawMode(false);
+    run.stdin.pause();
+}
+function endSelect(run) {
+    cleanupSelect(run);
+    run.reject();
+}
+function handleSelectKey(run, chunk) {
+    // Whole-chunk matching: an arrow key is a three-byte escape sequence.
+    if (chunk.includes(ETX) || chunk.includes(EOT)) {
+        endSelect(run);
+        return;
+    }
+    if (chunk.includes(ARROW_UP)) {
+        moveSelect(run, -1);
+        return;
+    }
+    if (chunk.includes(ARROW_DOWN)) {
+        moveSelect(run, 1);
+        return;
+    }
+    if (chunk.includes(CR) || chunk.includes(LF)) {
+        const rows = matchedRows(run.choices, run.filter);
+        if (rows.length === 0)
+            return;
+        cleanupSelect(run);
+        // biome-ignore lint/style/noNonNullAssertion: active is held below rows.length by renderSelect and the guard above.
+        run.resolve(rows[run.active].id);
+        return;
+    }
+    run.filter = chunk.includes(BACKSPACE) ? run.filter.slice(0, -1) : run.filter + chunk;
+    run.active = 0;
+    renderSelect(run);
+}
 /**
  * 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.
+ * option block is redrawn in place, so a value that is not an option can never
+ * be returned. Typed characters narrow the block rather than answering it: a
+ * catalog-sized list is scrolled by filtering, not printed whole, and the redraw
+ * moves up only by the rows it drew — a block taller than the terminal cannot be
+ * repainted, because the cursor-up cannot cross the scrollback. Enter with no
+ * match commits nothing.
  */
 export function promptForSelect(message, choices, style = PLAIN_STYLE) {
     const stdin = stdinOf();
@@ -134,63 +219,25 @@ export function promptForSelect(message, choices, style = PLAIN_STYLE) {
         return Promise.reject(new PromptCancelledError());
     _terminalPromptDeps.write(`${style.accent("?")} ${message}\n`);
     return new Promise((resolve, reject) => {
-        let index = 0;
-        let settled = false;
-        let drawn = false;
-        const render = () => {
-            if (drawn)
-                _terminalPromptDeps.write(`\u001b[${choices.length}A`);
-            drawn = true;
-            for (const [i, choice] of choices.entries()) {
-                const active = i === index;
-                const marker = active ? style.accent(">") : " ";
-                const label = active ? style.accent(choice.label) : choice.label;
-                _terminalPromptDeps.write(`\r\u001b[2K${marker} ${label}\n`);
-            }
-        };
-        const cleanup = () => {
-            if (settled)
-                return;
-            settled = true;
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            stdin.removeListener("error", onEnd);
-            stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onEnd = () => {
-            cleanup();
-            reject(new PromptCancelledError());
-        };
-        const onData = (chunk) => {
-            // Whole-chunk matching: an arrow key is a three-byte escape sequence.
-            if (chunk.includes(ETX) || chunk.includes(EOT)) {
-                onEnd();
-                return;
-            }
-            if (chunk.includes(ARROW_UP)) {
-                index = (index - 1 + choices.length) % choices.length;
-                render();
-                return;
-            }
-            if (chunk.includes(ARROW_DOWN)) {
-                index = (index + 1) % choices.length;
-                render();
-                return;
-            }
-            if (chunk.includes(CR) || chunk.includes(LF)) {
-                const chosen = choices[index];
-                cleanup();
-                // biome-ignore lint/style/noNonNullAssertion: index is held in range by the modulo above.
-                resolve(chosen.id);
-            }
+        const run = {
+            choices,
+            style,
+            stdin,
+            resolve,
+            reject: () => reject(new PromptCancelledError()),
+            onData: (chunk) => handleSelectKey(run, chunk),
+            onEnd: () => endSelect(run),
+            filter: "",
+            active: 0,
+            drawn: 0,
+            settled: false,
         };
         stdin.setRawMode(true);
         stdin.resume();
         stdin.setEncoding("utf8");
-        stdin.on("data", onData);
-        stdin.once("end", onEnd);
-        stdin.once("error", onEnd);
-        render();
+        stdin.on("data", run.onData);
+        stdin.once("end", run.onEnd);
+        stdin.once("error", run.onEnd);
+        renderSelect(run);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -46,8 +46,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@nathapp/nax-ai": "0.85.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@nathapp/nax-ai": "0.86.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {