@nylorun/runtime 0.20.0-beta → 0.21.1-beta

package/dist/mcp/pool.d.ts

@@ -1,7 +1,7 @@
 import type { AgentManifest, McpServerManifest } from "@nylorun/core/define";
 import type { OutboundPolicy } from "../tenant/outbound.js";
 import type { AuthorizeResult } from "../vault/service.js";
-import { callMcpTool, openMcpServer, type LiveConnection } from "./connect.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;
@@ -58,8 +58,17 @@ export declare class McpPool {
         manifest: AgentManifest;
         /** The effect id: a gate runs the call once under it (F4.1). */
         effectId?: string;
+        /** The tool is read-only or idempotent: a lost answer is the model's to retry (R2b C7). */
+        retrySafe?: boolean;
         signal?: AbortSignal;
-    }): Promise<Awaited<ReturnType<typeof callMcpTool>>>;
+    }): Promise<McpToolOutcome>;
+    /** The session's connection to the server, opened when there is none, or why it cannot be. */
+    private liveFor;
+    /**
+     * Takes a connection out of the pool, so the next call opens a new one. Calls still running on
+     * it finish first: the last one closes it.
+     */
+    private evict;
     /**
      * Closes connections unused for the idle timeout (the Tenant sweep). A session that calls
      * one again reconnects, as after a restart; this bounds the connections a Tenant keeps.

package/dist/mcp/pool.js

@@ -1,5 +1,5 @@
 import { delegatesOf } from "@nylorun/core/define";
-import { callMcpTool, diagnosticFromError, listMcpTools, openMcpServer, } from "./connect.js";
+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;
@@ -21,6 +21,7 @@ export class McpPool {
         // Each agent names its own tools, so collisions are checked per agent.
         const taken = new Map();
         const tools = [];
+        const notes = [];
         const diagnostics = [];
         for (const declared of serversOf(input.manifest)) {
             input.signal?.throwIfAborted();
@@ -36,17 +37,31 @@ export class McpPool {
                     capabilityId: declared.capabilityId,
                     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, {
+                        capabilityId: declared.capabilityId,
+                        serverName: declared.server.name,
+                        instructions: opened.connection.instructions,
+                    }));
                 diagnostics.push({
                     ...ownerOf(declared),
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
                     outcome: "connected",
-                    message: listed.omitted.length === 0
-                        ? "Connected"
-                        : `Connected. Omitted ${listed.omitted.join(", ")}`,
+                    message: [
+                        "Connected",
+                        ...(listed.omitted.length === 0 ? [] : [`Omitted ${listed.omitted.join(", ")}`]),
+                        ...(listed.unknownTools.length === 0
+                            ? []
+                            : [`Its tools settings name tools it does not list: ${listed.unknownTools.join(", ")}`]),
+                    ].join(". "),
+                    ...(listed.renamed.length === 0 ? {} : { renamed: listed.renamed }),
+                    ...(listed.disabled === 0 ? {} : { disabled: listed.disabled }),
+                    ...(listed.unknownTools.length === 0 ? {} : { unknownTools: listed.unknownTools }),
                 });
                 this.remember(input.sessionId, declared, opened.connection);
             }
@@ -60,6 +75,7 @@ export class McpPool {
                 snapshotSchemaVersion: 1,
                 manifestHash: input.manifestHash,
                 mcpTools: tools,
+                ...(notes.length === 0 ? {} : { servers: notes }),
             },
             diagnostics,
         };
@@ -101,32 +117,62 @@ export class McpPool {
     }
     async call(input) {
         const key = this.liveKey(input.sessionId, input.agentId, input.capabilityId, input.serverName);
-        let live = this.live.get(key);
-        if (!live) {
-            const declared = findServer(input.manifest, input.agentId, input.capabilityId, input.serverName);
-            if (!declared)
-                throw new Error(`MCP server '${input.serverName}' is not declared`);
-            let opening = this.opening.get(key);
-            if (!opening) {
-                opening = this.connectDeclared(input, declared).finally(() => this.opening.delete(key));
-                this.opening.set(key, opening);
+        for (let attempt = 0;; attempt += 1) {
+            const live = await this.liveFor(input, key);
+            // No connection, so no call was sent: the model sees why, a 401 included (R2b C1, C7).
+            if (!("connection" in live))
+                return live;
+            live.active += 1;
+            try {
+                return await callMcpTool(live.connection.client, input.serverToolName, input.args, {
+                    ...(input.effectId === undefined ? {} : { key: input.effectId }),
+                    ...(input.retrySafe ? { retrySafe: true } : {}),
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof McpConnectionStale))
+                    throw error;
+                // The server ended the connection's session, or its credential now sends it elsewhere,
+                // and the tool never saw the call: drop the connection and send it once more on a new one.
+                this.evict(key, live);
+                if (attempt > 0)
+                    return error.outcome();
+            }
+            finally {
+                live.active -= 1;
+                live.lastUsedAt = this.now();
+                if (live.evicted && live.active === 0)
+                    void live.connection.close().catch(() => { });
             }
-            const opened = await opening;
-            if (!opened.ok)
-                throw new Error(opened.diagnostic.message);
-            live = this.remember(input.sessionId, declared, opened.connection);
-        }
-        live.active += 1;
-        try {
-            return await callMcpTool(live.connection.client, input.serverToolName, input.args, {
-                ...(input.effectId === undefined ? {} : { key: input.effectId }),
-                ...(input.signal ? { signal: input.signal } : {}),
-            });
         }
-        finally {
-            live.active -= 1;
-            live.lastUsedAt = this.now();
+    }
+    /** The session's connection to the server, opened when there is none, or why it cannot be. */
+    async liveFor(input, key) {
+        const live = this.live.get(key);
+        if (live)
+            return live;
+        const declared = findServer(input.manifest, input.agentId, input.capabilityId, input.serverName);
+        if (!declared)
+            throw new Error(`MCP server '${input.serverName}' is not declared`);
+        let opening = this.opening.get(key);
+        if (!opening) {
+            opening = this.connectDeclared(input, declared).finally(() => this.opening.delete(key));
+            this.opening.set(key, opening);
         }
+        const opened = await opening;
+        if (!opened.ok)
+            return unreachable(input.serverName, opened.error).outcome();
+        return this.remember(input.sessionId, declared, opened.connection);
+    }
+    /**
+     * Takes a connection out of the pool, so the next call opens a new one. Calls still running on
+     * it finish first: the last one closes it.
+     */
+    evict(key, live) {
+        if (this.live.get(key) === live)
+            this.live.delete(key);
+        live.evicted = true;
     }
     /**
      * Closes connections unused for the idle timeout (the Tenant sweep). A session that calls
@@ -195,6 +241,7 @@ export class McpPool {
         catch (error) {
             return {
                 ok: false,
+                error,
                 diagnostic: owned(declared, diagnosticFromError(declared.capabilityId, declared.server.name, error)),
             };
         }

package/dist/mcp/preview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A remote MCP server's tools before an agent names it (R2b C12, `POST /v1/tenant/mcp/preview`,
+ * `nylorun mcp inspect`, Studio's Credentials page). 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 installation vault's credential for the
+ * URL (its headers, and its `via`), under the Host's address policy, within 15 s; then it closes.
+ * 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).
+ */
+import { type McpPreview, type McpPreviewRequest } 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" | "getVault" | "listVaults">;
+    /** The Host's address policy for developer URLs (`TenantConfig.delivery`). */
+    readonly policy: OutboundPolicy;
+    /** Default `MCP_PREVIEW_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /** Tests replace how the server is opened. */
+    readonly open?: typeof openMcpServer;
+}
+/**
+ * The server name a preview makes model names with when the request gives none: the URL host's
+ * name before its top-level domain, without a leading `mcp`, `www` or `api` (`linear` for
+ * `mcp.linear.app`); an IP address or a one-label host whole. Characters outside
+ * `[A-Za-z0-9_-]` become `_`.
+ */
+export declare function previewServerName(url: string): string;
+/** Lists the server's tools as an agent's session would see them; never calls one. */
+export declare function previewMcpServer(body: McpPreviewRequest, options: McpPreviewOptions): Promise<McpPreview>;

package/dist/mcp/preview.js

@@ -0,0 +1,215 @@
+/**
+ * A remote MCP server's tools before an agent names it (R2b C12, `POST /v1/tenant/mcp/preview`,
+ * `nylorun mcp inspect`, Studio's Credentials page). 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 installation vault's credential for the
+ * URL (its headers, and its `via`), under the Host's address policy, within 15 s; then it closes.
+ * 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).
+ */
+import { INSTALLATION_OWNER, McpPreviewRequestSchema, } from "@nylorun/core/contracts";
+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;
+/** Host labels that name a service's role rather than the service. */
+const GENERIC_LABELS = new Set(["mcp", "www", "api"]);
+/**
+ * The server name a preview makes model names with when the request gives none: the URL host's
+ * name before its top-level domain, without a leading `mcp`, `www` or `api` (`linear` for
+ * `mcp.linear.app`); an IP address or a one-label host whole. Characters outside
+ * `[A-Za-z0-9_-]` become `_`.
+ */
+export function previewServerName(url) {
+    const host = new URL(url).hostname.replace(/^\[|\]$/g, "");
+    const labels = host.split(".").filter(Boolean);
+    const ip = /^[\d.]+$/.test(host) || host.includes(":");
+    let name = host;
+    if (!ip && labels.length > 1) {
+        const named = labels.slice(0, -1);
+        while (named.length > 1 && GENERIC_LABELS.has(named[0].toLowerCase()))
+            named.shift();
+        name = named.at(-1);
+    }
+    return name.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "server";
+}
+/** Lists the server's tools as an agent's session would see them; never calls one. */
+export async function previewMcpServer(body, options) {
+    const request = McpPreviewRequestSchema.parse(body);
+    const type = request.type ?? "streamable-http";
+    const name = request.name ?? previewServerName(request.url);
+    const server = { name, type, url: request.url };
+    const authorized = await credentialFor(options.vault, request);
+    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 open = options.open ?? openMcpServer;
+    let connection;
+    try {
+        connection = await open({
+            server,
+            // Read once: one audit row, and the same credential for every request.
+            authorize: async () => authorized,
+            policy: options.policy,
+            signal,
+        });
+        const pages = [];
+        const listing = {
+            listTools: async (params, requestOptions) => {
+                const page = await connection.client.listTools(params, requestOptions);
+                pages.push(page);
+                return page;
+            },
+            callTool: () => Promise.reject(new Error("A preview never calls a tool")),
+        };
+        const listed = await listMcpTools(listing, {
+            capabilityId: "preview",
+            serverName: name,
+            taken: new Set(),
+            signal,
+        });
+        const modelNames = new Map(listed.tools.map((tool) => [tool.serverToolName, tool.name]));
+        const tools = pages
+            .flatMap((page) => page.tools)
+            .filter((tool) => typeof tool.name === "string" && tool.name.length > 0)
+            .map((tool) => {
+            const modelName = modelNames.get(tool.name);
+            return {
+                serverToolName: tool.name,
+                ...(modelName === undefined ? {} : { modelName }),
+                ...(typeof tool.description === "string" && tool.description.length > 0
+                    ? { description: tool.description }
+                    : {}),
+                ...(isRecord(tool.annotations) && Object.keys(tool.annotations).length > 0
+                    ? { annotations: { ...tool.annotations } }
+                    : {}),
+                schemaBytes: Buffer.byteLength(JSON.stringify(tool.inputSchema ?? {})),
+            };
+        });
+        const preview = {
+            ...base,
+            ...(connection.serverInfo === undefined ? {} : { serverInfo: { ...connection.serverInfo } }),
+            ...(connection.instructions === undefined ? {} : { instructions: connection.instructions }),
+            tools,
+            renamed: listed.renamed.map(({ serverToolName, name: renamedTo }) => ({
+                serverToolName,
+                name: renamedTo,
+            })),
+        };
+        return scrubValues(preview, secrets).value;
+    }
+    catch (error) {
+        if (error instanceof CredentialRejected) {
+            const authRequired = await protectedResource(request.url, error.challenge, options.policy, signal);
+            return scrubValues({ ...base, tools: [], renamed: [], authRequired }, secrets).value;
+        }
+        throw failed(name, error, signal, secrets, options.timeoutMs ?? MCP_PREVIEW_TIMEOUT_MS);
+    }
+    finally {
+        await connection?.close().catch(() => undefined);
+    }
+}
+/**
+ * The installation vault credential for the URL: from `vaultId`, else from every installation
+ * vault. None is a preview without one; two or more without `vaultId` is a refusal that names
+ * them.
+ */
+async function credentialFor(vault, request) {
+    let vaultIds;
+    if (request.vaultId !== undefined) {
+        const found = await vault.getVault(request.vaultId);
+        if (found.ownerUserId !== INSTALLATION_OWNER)
+            throw new VaultError(400, "A preview uses an installation vault's credential: no person asked for it");
+        vaultIds = [found.id];
+    }
+    else
+        vaultIds = (await vault.listVaults(undefined, { installation: true })).map((found) => found.id);
+    if (vaultIds.length === 0)
+        return { status: "unauthenticated", url: request.url, headers: {} };
+    const result = await vault.authorize({ vaultIds, credentialSelections: [], url: request.url });
+    if (result.status !== "refused")
+        return result;
+    throw new HttpError(409, result.reason === "ambiguous"
+        ? "Several installation vaults hold a credential for this URL: name one with vaultId"
+        : `The installation vault'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) {
+    if (error instanceof HttpError || error instanceof VaultError)
+        return error;
+    const failure = signal.aborted
+        ? { code: "mcp.unreachable", message: `The MCP server '${server}' did not answer within ${timeoutMs / 1000} s` }
+        : error instanceof McpCallFailed
+            ? { code: error.code, message: error.message }
+            : {
+                code: "mcp.unreachable",
+                message: refusedBy(error) !== undefined
+                    ? `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;
+    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. */
+function refusedBy(error) {
+    if (error instanceof OutboundRefused)
+        return error;
+    return error instanceof Error && error.cause instanceof OutboundRefused ? error.cause : undefined;
+}
+/**
+ * What a `401` says about signing in (RFC 9728): the metadata its `WWW-Authenticate` names in
+ * `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) {
+    const named = challenge === undefined ? undefined : resourceMetadataParam(challenge);
+    const target = new URL(url);
+    const wellKnown = "/.well-known/oauth-protected-resource";
+    const path = target.pathname.replace(/\/$/, "");
+    const candidates = named
+        ? [named]
+        : [...(path ? [`${target.origin}${wellKnown}${path}`] : []), `${target.origin}${wellKnown}`];
+    const fetchMetadata = guardedFetch(policy, { maxResponseBytes: RESOURCE_METADATA_MAX_BYTES });
+    for (const candidate of candidates) {
+        let resolved;
+        try {
+            resolved = new URL(candidate, url).href;
+        }
+        catch {
+            continue;
+        }
+        try {
+            const response = await fetchMetadata(resolved, {
+                headers: { accept: "application/json" },
+                signal,
+            });
+            if (!response.ok)
+                continue;
+            const document = (await response.json());
+            if (isRecord(document))
+                return { resourceMetadataUrl: resolved, resourceMetadata: document };
+        }
+        catch {
+            // Unreachable, refused or not JSON: the next place, or no metadata.
+        }
+    }
+    return {};
+}
+/** `resource_metadata` of a `WWW-Authenticate` challenge (RFC 9728 §5.1). */
+function resourceMetadataParam(challenge) {
+    const match = /resource_metadata\s*=\s*(?:"([^"]*)"|([^\s,]+))/i.exec(challenge);
+    const value = match?.[1] ?? match?.[2];
+    return value ? value : undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/mcp/snapshot.d.ts

@@ -7,16 +7,41 @@ export interface McpToolRecord {
     readonly agentId?: string;
     readonly capabilityId: 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;
+    /**
+     * The server's hints that calling the tool again is safe (R2b C7, Q15): a call whose answer
+     * was lost after it was sent is then `mcp.lost` to the model, not `uncertain`.
+     */
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+        readonly idempotentHint?: boolean;
+    };
+    /**
+     * 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 capabilityId: 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[];
 }
 export interface McpDiagnostic {
     /** The agent used as a tool that declares the server; absent for the session's root agent. */
@@ -26,17 +51,66 @@ 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. */
 export declare function mcpDiscovered(snapshot: McpSnapshot, diagnostics: readonly McpDiagnostic[]): EventPayload<"mcp.discovered">;
-export declare function modelToolName(serverName: string, serverToolName: string): string;
+/** 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;
 export declare function declaredToolNames(manifest: AgentManifest): Set<string>;
 /**
- * The tools of a snapshot, as the engine advertises them. A tool of a server whose `approval` is
- * `always` in the session's `manifest` waits for approval on each call.
+ * 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); one whose approval resolves to `always`
+ *   waits for approval on each call;
+ * - a deferred tool (R2b C10) is marked so, out of the model's list, and its agent gets
+ *   `tool_search`, with the note on the servers it holds deferred tools of, and `tool_call` in
+ *   its `nylorun.tools` capability. An agent whose turn has no such capability keeps its tools in
+ *   its list.
+ *
+ * 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 snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. */
-export declare function mcpToolOf(snapshot: McpSnapshot | undefined, request: Pick<HostEffect, "agent" | "capabilityId" | "toolName">): McpToolRecord | 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). An agent without
+ * the `nylorun.tools` capability (its definition names a tool `tool_search` or `tool_call`, or the
+ * session was opened before it existed) defers nothing.
+ */
+export declare function pinDeferral(snapshot: McpSnapshot, manifest: AgentManifest, contextWindow: number): McpSnapshot;
+/**
+ * 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).
+ */
+export declare function mcpToolOf(snapshot: McpSnapshot | undefined, request: Pick<HostEffect, "agent" | "capabilityId" | "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;
 /** 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;