@nylorun/runtime 0.25.0-beta → 0.27.0-beta

package/dist/mcp/pool.d.ts

@@ -1,10 +1,6 @@
 import type { AgentManifest, McpServerManifest } from "@nylorun/core/define";
-import type { OutboundPolicy } from "../tenant/outbound.js";
-import type { AuthorizeResult } from "../vault/service.js";
-import { openMcpServer, type LiveConnection, type McpToolOutcome } from "./connect.js";
-import { type McpDiagnostic, type McpSnapshot, type McpToolRecord } from "./snapshot.js";
-/** A connection unused this long is closed by the sweep; the next call opens it again. */
-export declare const DEFAULT_MCP_IDLE_MS: number;
+import { type LiveConnection, type McpToolOutcome } from "./connect.js";
+import type { McpDiagnostic, McpSnapshot } from "./snapshot.js";
 export declare class McpPool {
     private readonly options;
     private readonly live;
@@ -12,40 +8,44 @@ export declare class McpPool {
     private readonly opening;
     private readonly idleMs;
     private readonly now;
-    private readonly open;
     constructor(options: {
-        readonly authorize: (sessionId: string, request: {
-            url: string;
-            serverName: string;
-            agentId?: string;
-        }) => Promise<AuthorizeResult>;
-        /** Default `DEFAULT_MCP_IDLE_MS`. */
+        /**
+         * A connection unused this long is closed by the sweep; the next call opens it again.
+         * Default `harness.mcpIdleMs` (Host tuning, 15 min).
+         */
         readonly idleMs?: number;
         readonly now?: () => number;
-        /** Tests replace how a declared server is opened. */
-        readonly open?: typeof openMcpServer;
-        /** How remote servers opened in this process are reached (`TenantConfig.delivery`). */
-        readonly policy?: OutboundPolicy;
         /**
-         * Opens a remote (`streamable-http` or `sse`) server somewhere else: the gates service
-         * holds the connection and its credential, and the loop never sees either (F4.1).
-         * Absent: they are opened in this process, with `authorize`.
+         * Opens a declared remote (`streamable-http` or `sse`) server through a Tool Gate
+         * (`ToolGate.openMcp`): the gate finds it in the session's pinned manifest and holds its
+         * credential, and the pool never sees either (F4.1, protocol 15).
          */
-        readonly openRemote?: (server: McpServerRef) => Promise<LiveConnection>;
+        readonly openRemote: (server: McpServerRef) => Promise<LiveConnection>;
     });
+    /**
+     * Opens each declared server of the session and lists its tools (protocol 15): the snapshot
+     * holds every server that connected, with its instructions and its tools as it named them.
+     * Instructions past `maxInstructionBytes` (the Runtime limit `recordEntryBytes`) are left out,
+     * and the server's diagnostic says so.
+     */
     discover(input: {
         sessionId: string;
         manifest: AgentManifest;
         manifestHash: string;
+        maxInstructionBytes: number;
         signal?: AbortSignal;
     }): Promise<{
         snapshot: McpSnapshot;
         diagnostics: McpDiagnostic[];
     }>;
+    /** Opens again each server of the snapshot this process holds no connection to. */
     reconnect(input: {
         sessionId: string;
         manifest: AgentManifest;
-        tools: readonly McpToolRecord[];
+        servers: readonly {
+            readonly agentId?: string;
+            readonly name: string;
+        }[];
         signal?: AbortSignal;
     }): Promise<McpDiagnostic[]>;
     call(input: {
@@ -59,6 +59,11 @@ export declare class McpPool {
         effectId?: string;
         /** The call's span context (R7.4), sent as `traceparent` on a connection this process holds. */
         traceparent?: string;
+        /**
+         * The largest answer kept on a connection this process holds: the Runtime limit
+         * `toolAnswerBytes` (`turn.start.limits`). The gates service reads its own.
+         */
+        maxResultBytes: number;
         signal?: AbortSignal;
     }): Promise<McpToolOutcome>;
     /** The session's connection to the server, opened when there is none, or why it cannot be. */

package/dist/mcp/pool.js

@@ -1,8 +1,6 @@
 import { delegatesOf } from "@nylorun/core/define";
-import { callMcpTool, diagnosticFromError, listMcpTools, McpConnectionStale, openMcpServer, unreachable, } from "./connect.js";
-import { declaredToolNames, } from "./snapshot.js";
-/** A connection unused this long is closed by the sweep; the next call opens it again. */
-export const DEFAULT_MCP_IDLE_MS = 15 * 60_000;
+import { callMcpTool, diagnosticFromError, listMcpTools, McpConnectionStale, unreachable, } from "./connect.js";
+import { hostTuning } from "../tuning.js";
 export class McpPool {
     options;
     live = new Map();
@@ -10,18 +8,19 @@ export class McpPool {
     opening = new Map();
     idleMs;
     now;
-    open;
     constructor(options) {
         this.options = options;
-        this.idleMs = options.idleMs ?? DEFAULT_MCP_IDLE_MS;
+        this.idleMs = options.idleMs ?? hostTuning().harness.mcpIdleMs;
         this.now = options.now ?? Date.now;
-        this.open = options.open ?? openMcpServer;
     }
+    /**
+     * Opens each declared server of the session and lists its tools (protocol 15): the snapshot
+     * holds every server that connected, with its instructions and its tools as it named them.
+     * Instructions past `maxInstructionBytes` (the Runtime limit `recordEntryBytes`) are left out,
+     * and the server's diagnostic says so.
+     */
     async discover(input) {
-        // Each agent names its own tools, so collisions are checked per agent.
-        const taken = new Map();
-        const tools = [];
-        const notes = [];
+        const servers = [];
         const diagnostics = [];
         for (const declared of serversOf(input.manifest)) {
             input.signal?.throwIfAborted();
@@ -31,20 +30,18 @@ export class McpPool {
                 continue;
             }
             try {
-                if (!taken.has(declared.agentId))
-                    taken.set(declared.agentId, declaredToolNames(declared.manifest));
                 const listed = await listMcpTools(opened.connection.client, {
                     serverName: declared.server.name,
-                    taken: taken.get(declared.agentId),
                     server: declared.server,
                     ...(input.signal ? { signal: input.signal } : {}),
                 });
-                tools.push(...listed.tools.map((tool) => owned(declared, tool)));
-                if (opened.connection.instructions)
-                    notes.push(owned(declared, {
-                        serverName: declared.server.name,
-                        instructions: opened.connection.instructions,
-                    }));
+                const text = opened.connection.instructions;
+                const tooLong = text !== undefined && Buffer.byteLength(text) > input.maxInstructionBytes;
+                servers.push(owned(declared, {
+                    name: declared.server.name,
+                    ...(text === undefined || tooLong ? {} : { instructions: text }),
+                    tools: listed.tools,
+                }));
                 diagnostics.push({
                     ...ownerOf(declared),
                     serverName: declared.server.name,
@@ -55,8 +52,12 @@ export class McpPool {
                         ...(listed.unknownTools.length === 0
                             ? []
                             : [`Its tools settings name tools it does not list: ${listed.unknownTools.join(", ")}`]),
+                        ...(tooLong
+                            ? [
+                                `Its instructions are ${Buffer.byteLength(text)} bytes, more than a record entry holds (the Runtime limit recordEntryBytes, ${input.maxInstructionBytes} bytes), and are left out`,
+                            ]
+                            : []),
                     ].join(". "),
-                    ...(listed.renamed.length === 0 ? {} : { renamed: listed.renamed }),
                     ...(listed.disabled === 0 ? {} : { disabled: listed.disabled }),
                     ...(listed.unknownTools.length === 0 ? {} : { unknownTools: listed.unknownTools }),
                 });
@@ -68,20 +69,16 @@ export class McpPool {
             }
         }
         return {
-            snapshot: {
-                snapshotSchemaVersion: 1,
-                manifestHash: input.manifestHash,
-                mcpTools: tools,
-                ...(notes.length === 0 ? {} : { servers: notes }),
-            },
+            snapshot: { snapshotSchemaVersion: 2, manifestHash: input.manifestHash, servers },
             diagnostics,
         };
     }
+    /** Opens again each server of the snapshot this process holds no connection to. */
     async reconnect(input) {
         const diagnostics = [];
         const seen = new Set();
-        for (const tool of input.tools) {
-            const key = this.liveKey(input.sessionId, tool.agentId, tool.serverName);
+        for (const server of input.servers) {
+            const key = this.liveKey(input.sessionId, server.agentId, server.name);
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -92,11 +89,11 @@ export class McpPool {
                 continue;
             }
             input.signal?.throwIfAborted();
-            const declared = findServer(input.manifest, tool.agentId, tool.serverName);
+            const declared = findServer(input.manifest, server.agentId, server.name);
             if (!declared) {
                 diagnostics.push({
-                    ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
-                    serverName: tool.serverName,
+                    ...(server.agentId === undefined ? {} : { agentId: server.agentId }),
+                    serverName: server.name,
                     outcome: "failed",
                     message: "Declared MCP server is missing from the pinned manifest",
                 });
@@ -124,6 +121,7 @@ export class McpPool {
                     ...(input.effectId === undefined ? {} : { key: input.effectId }),
                     ...(input.signal ? { signal: input.signal } : {}),
                     ...(input.traceparent === undefined ? {} : { traceparent: input.traceparent }),
+                    maxResultBytes: input.maxResultBytes,
                 });
             }
             catch (error) {
@@ -213,22 +211,10 @@ export class McpPool {
     }
     async connectDeclared(input, declared) {
         try {
-            if (this.options.openRemote) {
-                const connection = await this.options.openRemote({
-                    sessionId: input.sessionId,
-                    ...ownerOf(declared),
-                    serverName: declared.server.name,
-                });
-                return { ok: true, connection };
-            }
-            const connection = await this.open({
-                server: declared.server,
-                ...(this.options.policy ? { policy: this.options.policy } : {}),
-                authorize: (url) => this.options.authorize(input.sessionId, {
-                    url,
-                    serverName: declared.server.name,
-                    ...ownerOf(declared),
-                }),
+            const connection = await this.options.openRemote({
+                sessionId: input.sessionId,
+                ...ownerOf(declared),
+                serverName: declared.server.name,
             });
             return { ok: true, connection };
         }

package/dist/mcp/preview.d.ts

@@ -1,6 +1,6 @@
 /**
  * A remote MCP server's tools before an agent names it (R2b C12, `POST /v1/tenant/mcp/preview`,
- * `nylorun mcp inspect`, an Environment's Secrets tab in Studio). It runs where plaintext credentials live:
+ * `nylorun tenant mcp inspect`, an Environment's Secrets tab in Studio). It runs where plaintext credentials live:
  * the keys service (`keys/keys.ts`, `previewMcp`), in the gateway or in process.
  *
  * One connection: `initialize` and `tools/list` with the Environment's credential for the
@@ -8,19 +8,26 @@
  * It never calls a tool, and sends no identity header: no person asked. A server that answers
  * `401` is `authRequired`, with its RFC 9728 protected-resource metadata when it publishes any,
  * read under the same policy. No credential value sent is in the answer (`scrubValues`, C8).
+ *
+ * Each tool's `modelName` is the name Nylorun's engine would give it (`mcpToolNames` of
+ * `@nylorun/harness`, protocol 15): the Runtime itself names no tool, and a harness of your own
+ * names them its way.
  */
-import { type McpPreview, type McpPreviewRequest } from "@nylorun/core/contracts";
+import { type McpPreview, type McpPreviewRequest, type RuntimeLimits } from "@nylorun/core/contracts";
 import { type OutboundPolicy } from "../tenant/outbound.js";
 import type { VaultService } from "../vault/service.js";
 import { openMcpServer } from "./connect.js";
-/** How long a preview may take, `initialize` and every `tools/list` page together. */
-export declare const MCP_PREVIEW_TIMEOUT_MS = 15000;
 export interface McpPreviewOptions {
     readonly vault: Pick<VaultService, "authorize" | "listEnvironmentSecrets">;
     /** The Host's address policy for developer URLs (`TenantConfig.delivery`). */
     readonly policy: OutboundPolicy;
-    /** Default `MCP_PREVIEW_TIMEOUT_MS`. */
-    readonly timeoutMs?: number;
+    /**
+     * The Tenant's Runtime limits a preview keeps to: `mcpPreviewMs` (how long it may take,
+     * `initialize` and every `tools/list` page together), `mcpMetadataBytes` (the largest
+     * protected-resource metadata document read) and `errorExcerptChars` (how much of a failure
+     * its message quotes).
+     */
+    readonly limits: Pick<RuntimeLimits, "mcpPreviewMs" | "mcpMetadataBytes" | "errorExcerptChars">;
     /** Tests replace how the server is opened. */
     readonly open?: typeof openMcpServer;
 }

package/dist/mcp/preview.js

@@ -1,6 +1,6 @@
 /**
  * A remote MCP server's tools before an agent names it (R2b C12, `POST /v1/tenant/mcp/preview`,
- * `nylorun mcp inspect`, an Environment's Secrets tab in Studio). It runs where plaintext credentials live:
+ * `nylorun tenant mcp inspect`, an Environment's Secrets tab in Studio). It runs where plaintext credentials live:
  * the keys service (`keys/keys.ts`, `previewMcp`), in the gateway or in process.
  *
  * One connection: `initialize` and `tools/list` with the Environment's credential for the
@@ -8,18 +8,21 @@
  * It never calls a tool, and sends no identity header: no person asked. A server that answers
  * `401` is `authRequired`, with its RFC 9728 protected-resource metadata when it publishes any,
  * read under the same policy. No credential value sent is in the answer (`scrubValues`, C8).
+ *
+ * Each tool's `modelName` is the name Nylorun's engine would give it (`mcpToolNames` of
+ * `@nylorun/harness`, protocol 15): the Runtime itself names no tool, and a harness of your own
+ * names them its way.
  */
 import { McpPreviewRequestSchema, } from "@nylorun/core/contracts";
+import { schemaFromJSON } from "@nylorun/core/define";
+import { mcpToolNames } from "@nylorun/harness";
 import { scrubValues } from "../redact.js";
 import { HttpError } from "../tenant/http.js";
 import { guardedFetch, OutboundRefused } from "../tenant/outbound.js";
 import { VaultError } from "../vault/error.js";
 import { credentialSecrets } from "../vault/headers.js";
 import { CredentialRejected, listMcpTools, McpCallFailed, openMcpServer, } from "./connect.js";
-/** How long a preview may take, `initialize` and every `tools/list` page together. */
-export const MCP_PREVIEW_TIMEOUT_MS = 15_000;
-/** The largest protected-resource metadata document read. */
-const RESOURCE_METADATA_MAX_BYTES = 64 * 1024;
+import { MODEL_TOOL_NAME_MAX } from "@nylorun/core/define";
 /** Host labels that name a service's role rather than the service. */
 const GENERIC_LABELS = new Set(["mcp", "www", "api"]);
 /**
@@ -39,7 +42,7 @@ export function previewServerName(url) {
             named.shift();
         name = named.at(-1);
     }
-    return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "server";
+    return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MODEL_TOOL_NAME_MAX) || "server";
 }
 /** Lists the server's tools as an agent's session would see them; never calls one. */
 export async function previewMcpServer(body, options) {
@@ -51,7 +54,8 @@ export async function previewMcpServer(body, options) {
     const secrets = authorized.status === "authorized" ? credentialSecrets(authorized.headers) : [];
     const credentialSent = authorized.status === "authorized";
     const base = { name, url: request.url, type, credentialSent };
-    const signal = AbortSignal.timeout(options.timeoutMs ?? MCP_PREVIEW_TIMEOUT_MS);
+    const { limits } = options;
+    const signal = AbortSignal.timeout(limits.mcpPreviewMs);
     const open = options.open ?? openMcpServer;
     let connection;
     try {
@@ -60,6 +64,7 @@ export async function previewMcpServer(body, options) {
             // Read once: one audit row, and the same credential for every request.
             authorize: async () => authorized,
             policy: options.policy,
+            errorExcerptChars: limits.errorExcerptChars,
             signal,
         });
         const pages = [];
@@ -71,12 +76,10 @@ export async function previewMcpServer(body, options) {
             },
             callTool: () => Promise.reject(new Error("A preview never calls a tool")),
         };
-        const listed = await listMcpTools(listing, {
-            serverName: name,
-            taken: new Set(),
-            signal,
-        });
-        const modelNames = new Map(listed.tools.map((tool) => [tool.serverToolName, tool.name]));
+        const listed = await listMcpTools(listing, { serverName: name, signal });
+        // The names Nylorun's engine gives the tools whose schemas it can use.
+        const named = mcpToolNames(name, listed.tools.filter((tool) => compiles(tool.inputSchema)).map((tool) => tool.name), new Set());
+        const modelNames = named.names;
         const tools = pages
             .flatMap((page) => page.tools)
             .filter((tool) => typeof tool.name === "string" && tool.name.length > 0)
@@ -99,7 +102,7 @@ export async function previewMcpServer(body, options) {
             ...(connection.serverInfo === undefined ? {} : { serverInfo: { ...connection.serverInfo } }),
             ...(connection.instructions === undefined ? {} : { instructions: connection.instructions }),
             tools,
-            renamed: listed.renamed.map(({ serverToolName, name: renamedTo }) => ({
+            renamed: named.renamed.map(({ serverToolName, name: renamedTo }) => ({
                 serverToolName,
                 name: renamedTo,
             })),
@@ -108,10 +111,10 @@ export async function previewMcpServer(body, options) {
     }
     catch (error) {
         if (error instanceof CredentialRejected) {
-            const authRequired = await protectedResource(request.url, error.challenge, options.policy, signal);
+            const authRequired = await protectedResource(request.url, error.challenge, options.policy, signal, limits);
             return scrubValues({ ...base, tools: [], renamed: [], authRequired }, secrets).value;
         }
-        throw failed(name, error, signal, secrets, options.timeoutMs ?? MCP_PREVIEW_TIMEOUT_MS);
+        throw failed(name, error, signal, secrets, limits);
     }
     finally {
         await connection?.close().catch(() => undefined);
@@ -132,7 +135,8 @@ async function credentialFor(vault, request) {
     throw new HttpError(409, `Environment ${request.environmentId}'s credential for this URL cannot be used (${result.reason})`, { code: "request_rejected", details: { reason: result.reason, credentialIds: result.credentialIds } });
 }
 /** A preview that listed nothing: `mcp_preview_failed`, with the code a tool call would have had. */
-function failed(server, error, signal, secrets, timeoutMs) {
+function failed(server, error, signal, secrets, limits) {
+    const timeoutMs = limits.mcpPreviewMs;
     if (error instanceof HttpError || error instanceof VaultError)
         return error;
     const failure = signal.aborted
@@ -145,7 +149,7 @@ function failed(server, error, signal, secrets, timeoutMs) {
                     ? `The MCP server '${server}' was not called: ${refusedBy(error).message}`
                     : `The MCP server '${server}' could not be listed: ${error instanceof Error ? error.message : String(error)}`,
             };
-    const message = scrubValues(failure.message.slice(0, 2_000), secrets).value;
+    const message = scrubValues(failure.message.slice(0, limits.errorExcerptChars), secrets).value;
     return new HttpError(502, message, { code: "mcp_preview_failed", details: { failure: failure.code } });
 }
 /** The Host's refusal of the address, when that is why the server was not reached. */
@@ -159,7 +163,7 @@ function refusedBy(error) {
  * `resource_metadata`, else the one at the URL's well-known path (with the URL's path, then at
  * the origin). Absent fields when the server publishes none.
  */
-async function protectedResource(url, challenge, policy, signal) {
+async function protectedResource(url, challenge, policy, signal, limits) {
     const named = challenge === undefined ? undefined : resourceMetadataParam(challenge);
     const target = new URL(url);
     const wellKnown = "/.well-known/oauth-protected-resource";
@@ -167,7 +171,10 @@ async function protectedResource(url, challenge, policy, signal) {
     const candidates = named
         ? [named]
         : [...(path ? [`${target.origin}${wellKnown}${path}`] : []), `${target.origin}${wellKnown}`];
-    const fetchMetadata = guardedFetch(policy, { maxResponseBytes: RESOURCE_METADATA_MAX_BYTES });
+    const fetchMetadata = guardedFetch(policy, {
+        maxResponseBytes: limits.mcpMetadataBytes,
+        timeoutMs: limits.mcpPreviewMs,
+    });
     for (const candidate of candidates) {
         let resolved;
         try {
@@ -199,6 +206,16 @@ function resourceMetadataParam(challenge) {
     const value = match?.[1] ?? match?.[2];
     return value ? value : undefined;
 }
+/** True when Nylorun's engine can check calls against `schema`. */
+function compiles(schema) {
+    try {
+        schemaFromJSON(schema);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }

package/dist/mcp/snapshot.d.ts

@@ -1,38 +1,15 @@
+/**
+ * A session's MCP snapshot (protocol 15): what its remote MCP servers listed at discovery, raw
+ * (`McpSnapshot`, `@nylorun/core/harness-api`), pinned on the session. The Runtime never names a
+ * tool for the model: it states facts per turn (`mcpFactsOf`, `turn.start.mcp`), and checks a
+ * call by its identity (`{server, tool}` of its agent): discovered (`mcpToolIn`) and left enabled
+ * by the turn's manifest (`isEnabledIn`, R2b C9).
+ */
 import type { EventPayload } from "@nylorun/core/contracts";
-import type { JsonObject } from "@nylorun/core/define";
 import { type AgentManifest, type ResolvedMcpToolSettings } from "@nylorun/core/define";
-import type { DurableSessionTool, HostEffect } from "@nylorun/harness/run";
-export interface McpToolRecord {
-    /** The agent used as a tool that declares the server; absent for the session's root agent. */
-    readonly agentId?: string;
-    readonly serverName: string;
-    /** The tool's name on its server, which the call sends. */
-    readonly serverToolName: string;
-    /** The name the model knows it by (`normalizeToolName`). */
-    readonly name: string;
-    readonly description?: string;
-    readonly inputSchema: JsonObject;
-    readonly outputSchema?: JsonObject;
-    /**
-     * Out of the model's tool list for the session's life (R2b C10): core decides it once, when it
-     * records the snapshot (`pinDeferral`), so every model call of the session lists the same tools.
-     */
-    readonly deferred?: true;
-}
-/** A server's own instructions (MCP `initialize`), for the note on its deferred tools (R2b C10). */
-export interface McpServerNote {
-    readonly agentId?: string;
-    readonly serverName: string;
-    /** Cut to `SERVER_INSTRUCTIONS_MAX_CHARS`. */
-    readonly instructions: string;
-}
-export interface McpSnapshot {
-    readonly snapshotSchemaVersion: 1;
-    readonly manifestHash: string;
-    readonly mcpTools: readonly McpToolRecord[];
-    /** The servers that gave instructions; absent when none did. */
-    readonly servers?: readonly McpServerNote[];
-}
+import type { McpFacts, McpSnapshot, McpToolRecord } from "@nylorun/core/harness-api";
+import type { HostEffect } from "@nylorun/harness/run";
+export type { McpFacts, McpServerRecord, McpSnapshot, McpToolRecord } from "@nylorun/core/harness-api";
 export interface McpDiagnostic {
     /** The agent used as a tool that declares the server; absent for the session's root agent. */
     readonly agentId?: string;
@@ -40,69 +17,41 @@ export interface McpDiagnostic {
     readonly outcome: "connected" | "refused" | "failed";
     readonly message: string;
     readonly credentialIds?: readonly string[];
-    /** Tools the model knows by another name than `server__tool` (R2b C6). */
-    readonly renamed?: readonly McpRenamedTool[];
     /** How many listed tools the server's `tools` settings disable (R2b C9). */
     readonly disabled?: number;
     /** Keys of the server's `tools` settings that name no tool it listed (R2b C9). */
     readonly unknownTools?: readonly string[];
 }
-/** A tool whose model-facing name is not `server__tool` (`normalizeToolName`). */
-export interface McpRenamedTool {
-    readonly serverToolName: string;
-    readonly name: string;
-}
 /**
- * The `mcp.discovered` payload: each server's outcome, with the tools it added to the snapshot,
- * and the Agent Plugin that brought the server (from `manifest`, the session's pinned one).
+ * The `mcp.discovered` payload: each server's outcome, with the tools it added to the snapshot
+ * that its settings in `manifest` (the session's pinned one) leave enabled, and the Agent Plugin
+ * that brought the server.
  */
 export declare function mcpDiscovered(snapshot: McpSnapshot, diagnostics: readonly McpDiagnostic[], manifest?: AgentManifest): EventPayload<"mcp.discovered">;
-/** The longest tool name every model provider accepts (R2b C6, Q14). */
-export declare const MODEL_TOOL_NAME_MAX = 64;
-/**
- * The name the model knows an MCP tool by (R2b C6, Q13): `server__tool`, with each character
- * outside `[A-Za-z0-9_-]` replaced by `_`, since MCP allows `.` and 128 characters and OpenAI,
- * Bedrock and Gemini on Vertex do not. A name over 64 characters, or one that collides
- * (`suffixed`), keeps 55 and adds `_` and 8 hex characters of the SHA-256 of the raw
- * `server/tool`.
- */
-export declare function normalizeToolName(serverName: string, serverToolName: string, options?: {
-    readonly suffixed?: boolean;
-}): string;
-/** The names of the agent's tools: its own and those the Runtime pinned. */
-export declare function declaredToolNames(manifest: AgentManifest): Set<string>;
+/** The tool `tool` of server `server` of agent `agentId` (the root when absent), as discovered. */
+export declare function mcpToolIn(snapshot: McpSnapshot | undefined, agentId: string | undefined, server: string, tool: string): McpToolRecord | undefined;
 /** The tool's settings in `manifest` (R2b C9); the defaults when its server is not there. */
-export declare function mcpToolSettingsIn(manifest: AgentManifest, tool: McpToolRecord): ResolvedMcpToolSettings;
-/**
- * The tools of a snapshot, as the engine gets them for a turn whose manifest is `manifest` (the
- * session's pin, or a turn variant that tightened its MCP servers' tools):
- *
- * - a tool its settings disable is left out (R2b C9); the Tool Gate holds a call its approval
- *   or the Tenant's tool policy asks a person about (R5 step 2);
- * - a deferred tool (R2b C10) is marked so, out of the model's list, and its agent gets the
- *   session tools `tool_search`, with the note on the servers it holds deferred tools of, and
- *   `tool_call`. Their names are reserved: no tool of the agent's own takes them.
- *
- * Nothing here changes between the steps of a turn, so neither does the model's tool list.
- */
-export declare function sessionToolsOf(snapshot: McpSnapshot | undefined, manifest: AgentManifest): readonly DurableSessionTool[] | undefined;
-/** The share of the model's context window past which an agent's MCP tools are deferred (Q21). */
-export declare const DEFER_CONTEXT_SHARE = 0.1;
-/** Characters per token, to estimate what tool definitions take of a context window (Q21). */
-export declare const CHARS_PER_TOKEN = 4;
-/**
- * The snapshot with its deferred tools marked (R2b C10, Q21), decided once for the session when
- * core records it. A tool's own setting, then `"*"`'s, then its server's, decides; a tool none
- * sets is deferred when the JSON of its agent's MCP tools that would be listed passes a tenth of
- * the model's context window (`contextWindow` tokens, at 4 characters a token).
- */
-export declare function pinDeferral(snapshot: McpSnapshot, manifest: AgentManifest, contextWindow: number): McpSnapshot;
+export declare function mcpToolSettingsIn(manifest: AgentManifest, agentId: string | undefined, server: string, tool: string): ResolvedMcpToolSettings;
+/** True when the tool's settings in `manifest` leave it enabled (R2b C9). */
+export declare function isEnabledIn(manifest: AgentManifest, agentId: string | undefined, server: string, tool: string): boolean;
 /**
- * The snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. With
- * the turn's `manifest`, a tool its settings disable is not one either (R2b C9).
+ * The snapshot's facts for a turn whose manifest is `manifest` (the session's pin, or a turn
+ * variant that tightened its MCP servers' tools): each tool with whether its settings leave it
+ * `enabled` and, when they say, whether to defer it. A server the turn's manifest no longer
+ * declares is left out.
  */
-export declare function mcpToolOf(snapshot: McpSnapshot | undefined, request: Pick<HostEffect, "agent" | "toolName">, manifest?: AgentManifest): McpToolRecord | undefined;
-/** True when the tool's settings in `manifest` leave it enabled (R2b C9). */
-export declare function isEnabledIn(manifest: AgentManifest, tool: McpToolRecord): boolean;
+export declare function mcpFactsOf(snapshot: McpSnapshot, manifest: AgentManifest): McpFacts;
 /** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
 export declare function manifestFor(manifest: AgentManifest, agent: HostEffect["agent"]): AgentManifest | undefined;
+/**
+ * `snapshot` within the Tenant's Runtime limit `mcpSnapshotBytes` (its JSON, which every
+ * `turn.start.mcp` carries): its servers in order while they fit. A server that does not is left
+ * out, so the session never offers its tools, and its diagnostic says so (`failed`, replacing
+ * the one it had). Unchanged when the whole snapshot fits.
+ */
+export declare function fitSnapshot(snapshot: McpSnapshot, diagnostics: readonly McpDiagnostic[], limitBytes: number): {
+    snapshot: McpSnapshot;
+    diagnostics: McpDiagnostic[];
+};
+/** True for a snapshot of the shape this Runtime pins (`snapshotSchemaVersion` 2). */
+export declare function isSnapshot(value: unknown): value is McpSnapshot;