@nathapp/nax-agent 0.3.1 → 0.85.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.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).
+
+### Added
+
+- `createTerminalAuthInteraction({ log, style?, openUrl? })`, `PromptCancelledError`, `TerminalStyle` and `PLAIN_STYLE`: the terminal login UI (hidden secret entry, arrow-key picker, browser handoff for OAuth), moved from the nax CLI so `nax-agent login` shares it (S5-4).
+- `loginProviderIds()`: the providers `runLogin` can log in to (S5-4).
+- `displayToolInput` and `toolResultPreview`: the live tool-display masking, for replaying stored transcripts (S5-1).
+- `answerable?: false` on the `approval_requested` and `question` session events, set for profile auto-decisions and noted questions (S5-2).
+- `carryHistoryAcrossModels` (`nativeBackend` option and `OpenSessionOpts`): keep a session's history across a model change; each assistant message records its origin model (S5-3).
+
 ## [0.3.1] - 2026-10-07
 
 ### Added

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
 
@@ -37,6 +38,12 @@ Three pieces of host knowledge are passed in as data or functions, because the p
 - **`ProtectedPathsPolicy`** names the paths you own and want kept away from the agent: git pathspecs the Git tool excludes from its default view, gitignore patterns `GitCommit` refuses to stage, the project state directory, the credential directory and the trust-store file the sandbox protects. If you do not supply it, the Git tool excludes nothing from its default view, and `GitCommit` fails closed: it refuses every path and stages nothing until the policy supplies a non-empty `gitIgnorePatterns` (an empty list refuses the same way). Supply it whenever the agent works in a directory that holds files you own. Building a sandboxed session requires it.
 - **`commandInterceptor`** may rewrite a command before it runs (for example to prefix a wrapper binary). Rewrites are validated: an argv rewrite may only prefix the original argv with the provider's own binary, and a shell rewrite goes through the same narrowing. If you do not supply one, commands run unchanged. An interceptor that throws, or returns a rewrite that fails validation, is treated as a decline, and the original command runs.
 
+## Repository instructions
+
+Native sessions load repository-local instructions from the session workdir. In each directory, `AGENTS.override.md` takes precedence over `AGENTS.md`, with `CLAUDE.md` as a fallback. The native adapter's `OpenSessionOpts.instructionDirectories` adds package scopes relative to that workdir; a monorepo session can supply `["apps/api", "packages/client"]` to load each root-to-package chain. `OpenSessionOpts.instructionFileName` selects another Markdown basename, such as `TEAM.md`. A custom name loads only that filename in each directory, with no override or legacy fallback. Names must be nonhidden Markdown basenames without path separators, colon or control characters. More specific directory instructions override ancestor instructions within their scope. Other packages are discovered when authorized file tools enter them.
+
+Local Markdown `@path.md` imports are deduplicated and bounded. Discovery stays inside the active checkout and respects protected paths and denied paths. Each session retains its own instructions outside compactable message history; transcripts record source paths, scopes and hashes. Resume reloads the applicable files from disk using the filename supplied again in the session options. ACP sessions use their CLI's instruction discovery.
+
 ## Conversational sessions
 
 `createAgentSession` gives an embedder (for example a long-running Node service) a multi-turn chat with a person in the loop. Events stream, tools come from the embedder, history lives in a store the embedder supplies, and a turn can be cancelled or answered with an approval.
@@ -79,7 +86,7 @@ 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 `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` and `allowUnsandboxed`. The ACP backend ships in `@nathapp/nax-agent-acp`.
 
 `usage.costSource` is `computed` (native), `reported` or `unpriced`; never sum `unpriced` rows as cost.
 
@@ -91,6 +98,32 @@ Profiles set what a session may do:
 - **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

@@ -18,11 +18,12 @@ export { isProcessAlive } from "#src/internal/process-alive";
 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, 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, 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 { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { displayToolInput, TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES, toolResultPreview, } from "#src/native/session/turn-event-emitter";
 export { type ApprovalAuditRow, type ApprovalEntry, type ApprovalsFile, type ApprovalsFileRead, type ApprovalsFileState, type ApprovalsTaint, ASK_CANCELLED_REASON, ASK_DENIED_REASON, ASK_NO_CHANNEL_REASON, ASK_PROFILE_REASON, ASK_TIMEOUT_REASON, ASK_UNAVAILABLE_REASON, ASK_UNSHOWABLE_REASON, type AskControl, type AskDecidedBy, type AskDecision, type AskLink, type AskLinkOutcome, type AskRequest, type AskResolver, type AskVerdict, appendApproval, appendApprovalAudit, approvalId, approvalsPath, type BashLexResult, type BashRedirect, type BashSegment, type BashSegmentSeparator, type BashToken, type ClearTaintOutcome, chainAskLinks, clearApprovalsTaint, createApprovalsLink, findApproval, findSecretSpans, headlessAskResolver, isForgeCapable, lexBashCommand, type MaskResult, maskForPrompt, type PrepareApprovalsStoreOptions, parseRuleList, parseToolExpression, prepareApprovalsStore, type RemovalDecision, type RemovalResult, type ResolvedPermissions, readApprovals, readApprovalsFile, readApprovalsFileDetailed, redactForRow, redactRowStrings, removeApprovals, type SecretSpan, taintApprovals, writeApprovalsFile, } from "#src/permissions/index";
 export { type AgentGlobOptions, type AgentRuntime, type AgentSpawnOptions, type AgentSpawnResult, type AgentSpawnStdin, getAgentRuntime, nodeRuntime, setAgentRuntime, } from "#src/runtime/index";
 export { buildSandboxPolicy, type CommandLauncher, type CommandLauncherOptions, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, type GitLayout, type LaunchRequest, type LaunchResult, type LaunchSpec, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, type ProbeResult, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, type SandboxBackend, type SandboxBackendName, type SandboxNetworkPolicy, type SandboxPolicy, type SandboxPolicyInput, type SandboxRecord, type SandboxState, type SandboxWrapRequest, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";

package/dist/index.js

@@ -16,8 +16,9 @@ export { isProcessAlive } from "#src/internal/process-alive";
 export { killProcessGroup } from "#src/internal/process-kill";
 export { capStrings, redactSecrets } from "#src/internal/redact";
 export { NaxError } from "#src/infra/nax-error";
-export { AuthCancelledError, ambientShadows, anyAmbientCredential, authImportOutcomeLabel, createFileTranscriptStore, createMemoryTranscriptStore, credentialFilePath, DEFAULT_PI_AUTH_PATH, importPiCredentials, listStoredProviders, MAX_RETAINED_TRANSCRIPTS, NATIVE_AGENT, NativeSessionAdapter, NativeSessionUnsupportedError, nativeComplete, nativeTierProviders, naxCredentialStore, newSessionKey, providersWithoutCredentials, pruneRetainedTranscripts, removeStoredProvider, resolveNativeId, runLogin, servedAuth, } from "#src/native/index";
-export { TOOL_CALL_INPUT_BYTES, TOOL_RESULT_PREVIEW_BYTES } from "#src/native/session/turn-event-emitter";
+export { createTerminalAuthInteraction, PLAIN_STYLE, PromptCancelledError, } from "#src/terminal-auth/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";
 export { buildSandboxPolicy, createCommandLauncher, createSrtBackend, DISABLED_SANDBOX_STATE, defaultTempRoots, denialHintLine, LIKELY_SANDBOX_DENIAL, listCredentialFiles, listGitGuardFiles, listNaxEntries, probeSandbox, probeSandboxOnce, quoteArgvForShell, rawBashRefusalReason, resetSandboxBackend, resolveGitLayout, runTempRoots, runTmpRoot, sandboxBackendFor, sandboxSentence, sessionTmpDir, sessionTmpDirUnder, strayCommonDirTripwire, unsandboxedSentence, warnSandboxUnavailableOnce, } from "#src/sandbox/index";

package/dist/internal/atomic-write.d.ts

@@ -0,0 +1,16 @@
+import { rename, rm } from "node:fs/promises";
+/** The one `writeFile` shape this module uses; narrower than the overloaded node signature so stubs type-check. */
+type WriteText = (path: string, content: string, options: {
+    encoding: "utf8";
+    mode?: number;
+}) => Promise<void>;
+/** Injectable for tests that simulate a write dying part-way. */
+export declare const _atomicWriteDeps: {
+    writeFile: WriteText;
+    rename: typeof rename;
+    rm: typeof rm;
+};
+export declare function writeFileAtomic(path: string, content: string, options?: {
+    mode?: number;
+}): Promise<void>;
+export {};

package/dist/internal/atomic-write.js

@@ -0,0 +1,34 @@
+/**
+ * Whole-file writes that a crash cannot tear.
+ *
+ * `writeFile` truncates the target before the new bytes land, so a process
+ * killed mid-write (SIGKILL, OOM, ENOSPC) leaves a partial file and the old
+ * content is gone. Staging the bytes in a sibling and `rename`-ing it over the
+ * target publishes the new content in one step: a reader, or the next run,
+ * sees the old file or the new one. Same-directory staging keeps the rename on
+ * one filesystem, where POSIX makes it atomic. Not fsync'd: this guards against
+ * a killed PROCESS, not a power loss.
+ */
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+/** Injectable for tests that simulate a write dying part-way. */
+export const _atomicWriteDeps = {
+    writeFile: (path, content, options) => writeFile(path, content, options),
+    rename,
+    rm,
+};
+export async function writeFileAtomic(path, content, options = {}) {
+    // Ends in `.tmp`, not `.json`, so directory sweeps that match `*.json` never see it.
+    const staged = `${path}.${randomUUID()}.tmp`;
+    try {
+        await _atomicWriteDeps.writeFile(staged, content, {
+            encoding: "utf8",
+            ...(options.mode !== undefined ? { mode: options.mode } : {}),
+        });
+        await _atomicWriteDeps.rename(staged, path);
+    }
+    catch (error) {
+        await _atomicWriteDeps.rm(staged, { force: true });
+        throw error;
+    }
+}

package/dist/internal/command-spec/index.js

@@ -22,7 +22,7 @@ export function commandSpecIncludes(spec, fragment) {
 }
 /** Apply a literal replacement to every command entry without changing its shape. */
 export function replaceInCommandSpec(spec, searchValue, replacement) {
-    const replace = (command) => command.replaceAll(searchValue, replacement);
+    const replace = (command) => command.replaceAll(searchValue, () => replacement);
     return typeof spec === "string" ? replace(spec) : spec.map(replace);
 }
 /**

package/dist/internal/git-env.d.ts

@@ -50,9 +50,10 @@ export declare function hardenedGitEnv(base: Readonly<Record<string, string | un
 export declare function gitSpawnEnv(overlay?: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
 export declare const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
 /**
- * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
- * right after a `status` / `diff` subcommand. Unlike the config key, the flag
- * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `argv` (argv[0] is the git program, or an interceptor token followed by it)
+ * with `--ignore-submodules=dirty` placed right after a `status` / `diff`
+ * subcommand. Unlike the config key, the flag overrides a
+ * `submodule.<name>.ignore` from `.gitmodules`. A later explicit
  * `--ignore-submodules` in `argv` still wins (git takes the last), which the
  * agent-facing git tool cannot supply: it refuses every `-`-leading element.
  */

package/dist/internal/git-env.js

@@ -73,16 +73,23 @@ const SUBMODULE_DIRTY_CHECK_VERBS = new Set(["status", "diff"]);
 /** Global options that consume the next argument (`-C <dir>`, `-c <k=v>`). */
 const GLOBAL_OPTIONS_WITH_VALUE = new Set(["-C", "-c"]);
 export const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
+/** `git` or a path ending in `/git`: the program, as opposed to a wrapper in front of it. */
+function isGitProgram(token) {
+    return token === "git" || (token?.endsWith("/git") ?? false);
+}
 /**
- * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
- * right after a `status` / `diff` subcommand. Unlike the config key, the flag
- * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `argv` (argv[0] is the git program, or an interceptor token followed by it)
+ * with `--ignore-submodules=dirty` placed right after a `status` / `diff`
+ * subcommand. Unlike the config key, the flag overrides a
+ * `submodule.<name>.ignore` from `.gitmodules`. A later explicit
  * `--ignore-submodules` in `argv` still wins (git takes the last), which the
  * agent-facing git tool cannot supply: it refuses every `-`-leading element.
  */
 export function hardenedGitArgv(argv) {
     const out = [...argv];
-    let i = 1;
+    // A command interceptor may add exactly ONE leading token (validateRewrite), so a
+    // rewritten argv is `<provider> git <verb> ...`: the walk starts after the git program.
+    let i = !isGitProgram(out[0]) && isGitProgram(out[1]) ? 2 : 1;
     while (i < out.length && out[i].startsWith("-")) {
         i += GLOBAL_OPTIONS_WITH_VALUE.has(out[i]) ? 2 : 1;
     }

package/dist/internal.d.ts

@@ -30,6 +30,7 @@ export * as infraModule from "#src/infra/index";
 export * from "#src/infra/spin-breaker/index";
 export * from "#src/internal/agent-output-env";
 export * from "#src/internal/argv-exec";
+export * from "#src/internal/atomic-write";
 export * from "#src/internal/command-spec/index";
 export * from "#src/internal/file-lock";
 export * from "#src/internal/git-add";
@@ -56,11 +57,14 @@ 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 { 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";
 export * from "#src/native/session/loop-events/types";
 export * from "#src/native/session/memory-transcript-store";
+export { _repositoryInstructionDeps } from "#src/native/session/repository-instructions";
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
@@ -80,11 +84,13 @@ export * from "#src/permissions/index";
 export * from "#src/sandbox/index";
 export * as policyInputsModule from "#src/sandbox/policy-inputs";
 export * from "#src/session/agent-session-deps";
+export * from "#src/terminal-auth/index";
 export * from "#src/tools/credential-read-deny";
 export * from "#src/tools/git";
 export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
+export { _instructionAccessDeps } from "#src/tools/instruction-access";
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";
 export * from "#src/tools/policy";

package/dist/internal.js

@@ -30,6 +30,7 @@ export * as infraModule from "#src/infra/index";
 export * from "#src/infra/spin-breaker/index";
 export * from "#src/internal/agent-output-env";
 export * from "#src/internal/argv-exec";
+export * from "#src/internal/atomic-write";
 export * from "#src/internal/command-spec/index";
 export * from "#src/internal/file-lock";
 export * from "#src/internal/git-add";
@@ -56,11 +57,14 @@ 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 { 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";
 export * from "#src/native/session/loop-events/types";
 export * from "#src/native/session/memory-transcript-store";
+export { _repositoryInstructionDeps } from "#src/native/session/repository-instructions";
 export * from "#src/native/session/session";
 export * as sessionModule from "#src/native/session/session";
 export * from "#src/native/session/tool-mapping";
@@ -80,11 +84,13 @@ export * from "#src/permissions/index";
 export * from "#src/sandbox/index";
 export * as policyInputsModule from "#src/sandbox/policy-inputs";
 export * from "#src/session/agent-session-deps";
+export * from "#src/terminal-auth/index";
 export * from "#src/tools/credential-read-deny";
 export * from "#src/tools/git";
 export * from "#src/tools/git-commit";
 export * from "#src/tools/grep";
 export * from "#src/tools/index";
+export { _instructionAccessDeps } from "#src/tools/instruction-access";
 // S3-2: the port (nax supplies the policy behind it from its own module).
 export * from "#src/tools/owned-paths";
 export * from "#src/tools/package-managers";

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;
+};