@nathapp/nax-agent 0.84.0 → 0.85.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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).

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
 
@@ -97,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

@@ -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.d.ts

@@ -57,6 +57,7 @@ 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";

package/dist/internal.js

@@ -57,6 +57,7 @@ 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";

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/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.0",
   "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.30.0",
+    "@nathapp/nax-ai": "0.85.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {