@nathapp/nax-agent 0.84.0 → 0.85.1

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+
+- `listProviderModels(providerId, catalogOverrides?)` and `ProviderModel`: the tool-capable models the catalog offers for one provider, as plain data (#2414).
+
 ## [0.84.0] - 2026-10-09
 
 - Versioning: released in lockstep with `@nathapp/nax`, `@nathapp/nax-ai` and the other agent package at one shared version, starting at 0.84.0 (previously 0.3.x).

package/README.md

@@ -16,6 +16,7 @@ Requires **Node.js >= 22.19.0**. The package is ESM only and ships no Bun code:
 
 - **`@nathapp/nax-agent`** is the supported entry. Every export is named, and none starts with `_`. Its exact names are pinned in [`api/nax-agent.api.txt`](api/nax-agent.api.txt), which CI compares with the built declarations.
 - **`@nathapp/nax-agent/internal`** is **nax-only and outside semver.** nax bundles this package and reaches below the public entry for shared helpers, `NaxError`, deep modules and the `_*Deps` test seams. Names, shapes and behaviour there can change in any release, patch included, and a change there is not a breaking change. Do not import it from another project.
+- **`@nathapp/nax-agent/mcp`** — the shared MCP connection layer; see below.
 
 ## Process-wide slots
 
@@ -85,18 +86,45 @@ 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.
 - **History and restarts.** The store holds one document per session, saved at the end of every turn. `close()` keeps it. After a restart, `resumeAgentSession(sessionId, options)` reopens it with the same options you created it with; pass `instructions` and `tools` again, since they are not stored. If the process died mid-turn, `session.lastTurn` is `{ turnId, status: "interrupted" }`, and that turn's message is not in history. A resume with a different model throws `AGENT_SESSION_MODEL_MISMATCH`; a different reasoning effort (`[high]`) is the same model. Resuming with a different backend kind throws `AGENT_SESSION_BACKEND_MISMATCH`; a stored document with no `backend` field is native. Do not open one session id twice at once: the store has no lock.
 - **Errors.** Every error is an `AgentSessionError` with a code `AGENT_SESSION_*`: `INVALID_OPTIONS`, `EXISTS`, `BUSY`, `CLOSED`, `INVALID_ANSWER`, `NOT_FOUND`, `SCHEMA_UNSUPPORTED`, `MODEL_MISMATCH`, `SANDBOX_UNAVAILABLE`, `TOOL_NAME_RESERVED`, `BACKEND_UNAVAILABLE`, `AUTH_REQUIRED`, `CAPABILITY_UNSUPPORTED` or `BACKEND_MISMATCH`. A stored document that cannot be read is a `NaxError` with `TRANSCRIPT_CORRUPT`.
 
+## MCP connections (`@nathapp/nax-agent/mcp`)
+
+A small MCP client for embedders that bridge MCP servers into their own tools.
+The root entry never loads it.
+
+```ts
+import { connectMcp } from "@nathapp/nax-agent/mcp";
+
+const connection = await connectMcp(
+  { kind: "stdio", command: "my-mcp-server", args: [], env: { API_KEY: "..." }, cwd: "/repo" },
+  { signal, timeoutMs: 30_000, clientInfo: { name: "my-app", version: "1.0.0" } },
+);
+connection.tools;                                   // listed once, every page
+await connection.call("search", { q: "x" }, { signal, timeoutMs: 600_000, maxBytes: 1_048_576 });
+await connection.close();                           // waits for the process; SIGKILL after 3 s
+```
+
+- Transports: `stdio` and streamable `http` (with `headers`). SSE is not supported.
+- `env` is laid over the default environment, so `PATH` is kept. Server stderr is
+  never inherited; its last 512 bytes are attached to a connect failure.
+- A server-side tool error is a result with `isError: true`; protocol errors,
+  timeouts, aborts and closed connections throw `McpCallError`.
+- `onClose` reports a stdio server that exits on its own; HTTP has no such signal.
+- The facade (`createAgentSession`) has no `mcpServers` option: wrap MCP tools as
+  `EmbedderTool`s yourself.
+
 ## Status and roadmap
 
 `0.x` may reshape `.` with a minor bump. `@nathapp/nax-agent-acp` provides an ACP backend for the same API (0.3.0). See [`CHANGELOG.md`](CHANGELOG.md).

package/dist/config/catalog-overrides.d.ts

@@ -52,6 +52,18 @@ export interface OpenRouterRouting {
     ignore?: readonly string[];
     quantizations?: readonly string[];
     sort?: "price" | "throughput" | "latency";
+    preferred_min_throughput?: number | {
+        p50?: number;
+        p75?: number;
+        p90?: number;
+        p99?: number;
+    };
+    preferred_max_latency?: number | {
+        p50?: number;
+        p75?: number;
+        p90?: number;
+        p99?: number;
+    };
 }
 /**
  * One complete catalog entry for a model the bundled pi-ai snapshot does not

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
 export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, type TerminalAuthOptions, type TerminalStyle, } from "#src/terminal-auth/index";
 export type { CredentialSource } from "#src/native/credentials/session-source";
-export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
+export { AuthCancelledError, type AuthEvent, type AuthInteraction, type AuthLink, type AuthMethod, type AuthOption, type AuthPrompt, type AuthResult, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, type ImportOutcome, importPiCredentials, listProviderModels, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, type MemoryTranscriptStore, NATIVE_AGENT, type NativeCatalogOverrides, type NativeCompleteContext, type NativeCompleteOptions, type NativeCompleteResult, NativeSessionAdapter, NativeSessionUnsupportedError, type NativeTierConfig, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, type ProviderModel, providersWithoutCredentials, pruneRetainedTranscripts, type ResolveResult, type ResolveStatus, removeStoredProvider, resolveNativeId, runLogin, type StoredEntry, servedAuth, type TranscriptAcpRecord, type TranscriptDoc, type TranscriptStore, type TurnMarker, } from "#src/native/index";
 export type { NativeSessionAdapterOptions } from "#src/native/session-adapter";
 export type { AfterResponsePatch, AfterResponsePayload, AfterToolPatch, AfterToolPayload, BeforeCompactionPatch, BeforeCompactionPayload, BeforeRequestPatch, BeforeRequestPayload, BeforeToolOutcome, BeforeToolPayload, BeforeTurnEndPatch, BeforeTurnEndPayload, BeforeTurnPatch, BeforeTurnPayload, CompleteCallOptions, ExternalHandlerOf, LoopEvent, LoopEventMap, LoopHandlerContext, LoopHandlerEntry, LoopHandlerSet, PatchOf, PayloadOf, TransformContextPatch, TransformContextPayload, } from "#src/native/session/loop-events/types";
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";

package/dist/index.js

@@ -17,7 +17,7 @@ export { killProcessGroup } from "#src/internal/process-kill";
 export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
 export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, } from "#src/terminal-auth/index";
-export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
+export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listProviderModels, listStoredProviders, loginProviderIds, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
 export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, appendApproval, appendApprovalAudit, approvalId, approvalsPath, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, maskForPrompt, parseRuleList, parseToolExpression, prepareApprovalsStore, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";

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

@@ -57,7 +57,9 @@ export * from "#src/native/credentials/index";
 export * from "#src/native/errors";
 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

@@ -57,7 +57,9 @@ export * from "#src/native/credentials/index";
 export * from "#src/native/errors";
 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/mcp/connect.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectMcpOptions, McpConnection, McpTransportConfig } from "#src/mcp/types";
+export declare const DEFAULT_CLOSE_GRACE_MS = 3000;
+export declare function connectMcp(config: McpTransportConfig, opts: ConnectMcpOptions): Promise<McpConnection>;

package/dist/mcp/connect.js

@@ -0,0 +1,144 @@
+/**
+ * connectMcp (S5-5 spec §3.1): one MCP server over stdio or streamable HTTP.
+ * Connect (initialize + every tools/list page) is bounded by timeoutMs and the
+ * caller's signal; a call honours its signal and timeout (reset on progress);
+ * close is idempotent, bounded by closeGraceMs, and for stdio resolves only
+ * 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 { McpCallError, McpConnectError } from "#src/mcp/errors";
+import { resultText } from "#src/mcp/result-text";
+import { waitForStdioExit } from "#src/mcp/stdio-close";
+import { _mcpTransportDeps } from "#src/mcp/transport";
+export const DEFAULT_CLOSE_GRACE_MS = 3000;
+const EXIT_REASON = "the server process exited";
+const isRaw = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** Waits for `promise` at most `ms`; the timer is cleared, so nothing keeps the process alive. */
+async function within(promise, ms) {
+    let timer;
+    const limit = new Promise((resolve) => {
+        timer = setTimeout(resolve, ms);
+    });
+    await Promise.race([promise.catch(() => undefined), limit]);
+    clearTimeout(timer);
+}
+function trackLife(client, kind) {
+    const life = { exited: false, closing: false, exitReason: undefined, listeners: [] };
+    client.onclose = () => {
+        life.exited = true;
+        if (life.closing || kind !== "stdio" || life.exitReason !== undefined)
+            return;
+        life.exitReason = EXIT_REASON;
+        for (const listener of life.listeners)
+            listener(EXIT_REASON);
+    };
+    return life;
+}
+async function closeTransport(client, handle, graceMs, life) {
+    life.closing = true;
+    const pid = handle.pid();
+    if (handle.terminate !== undefined)
+        await within(handle.terminate(), graceMs);
+    const closed = client.close();
+    // The stdio path below waits on the process, not on this promise: attach a
+    // handler now so a transport close that later rejects is never unhandled.
+    void closed.catch(() => undefined);
+    if (pid === null)
+        return within(closed, graceMs);
+    await waitForStdioExit(pid, () => life.exited, graceMs);
+}
+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 };
+}
+async function listAll(client, signal, timeout) {
+    const tools = [];
+    let cursor;
+    do {
+        const page = await client.listTools(cursor !== undefined ? { cursor } : undefined, { signal, timeout });
+        for (const raw of page.tools ?? []) {
+            const info = toolInfo(raw);
+            if (info !== undefined)
+                tools.push(info);
+        }
+        cursor = typeof page.nextCursor === "string" && page.nextCursor !== "" ? page.nextCursor : undefined;
+    } while (cursor !== undefined);
+    return tools;
+}
+function connectFailure(error, deadline, opts, handle) {
+    const timedOut = deadline.aborted || (error instanceof McpError && error.code === ErrorCode.RequestTimeout);
+    const reason = timedOut ? `timed out after ${opts.timeoutMs} ms` : messageOf(error);
+    const tail = handle.stderrTail().trim();
+    return new McpConnectError(`MCP connect failed: ${reason}`, tail === "" ? undefined : tail);
+}
+function createHandle(config) {
+    try {
+        return _mcpTransportDeps.create(config);
+    }
+    catch (error) {
+        throw new McpConnectError(`MCP connect failed: ${messageOf(error)}`);
+    }
+}
+export async function connectMcp(config, opts) {
+    const handle = createHandle(config);
+    const client = new Client({ name: opts.clientInfo.name, version: opts.clientInfo.version });
+    const graceMs = opts.closeGraceMs ?? DEFAULT_CLOSE_GRACE_MS;
+    const life = trackLife(client, config.kind);
+    const deadline = AbortSignal.timeout(opts.timeoutMs);
+    const signal = AbortSignal.any([opts.signal, deadline]);
+    try {
+        if (signal.aborted)
+            throw new McpConnectError("MCP connect failed: aborted");
+        await client.connect(handle.transport, { signal, timeout: opts.timeoutMs });
+        const tools = await listAll(client, signal, opts.timeoutMs);
+        return liveConnection(config, client, handle, tools, { graceMs, life });
+    }
+    catch (error) {
+        await closeTransport(client, handle, graceMs, life);
+        throw error instanceof McpConnectError ? error : connectFailure(error, deadline, opts, handle);
+    }
+}
+async function callTool(client, name, input, opts) {
+    try {
+        const raw = await client.callTool({ name, arguments: isRaw(input) ? { ...input } : {} }, undefined, {
+            signal: opts.signal,
+            timeout: opts.timeoutMs,
+            resetTimeoutOnProgress: true,
+            // The SDK sends a progressToken (so servers can report progress and reset
+            // the timeout) only when onprogress is set (shared/protocol.js:643-650).
+            onprogress: () => undefined,
+        });
+        return resultText(raw, opts.maxBytes);
+    }
+    catch (error) {
+        throw new McpCallError(`MCP call ${name} failed: ${messageOf(error)}`);
+    }
+}
+function liveConnection(config, client, handle, tools, state) {
+    let closing;
+    const { life } = state;
+    return {
+        kind: config.kind,
+        tools,
+        call(name, input, opts) {
+            if (closing !== undefined || life.exited)
+                return Promise.reject(new McpCallError(`MCP call ${name} failed: the connection is closed`));
+            return callTool(client, name, input, opts);
+        },
+        onClose(listener) {
+            // An exit before anyone listened (spec §4.5, plan review I3) is still reported, once.
+            if (life.exitReason !== undefined)
+                listener(life.exitReason);
+            else
+                life.listeners.push(listener);
+        },
+        close() {
+            closing ??= closeTransport(client, handle, state.graceMs, life);
+            return closing;
+        },
+    };
+}

package/dist/mcp/errors.d.ts

@@ -0,0 +1,9 @@
+/** Errors of the shared MCP layer (S5-5 spec §3.1, plan M-42). */
+import { NaxError } from "#src/infra/nax-error";
+export declare class McpConnectError extends NaxError {
+    readonly stderrTail?: string | undefined;
+    constructor(message: string, stderrTail?: string | undefined, context?: Record<string, unknown>);
+}
+export declare class McpCallError extends NaxError {
+    constructor(message: string, context?: Record<string, unknown>);
+}

package/dist/mcp/errors.js

@@ -0,0 +1,16 @@
+/** Errors of the shared MCP layer (S5-5 spec §3.1, plan M-42). */
+import { NaxError } from "#src/infra/nax-error";
+export class McpConnectError extends NaxError {
+    stderrTail;
+    constructor(message, stderrTail, context = {}) {
+        super(message, "MCP_CONNECT_FAILED", context);
+        this.stderrTail = stderrTail;
+        this.name = "McpConnectError";
+    }
+}
+export class McpCallError extends NaxError {
+    constructor(message, context = {}) {
+        super(message, "MCP_CALL_FAILED", context);
+        this.name = "McpCallError";
+    }
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@nathapp/nax-agent/mcp`: the shared MCP connection layer (S5-5 spec §3.1).
+ * Never imported from the root entry, so `@nathapp/nax-agent` alone never loads
+ * the MCP SDK.
+ */
+export { connectMcp, DEFAULT_CLOSE_GRACE_MS } from "#src/mcp/connect";
+export { McpCallError, McpConnectError } from "#src/mcp/errors";
+export { resultText } from "#src/mcp/result-text";
+export type { ConnectMcpOptions, McpCallOptions, McpCallResult, McpConnection, McpToolInfo, McpTransportConfig, } from "#src/mcp/types";

package/dist/mcp/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@nathapp/nax-agent/mcp`: the shared MCP connection layer (S5-5 spec §3.1).
+ * Never imported from the root entry, so `@nathapp/nax-agent` alone never loads
+ * the MCP SDK.
+ */
+export { connectMcp, DEFAULT_CLOSE_GRACE_MS } from "#src/mcp/connect";
+export { McpCallError, McpConnectError } from "#src/mcp/errors";
+export { resultText } from "#src/mcp/result-text";

package/dist/mcp/result-text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A `tools/call` result as text (S5-5 spec §5.4). Text items are kept; embedded
+ * text resources keep their uri; binary content becomes a one-line placeholder;
+ * structuredContent is printed only when no text item exists. Capped at
+ * maxBytes on a code point boundary.
+ */
+import type { McpCallResult } from "#src/mcp/types";
+export declare function resultText(raw: unknown, maxBytes: number): McpCallResult;

package/dist/mcp/result-text.js

@@ -0,0 +1,38 @@
+import { cutToByteCap } from "#src/tools/truncate";
+const isItem = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === "string" ? value : undefined);
+function resourceText(resource) {
+    if (!isItem(resource))
+        return "[resource omitted]";
+    const text = str(resource.text);
+    if (text !== undefined)
+        return `${str(resource.uri) ?? ""}\n${text}`;
+    return `[resource omitted: ${str(resource.mimeType) ?? "binary"}]`;
+}
+function itemText(item) {
+    switch (item.type) {
+        case "text":
+            return str(item.text) ?? "";
+        case "resource":
+            return resourceText(item.resource);
+        case "image":
+        case "audio":
+            return `[${item.type} omitted: ${str(item.mimeType) ?? "unknown"}]`;
+        case "resource_link":
+            return `[resource link: ${str(item.uri) ?? ""}]`;
+        default:
+            return `[${String(item.type ?? "unknown")} content omitted]`;
+    }
+}
+export function resultText(raw, maxBytes) {
+    const body = isItem(raw) ? raw : {};
+    const items = Array.isArray(body.content) ? body.content.filter(isItem) : [];
+    const hasText = items.some((item) => item.type === "text");
+    const parts = items.map(itemText);
+    if (!hasText && body.structuredContent !== undefined)
+        parts.push(JSON.stringify(body.structuredContent));
+    const full = parts.join("\n\n");
+    const bytes = Buffer.byteLength(full, "utf8");
+    const text = bytes <= maxBytes ? full : `${cutToByteCap(full, maxBytes)}\n[truncated: ${bytes} bytes in total]`;
+    return { text, isError: body.isError === true, bytesBeforeCap: bytes };
+}

package/dist/mcp/stdio-close.d.ts

@@ -0,0 +1 @@
+export declare function waitForStdioExit(pid: number, exited: () => boolean, graceMs: number): Promise<void>;

package/dist/mcp/stdio-close.js

@@ -0,0 +1,31 @@
+/**
+ * After close(), wait for an MCP stdio child to exit (S5-5 spec §3.1, I1). The
+ * SDK ends stdin, then SIGTERM after 2 s, then SIGKILL after 2 s more, on
+ * unref()'d timers: a server process exiting in between could orphan the child.
+ * These timers are ref'd, and after graceMs the child is SIGKILLed here.
+ */
+import { isProcessAlive } from "#src/internal/process-alive";
+const POLL_MS = 25;
+const AFTER_KILL_MS = 1000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitUntil(gone, ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        if (gone())
+            return true;
+        await sleep(POLL_MS);
+    }
+    return gone();
+}
+export async function waitForStdioExit(pid, exited, graceMs) {
+    const gone = () => exited() || !isProcessAlive(pid);
+    if (await waitUntil(gone, graceMs))
+        return;
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        return; // ESRCH: it exited between the probe and the kill
+    }
+    await waitUntil(gone, AFTER_KILL_MS);
+}

package/dist/mcp/transport.d.ts

@@ -0,0 +1,14 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpTransportConfig } from "#src/mcp/types";
+export declare const STDERR_TAIL_BYTES = 512;
+export interface TransportHandle {
+    readonly transport: Transport;
+    readonly pid: () => number | null;
+    readonly stderrTail: () => string;
+    /** http: DELETE the MCP session, best effort. */
+    readonly terminate?: () => Promise<void>;
+}
+/** Injectable seam: unit tests return an in-memory transport. */
+export declare const _mcpTransportDeps: {
+    create: (config: McpTransportConfig) => TransportHandle;
+};

package/dist/mcp/transport.js

@@ -0,0 +1,41 @@
+/**
+ * The SDK transport for one McpTransportConfig (S5-5 spec §3.1). The only file
+ * besides connect.ts that imports the SDK. stdio: the env is an overlay on the
+ * SDK's default environment (SDK 1.30.0 already merges; passing it explicitly
+ * keeps PATH if a later SDK stops), and stderr is piped with a bounded tail
+ * kept for connect-failure messages, never inherited (stdout may carry ACP
+ * frames). http: streamable HTTP with the configured headers.
+ */
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const STDERR_TAIL_BYTES = 512;
+function stdioHandle(config) {
+    const transport = new StdioClientTransport({
+        command: config.command,
+        args: [...config.args],
+        env: { ...getDefaultEnvironment(), ...config.env },
+        cwd: config.cwd,
+        stderr: "pipe",
+    });
+    let tail = Buffer.alloc(0);
+    transport.stderr?.on("data", (chunk) => {
+        const joined = Buffer.concat([tail, chunk]);
+        tail = joined.subarray(Math.max(0, joined.length - STDERR_TAIL_BYTES));
+    });
+    return { transport, pid: () => transport.pid, stderrTail: () => tail.toString("utf8") };
+}
+function httpHandle(config) {
+    const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: { headers: { ...config.headers } },
+    });
+    return {
+        transport,
+        pid: () => null,
+        stderrTail: () => "",
+        terminate: () => transport.terminateSession().catch(() => undefined),
+    };
+}
+/** Injectable seam: unit tests return an in-memory transport. */
+export const _mcpTransportDeps = {
+    create: (config) => config.kind === "stdio" ? stdioHandle(config) : httpHandle(config),
+};

package/dist/mcp/types.d.ts

@@ -0,0 +1,48 @@
+/** Vocabulary of the shared MCP connection layer (S5-5 spec §3.1). Free of SDK types. */
+import type { JSONSchema } from "#src/session/tool-descriptor";
+export type McpTransportConfig = {
+    readonly kind: "stdio";
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd: string;
+} | {
+    readonly kind: "http";
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+};
+export interface McpToolInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+}
+export interface McpCallResult {
+    readonly text: string;
+    readonly isError: boolean;
+    readonly bytesBeforeCap: number;
+}
+export interface McpCallOptions {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+    readonly maxBytes: number;
+}
+export interface McpConnection {
+    readonly kind: "stdio" | "http";
+    readonly tools: readonly McpToolInfo[];
+    /** Server-side tool errors are `isError` results; transport failures throw McpCallError. */
+    call(name: string, input: unknown, opts: McpCallOptions): Promise<McpCallResult>;
+    /** stdio only: called once when the process exits without close() having been called. */
+    onClose(listener: (reason: string) => void): void;
+    /** Idempotent. Resolves when the transport, and for stdio the process, is gone. */
+    close(): Promise<void>;
+}
+export interface ConnectMcpOptions {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+    readonly clientInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** stdio: how long close() waits for the process before SIGKILL. Default 3000. */
+    readonly closeGraceMs?: number;
+}

package/dist/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/native/index.d.ts

@@ -19,6 +19,7 @@ export { credentialFilePath, naxCredentialStore, type StoredEntry, servedAuth }
 export { NativeSessionUnsupportedError } from "./errors.ts";
 export { type ResolveResult, type ResolveStatus, resolveNativeId, } from "./model-resolver.ts";
 export { NATIVE_AGENT } from "./models.ts";
+export { listProviderModels, type ProviderModel } from "./provider-models.ts";
 export { createMemoryTranscriptStore, type MemoryTranscriptStore } from "./session/memory-transcript-store.ts";
 export { createFileTranscriptStore, MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.ts";
 export type { TranscriptAcpRecord, TranscriptDoc, TranscriptStore, TurnMarker } from "./session/transcript-types.ts";

package/dist/native/index.js

@@ -17,6 +17,7 @@ export { credentialFilePath, naxCredentialStore, servedAuth } from "./credential
 export { NativeSessionUnsupportedError } from "./errors.js";
 export { resolveNativeId, } from "./model-resolver.js";
 export { NATIVE_AGENT } from "./models.js";
+export { listProviderModels } from "./provider-models.js";
 export { createMemoryTranscriptStore } from "./session/memory-transcript-store.js";
 export { createFileTranscriptStore, MAX_RETAINED_TRANSCRIPTS, pruneRetainedTranscripts, } from "./session/transcript-store.js";
 export { NativeSessionAdapter } from "./session-adapter.js";

package/dist/native/provider-models.d.ts

@@ -0,0 +1,13 @@
+import { type NativeCatalogOverrides } from "./client.ts";
+export interface ProviderModel {
+    /** The model id without its provider prefix; the config string is `<provider>/<id>`. */
+    readonly id: string;
+    readonly contextWindow: number;
+    /** The output ceiling, when the catalog states one. */
+    readonly maxTokens?: number;
+}
+/**
+ * Tool-capable models for `providerId`, sorted by id. An unknown provider gives
+ * an empty list. A catalog that cannot load rejects.
+ */
+export declare function listProviderModels(providerId: string, catalogOverrides?: NativeCatalogOverrides): Promise<readonly ProviderModel[]>;

package/dist/native/provider-models.js

@@ -0,0 +1,22 @@
+/**
+ * The models the catalog offers for one provider, as plain data. The catalog is
+ * nax-ai's; nothing here carries a nax-ai type (see check-nax-ai-imports).
+ */
+import { byCodePoint } from "#src/internal/sort";
+import { getNativeClient } from "./client.js";
+/**
+ * Tool-capable models for `providerId`, sorted by id. An unknown provider gives
+ * an empty list. A catalog that cannot load rejects.
+ */
+export async function listProviderModels(providerId, catalogOverrides = []) {
+    const client = await getNativeClient(catalogOverrides);
+    const models = await client.listModels(providerId);
+    return models
+        .filter((model) => model.supportsTools)
+        .map((model) => ({
+        id: model.id,
+        contextWindow: model.contextWindow,
+        ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}),
+    }))
+        .sort((a, b) => byCodePoint(a.id, b.id));
+}

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/dist/tools/denial-redirect.js

@@ -19,7 +19,7 @@
  * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
  * no redirect (nax#1999). A single table cannot drift against itself.
  */
-const GIT_READ_VERBS = new Set(["diff", "log", "show", "status", "blame"]);
+const GIT_READ_VERBS = new Set(["diff", "log", "show", "status", "blame", "rev-parse"]);
 /**
  * Git verbs that stage or record a commit. Deliberately NOT every write verb:
  * `git restore` reverts, which `GitCommit` does not do, and naming it would be

package/dist/tools/git.js

@@ -24,7 +24,7 @@ import { cutToByteCap, READ_CEILING } from "./truncate.js";
  * Note what bounds these: the argv shape below, not the verb list. A read-only
  * verb still spans the whole repository unless its scope is stated.
  */
-export const GIT_READ_VERBS = ["diff", "log", "show", "status", "blame"];
+export const GIT_READ_VERBS = ["diff", "log", "show", "status", "blame", "rev-parse"];
 /**
  * Typed flag fields, and the verbs each one is valid on.
  *
@@ -164,6 +164,16 @@ export { GIT_ESCAPE_FLAGS } from "#src/tools/git-flags/index";
 function looksLikeFlag(value) {
     return value.startsWith("-");
 }
+function buildGitRootArgv(input) {
+    const extraFields = Object.keys(input).filter((field) => field !== "subcommand");
+    if (extraFields.length > 0) {
+        return { error: `rev-parse accepts no additional fields (received: ${extraFields.join(", ")})` };
+    }
+    return ["rev-parse", "--show-toplevel"];
+}
+function defaultGitExcludes(subcommand, excludes) {
+    return subcommand === "blame" ? [] : excludes;
+}
 /**
  * `defaultExcludes`: pathspecs appended to an unscoped call (the host's own
  * state, nax#2007); none by default.
@@ -173,6 +183,9 @@ export function buildGitArgv(input, defaultExcludes = []) {
     if (typeof subcommand !== "string" || !GIT_READ_VERBS.includes(subcommand)) {
         return { error: `subcommand must be one of: ${GIT_READ_VERBS.join(", ")}` };
     }
+    if (subcommand === "rev-parse") {
+        return buildGitRootArgv(input);
+    }
     const refs = Array.isArray(input.refs) ? input.refs : [];
     const paths = Array.isArray(input.paths) ? input.paths : [];
     // No `--relative` is injected. Since the single-frame redesign the permitted
@@ -281,8 +294,7 @@ export function buildGitArgv(input, defaultExcludes = []) {
         // requested path would be a worse failure than the one being fixed.
         // `blame` is exempt because git rejects exclude pathspecs on it and exits
         // 128; do not "unify" it back in.
-        if (subcommand !== "blame")
-            argv.push(...defaultExcludes);
+        argv.push(...defaultGitExcludes(subcommand, defaultExcludes));
         return argv;
     }
     for (const path of paths) {
@@ -296,11 +308,15 @@ export function buildGitArgv(input, defaultExcludes = []) {
 }
 export const gitTool = {
     name: "Git",
-    description: "Run a read-only git command (diff, log, show, status, blame) in the repository. Supply refs and pathspecs as arrays, not as a command line. Command-line flags are not accepted in any field; use the nameOnly, diffFilter, oneline, fullMessage and maxCount fields instead.",
+    description: "Run a read-only git command (diff, log, show, status, blame, rev-parse) in the repository. rev-parse is fixed to `git rev-parse --show-toplevel` and accepts no other fields. Supply refs and pathspecs as arrays, not as a command line. Command-line flags are not accepted in any field; use the nameOnly, diffFilter, oneline, fullMessage and maxCount fields instead.",
     inputSchema: {
         type: "object",
         properties: {
-            subcommand: { type: "string", enum: [...GIT_READ_VERBS], description: "Read-only git subcommand" },
+            subcommand: {
+                type: "string",
+                enum: [...GIT_READ_VERBS],
+                description: "Read-only git subcommand; rev-parse is fixed to --show-toplevel",
+            },
             refs: { type: "array", items: { type: "string" }, description: "Refs, e.g. ['HEAD~1','HEAD']" },
             paths: { type: "array", items: { type: "string" }, description: "Pathspecs, relative to the permitted root" },
             nameOnly: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.84.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",
@@ -29,6 +29,10 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
     }
   },
   "imports": {
@@ -42,7 +46,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@nathapp/nax-ai": "0.84.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@nathapp/nax-ai": "0.85.1",
     "zod": "^4.3.6"
   },
   "publishConfig": {