@nathapp/nax-agent 0.85.0 → 0.85.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.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,12 +1,3 @@
-/**
- * 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.).
- */
 /**
  * Patterns are reset via `re.lastIndex = 0` before every call because they carry
  * the `/g` flag (required for `String.replace`). Resetting prevents the stale

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.
@@ -93,13 +94,21 @@ export const SECRET_VALUE_PATTERNS = [
     { kind: "url-credentials", re: /\b[a-z][a-z0-9+.-]*:\/\/(?:[^/\s@]*:[^/\s@]+)@/gi },
 ];
 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 } of SECRET_VALUE_PATTERNS) {
+        if (STRUCTURED_KINDS.has(kind))
+            continue;
         re.lastIndex = 0;
         out = out.replace(re, 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.85.0",
+  "version": "0.85.1",
   "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.85.1",
     "zod": "^4.3.6"
   },
   "publishConfig": {