@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/mcp-resolver.js

@@ -0,0 +1,238 @@
+/**
+ * Resolves the MCP servers a turn's agent writes and its plugins carry into
+ * an intermediate ResolvedMcpServer format.
+ *
+ * THE single resolver for both harnesses: the turn runtime's MCP phase
+ * (harness/turn-context.ts, serving both adapters) and a tools listing
+ * (shared/mcp-tool-listing.ts, through entryToResolved) consume it. Each
+ * harness maps the result into its SDK format at the last hop:
+ * toMcpClientConfig (shared/mcp-manager.ts) for LangChain,
+ * toCursorMcpConfig (execute-cursor/cursor-mcp-config.ts) for the Cursor
+ * SDK — so a behavioral change here (like the transport guard) lands in
+ * both execution paths by construction.
+ *
+ * A plugin's server is named as Claude Code names it, `plugin_<plugin>_<server>`
+ * (plugin-servers.ts), so a tool list written for Claude Code scopes the
+ * same tools here and a hook sees the names it expects. A server the agent
+ * writes itself is named by its own name, as Claude Code names a server
+ * added directly (`mcp__<name>__<tool>`), and read as a plugin entry
+ * (agent-servers.ts), so both go through one loop: the URL check, the
+ * declared-key filter, the platform address fill, the transport guard.
+ *
+ * Every resolved server records its home (`McpServerHome`): the plugin it
+ * is part of, the agent that writes it, or the platform for the runner's
+ * own attachments. Every reader that tells them apart (the tool listing,
+ * the hooks' names, the platform set, the server count) switches on it.
+ *
+ * Each server is filled only from its own values: the group the run's value
+ * fetch answered for its home and name (shared/run-values.ts), plus the
+ * platform-filled keys the caller hands over (the caller identity), through
+ * the per-server filter over the keys the entry reads. A server the fetch
+ * named no group for gets no run values. A server whose URL is not, byte for
+ * byte, the URL its group was checked against is skipped for the turn with a
+ * warning naming it: the server checked each login's address against that
+ * URL when it handed the values over, and a value goes nowhere else.
+ *
+ * The one platform key filled here is STIGMER_SERVER_ADDRESS
+ * (platform-server-address.ts), before the declared-key filter so the filter
+ * sees the key present.
+ */
+import { assertTransportAllowed, McpTransportError, } from "./mcp-transport-guard.js";
+import { resolveHeaders, resolvePlaceholders, filterEnvToDeclaredKeys, PlaceholderResolutionError, } from "./placeholder-resolver.js";
+import { agentServerEntry } from "./agent-servers.js";
+import { fillPlatformServerAddress } from "./platform-server-address.js";
+import { toolServerSegment } from "./plugin-servers.js";
+import { toolValuesKey } from "./run-values.js";
+/** A server's home in a sentence, for the refusals that name two servers. */
+export function describeServerHome(home, slug) {
+    switch (home.kind) {
+        case "plugin":
+            return `plugin '${home.plugin}' server '${home.server}'`;
+        case "agent":
+            return home.subagent === null
+                ? `the agent's own server '${home.server}'`
+                : `subagent '${home.subagent}''s own server '${home.server}'`;
+        case "platform":
+            return `the platform's server '${slug}'`;
+        /* v8 ignore next -- @preserve: the exhaustiveness guard over a closed union; no value reaches it */
+        default: {
+            const exhaustive = home;
+            return exhaustive;
+        }
+    }
+}
+/** Whether two homes are one: the same plugin's or agent's server of one name, or both the platform's. */
+export function sameServerHome(a, b) {
+    switch (a.kind) {
+        case "plugin":
+            return b.kind === "plugin" && a.pluginId === b.pluginId && a.server === b.server;
+        case "agent":
+            return b.kind === "agent" && a.agentId === b.agentId && a.server === b.server;
+        case "platform":
+            return b.kind === "platform";
+        /* v8 ignore next -- @preserve: the exhaustiveness guard over a closed union; no value reaches it */
+        default: {
+            const exhaustive = a;
+            return exhaustive;
+        }
+    }
+}
+/** The platform's own servers among `servers`, by slug: the one answer to "is this the platform's?". */
+export function platformServerSlugsOf(servers) {
+    return new Set(servers.filter((server) => server.home.kind === "platform").map((server) => server.slug));
+}
+/** Two of a turn's servers would take one name; the turn cannot run them both. */
+export class DuplicateServerNameError extends Error {
+    constructor(name, first, second) {
+        super(`two MCP servers of this turn would both be named '${name}' (${first} and ${second}); remove or rename one of them`);
+        this.name = "DuplicateServerNameError";
+    }
+}
+/** The servers to resolve: the agent's own first, then each plugin's. */
+function turnServerSources(agent, plugins) {
+    const sources = [];
+    for (const server of agent?.servers ?? []) {
+        sources.push({
+            home: { kind: "agent", agentId: agent.agentId, subagent: agent.subagent, server: server.name },
+            slug: server.name,
+            valuesKey: toolValuesKey("agent", agent.agentId, server.name),
+            entryWith: (values) => agentServerEntry(server, values),
+        });
+    }
+    for (const plugin of plugins) {
+        const pluginId = plugin.metadata?.id ?? "";
+        const pluginName = plugin.metadata?.name ?? "";
+        for (const entry of plugin.status?.mcpServers ?? []) {
+            sources.push({
+                home: { kind: "plugin", pluginId, plugin: pluginName, server: entry.name },
+                slug: toolServerSegment(pluginName, entry.name),
+                valuesKey: toolValuesKey("plugin", pluginId, entry.name),
+                entryWith: () => entry,
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Resolve every MCP server of one agent of the turn: the servers it writes
+ * itself, then its plugins'.
+ *
+ * @param input.agent The agent whose own servers to resolve; undefined for
+ *        the built-in assistant.
+ * @param input.plugins Its plugins, each at the version it resolved to.
+ * @param input.tools The run's values per tool, by {@link toolValuesKey}.
+ * @param input.platformValues Platform-filled keys every server may read
+ *        (the caller identity); authoritative over a same-named run value.
+ * @param input.transportPosture Whether stdio servers may run here (derive
+ *        via resolveMcpTransportPosture(config.mode)). A stdio server under a
+ *        forbidding posture throws {@link McpTransportError} and fails the
+ *        whole resolution — never degraded to a skipped server.
+ * @param input.platformEndpoints The runner's endpoints a missing
+ *        STIGMER_SERVER_ADDRESS is filled from (the runner Config satisfies
+ *        it). Required so no resolution path can forget the fill.
+ */
+export function resolveTurnServers(input) {
+    const resolved = [];
+    const named = new Map();
+    for (const { home, slug, valuesKey, entryWith } of turnServerSources(input.agent, input.plugins)) {
+        // Two servers one name would share every table keyed by it (the
+        // engines' server configs, tool lists, leases, marks, hook matchers):
+        // the turn is refused rather than one silently taking the other's
+        // place. Run planning refuses it first; this is the backstop.
+        const holder = named.get(slug);
+        if (holder !== undefined) {
+            throw new DuplicateServerNameError(slug, holder, describeServerHome(home, slug));
+        }
+        named.set(slug, describeServerHome(home, slug));
+        try {
+            const group = input.tools.get(valuesKey);
+            const entry = entryWith(group?.values);
+            if (group !== undefined && group.url !== dialedUrlOf(entry)) {
+                console.warn(`MCP server '${slug}' no longer dials the URL its values were checked against ` +
+                    "when this turn started: it is skipped for this turn. Recover the run to plan its values again.");
+                continue;
+            }
+            const serverEnv = filterEnvToDeclaredKeys(declaredKeysOf(entry), fillPlatformServerAddress(entry, slug, { ...group?.values, ...input.platformValues }, input.platformEndpoints), `MCP server '${slug}'`);
+            const server = entryToResolved(entry, slug, serverEnv, home);
+            if (server) {
+                assertTransportAllowed(server.slug, server.connectionType, input.transportPosture);
+                resolved.push(server);
+            }
+        }
+        catch (err) {
+            if (err instanceof McpTransportError) {
+                // Policy rejection, not a resolution hiccup: swallowing it here
+                // would mean the agent silently loses tools. Fail the execution.
+                throw err;
+            }
+            if (err instanceof PlaceholderResolutionError) {
+                console.error(`MCP server '${slug}': ${err.message}`);
+            }
+            else {
+                console.warn(`Failed to resolve MCP server '${slug}': ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    return { resolvedServers: resolved };
+}
+/**
+ * How many of a turn's servers the agent and session declared: the
+ * agent's own and the plugins', the platform's own attachments excluded
+ * (the timing record's `mcp_server_count`, read by benchmark/report.ts).
+ */
+export function declaredServerCount(servers) {
+    return servers.filter((server) => server.home.kind !== "platform").length;
+}
+/** The keys a server reads, as the env filter takes them. */
+export function declaredKeysOf(entry) {
+    return Object.fromEntries(entry.env.map((key) => [key, true]));
+}
+/** The URL a server dials: its HTTP URL, or "" for a local program. */
+export function dialedUrlOf(entry) {
+    return entry.transport.case === "http" ? entry.transport.value.url : "";
+}
+export function entryToResolved(entry, slug, envVars, home) {
+    switch (entry.transport.case) {
+        case "stdio": {
+            const stdio = entry.transport.value;
+            if (!stdio.command)
+                return null;
+            const resolvedArgs = stdio.args.length > 0
+                ? stdio.args.map((arg, i) => resolvePlaceholders(arg, envVars, `stdio arg[${i}]`))
+                : undefined;
+            return {
+                slug,
+                connectionType: "stdio",
+                command: stdio.command,
+                args: resolvedArgs,
+                env: Object.keys(envVars).length > 0 ? { ...envVars } : undefined,
+                home,
+            };
+        }
+        case "http": {
+            const http = entry.transport.value;
+            if (!http.url)
+                return null;
+            const rawHeaders = Object.keys(http.headers).length > 0 ? http.headers : undefined;
+            const resolved = rawHeaders
+                ? resolveHeaders(Object.fromEntries(Object.entries(rawHeaders)), envVars)
+                : undefined;
+            return {
+                slug,
+                connectionType: "http",
+                url: http.url,
+                headers: resolved,
+                home,
+            };
+        }
+        case undefined:
+            return null;
+        /* v8 ignore next -- @preserve: the exhaustiveness guard over the transport oneof; a decoded entry's case is one of the arms above or undefined */
+        default: {
+            const exhaustive = entry.transport;
+            return exhaustive;
+        }
+    }
+}
+export { PlaceholderResolutionError } from "./placeholder-resolver.js";
+//# sourceMappingURL=mcp-resolver.js.map

package/dist/shared/mcp-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-resolver.js","sourceRoot":"","sources":["../../src/shared/mcp-resolver.ts"],"names":[],"mappings":"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"}

package/dist/shared/mcp-schema-sanitizer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Unicode-flag regex sanitization for MCP tool input schemas (issue #420).
+ *
+ * Why this exists: real-world MCP servers ship JSON-schema `pattern` values
+ * that are legal as plain ECMAScript regexes but invalid under the unicode
+ * flag (PayPal's `^https\:\/\/` — `\:` is an invalid escape under /u).
+ * @langchain/core validates tool input on EVERY call with
+ * @cfworker/json-schema, which compiles patterns via `new RegExp(p, "u")`
+ * at exactly two uncaught sites: the `pattern` keyword and each
+ * `patternProperties` key. One bad vendor pattern therefore makes the tool
+ * permanently uncallable on the deep-agent path — every invocation dies
+ * with a cryptic SyntaxError before the tool is ever reached. (The third
+ * /u compile site, `format: "regex"`, validates instance values inside a
+ * try/catch and fails gracefully — not a crash surface.)
+ *
+ * The fix: at the deep-agent connect funnel (mcp-manager.ts
+ * connectMcpServers), drop every pattern that cannot compile under /u.
+ * Dropping is deliberate — rewriting to a /u-safe equivalent would need an
+ * Annex-B-aware regex transpiler, disproportionate machinery for what is
+ * best-effort client-side validation; the MCP server still validates its
+ * own inputs server-side. This mirrors the loosening posture of
+ * @langchain/mcp-adapters' own schema pipeline (dereferenceJsonSchema →
+ * simplifyJsonSchemaForLLM), which already normalizes schemas for this
+ * exact validator.
+ *
+ * THE INVARIANT: sanitization may only ever LOOSEN validation, never
+ * tighten it. Dropping a `patternProperties` entry naively would violate
+ * this — @cfworker marks pattern-matched keys as "evaluated" and routes
+ * unevaluated keys into the `additionalProperties` / `unevaluatedProperties`
+ * checks, so under `additionalProperties: false` the drop would flip a
+ * crash into a false REJECTION of valid inputs. Whenever a
+ * `patternProperties` entry is dropped, any restrictive
+ * `additionalProperties` / `unevaluatedProperties` at that schema level is
+ * therefore relaxed too.
+ *
+ * Scope: this sanitizer serves the EXECUTION path only. A tools listing
+ * (shared/mcp-tool-listing.ts) reads names, descriptions and marks, never
+ * schemas, and never invokes a tool, so it cannot hit the crash.
+ */
+/** One dropped regex constraint, for the caller's log line. */
+export interface DroppedPattern {
+    /** JSON-pointer-style path of the dropped constraint within the schema. */
+    location: string;
+    /** The pattern source that failed to compile under the unicode flag. */
+    pattern: string;
+    /**
+     * True when the pattern compiles WITHOUT the /u flag — vendor sloppiness
+     * (Annex B legacy syntax), the oss#420 class. False means the regex is
+     * broken outright; either way validation could only crash, so both drop.
+     */
+    compilesWithoutUnicodeFlag: boolean;
+}
+/**
+ * Drop unicode-invalid regex patterns from a JSON schema, in place.
+ *
+ * Walks only schema positions (the recursion set is @cfworker's own
+ * validated-keyword list), so a property literally NAMED "pattern" under
+ * `properties` is never touched. The walker handles composition keywords
+ * (anyOf/allOf/oneOf/not/if-then-else) even though the adapter's
+ * simplifyJsonSchemaForLLM currently strips them, and carries a visited-set
+ * cycle guard even though the adapter's $ref inlining currently guarantees
+ * an acyclic result — correctness here must not depend on another
+ * package's internals holding across dependency bumps.
+ *
+ * Returns the dropped constraints (empty for clean schemas — the common
+ * case, which this walk leaves byte-identical).
+ */
+export declare function sanitizeSchemaPatterns(schema: unknown): DroppedPattern[];

package/dist/shared/mcp-schema-sanitizer.js

@@ -0,0 +1,195 @@
+/**
+ * Unicode-flag regex sanitization for MCP tool input schemas (issue #420).
+ *
+ * Why this exists: real-world MCP servers ship JSON-schema `pattern` values
+ * that are legal as plain ECMAScript regexes but invalid under the unicode
+ * flag (PayPal's `^https\:\/\/` — `\:` is an invalid escape under /u).
+ * @langchain/core validates tool input on EVERY call with
+ * @cfworker/json-schema, which compiles patterns via `new RegExp(p, "u")`
+ * at exactly two uncaught sites: the `pattern` keyword and each
+ * `patternProperties` key. One bad vendor pattern therefore makes the tool
+ * permanently uncallable on the deep-agent path — every invocation dies
+ * with a cryptic SyntaxError before the tool is ever reached. (The third
+ * /u compile site, `format: "regex"`, validates instance values inside a
+ * try/catch and fails gracefully — not a crash surface.)
+ *
+ * The fix: at the deep-agent connect funnel (mcp-manager.ts
+ * connectMcpServers), drop every pattern that cannot compile under /u.
+ * Dropping is deliberate — rewriting to a /u-safe equivalent would need an
+ * Annex-B-aware regex transpiler, disproportionate machinery for what is
+ * best-effort client-side validation; the MCP server still validates its
+ * own inputs server-side. This mirrors the loosening posture of
+ * @langchain/mcp-adapters' own schema pipeline (dereferenceJsonSchema →
+ * simplifyJsonSchemaForLLM), which already normalizes schemas for this
+ * exact validator.
+ *
+ * THE INVARIANT: sanitization may only ever LOOSEN validation, never
+ * tighten it. Dropping a `patternProperties` entry naively would violate
+ * this — @cfworker marks pattern-matched keys as "evaluated" and routes
+ * unevaluated keys into the `additionalProperties` / `unevaluatedProperties`
+ * checks, so under `additionalProperties: false` the drop would flip a
+ * crash into a false REJECTION of valid inputs. Whenever a
+ * `patternProperties` entry is dropped, any restrictive
+ * `additionalProperties` / `unevaluatedProperties` at that schema level is
+ * therefore relaxed too.
+ *
+ * Scope: this sanitizer serves the EXECUTION path only. A tools listing
+ * (shared/mcp-tool-listing.ts) reads names, descriptions and marks, never
+ * schemas, and never invokes a tool, so it cannot hit the crash.
+ */
+/** Keywords whose value is a single subschema. */
+const SINGLE_SCHEMA_KEYWORDS = [
+    "additionalProperties",
+    "unevaluatedProperties",
+    "propertyNames",
+    "items",
+    "additionalItems",
+    "unevaluatedItems",
+    "contains",
+    "not",
+    "if",
+    "then",
+    "else",
+];
+/** Keywords whose value is an array of subschemas. */
+const SCHEMA_ARRAY_KEYWORDS = ["anyOf", "allOf", "oneOf", "prefixItems"];
+/** Keywords whose value is an object mapping names to subschemas. */
+const SCHEMA_MAP_KEYWORDS = [
+    "properties",
+    "patternProperties",
+    "dependentSchemas",
+    "$defs",
+    "definitions",
+];
+function compilesUnderUnicodeFlag(pattern) {
+    try {
+        new RegExp(pattern, "u");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function compilesWithoutUnicodeFlag(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** JSON-pointer token escaping (RFC 6901): `~` → `~0`, `/` → `~1`. */
+function pointerToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/**
+ * Drop unicode-invalid regex patterns from a JSON schema, in place.
+ *
+ * Walks only schema positions (the recursion set is @cfworker's own
+ * validated-keyword list), so a property literally NAMED "pattern" under
+ * `properties` is never touched. The walker handles composition keywords
+ * (anyOf/allOf/oneOf/not/if-then-else) even though the adapter's
+ * simplifyJsonSchemaForLLM currently strips them, and carries a visited-set
+ * cycle guard even though the adapter's $ref inlining currently guarantees
+ * an acyclic result — correctness here must not depend on another
+ * package's internals holding across dependency bumps.
+ *
+ * Returns the dropped constraints (empty for clean schemas — the common
+ * case, which this walk leaves byte-identical).
+ */
+export function sanitizeSchemaPatterns(schema) {
+    const dropped = [];
+    if (!isPlainObject(schema))
+        return dropped;
+    walkSchema(schema, "", dropped, new Set());
+    return dropped;
+}
+function recordDrop(dropped, location, pattern) {
+    dropped.push({
+        location,
+        pattern,
+        compilesWithoutUnicodeFlag: compilesWithoutUnicodeFlag(pattern),
+    });
+}
+function walkSchema(node, path, dropped, seen) {
+    if (seen.has(node))
+        return;
+    seen.add(node);
+    if (typeof node.pattern === "string" && !compilesUnderUnicodeFlag(node.pattern)) {
+        recordDrop(dropped, `${path}/pattern`, node.pattern);
+        delete node.pattern;
+    }
+    if (isPlainObject(node.patternProperties)) {
+        const patternProperties = node.patternProperties;
+        let droppedEntry = false;
+        for (const key of Object.keys(patternProperties)) {
+            if (compilesUnderUnicodeFlag(key))
+                continue;
+            recordDrop(dropped, `${path}/patternProperties/${pointerToken(key)}`, key);
+            delete patternProperties[key];
+            droppedEntry = true;
+        }
+        if (droppedEntry) {
+            // Never-tighten: keys the dropped pattern used to match would now
+            // fall through to these checks and could be falsely rejected.
+            if (node.additionalProperties !== undefined && node.additionalProperties !== true) {
+                delete node.additionalProperties;
+            }
+            if (node.unevaluatedProperties !== undefined && node.unevaluatedProperties !== true) {
+                delete node.unevaluatedProperties;
+            }
+            if (Object.keys(patternProperties).length === 0) {
+                delete node.patternProperties;
+            }
+        }
+    }
+    for (const keyword of SINGLE_SCHEMA_KEYWORDS) {
+        const value = node[keyword];
+        if (isPlainObject(value)) {
+            walkSchema(value, `${path}/${keyword}`, dropped, seen);
+        }
+    }
+    for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+        const value = node[keyword];
+        if (!Array.isArray(value))
+            continue;
+        value.forEach((entry, index) => {
+            if (isPlainObject(entry)) {
+                walkSchema(entry, `${path}/${keyword}/${index}`, dropped, seen);
+            }
+        });
+    }
+    for (const keyword of SCHEMA_MAP_KEYWORDS) {
+        const value = node[keyword];
+        if (!isPlainObject(value))
+            continue;
+        for (const [name, entry] of Object.entries(value)) {
+            if (isPlainObject(entry)) {
+                walkSchema(entry, `${path}/${keyword}/${pointerToken(name)}`, dropped, seen);
+            }
+        }
+    }
+    // Draft-07 `items` tuple form and `dependencies` schema form — both
+    // keywords are dual-shaped, so the typed loops above miss these arms.
+    if (Array.isArray(node.items)) {
+        node.items.forEach((entry, index) => {
+            if (isPlainObject(entry)) {
+                walkSchema(entry, `${path}/items/${index}`, dropped, seen);
+            }
+        });
+    }
+    if (isPlainObject(node.dependencies)) {
+        for (const [name, entry] of Object.entries(node.dependencies)) {
+            // Array-valued entries are dependentRequired (property names, not
+            // schemas) — only schema-valued entries are walked.
+            if (isPlainObject(entry)) {
+                walkSchema(entry, `${path}/dependencies/${pointerToken(name)}`, dropped, seen);
+            }
+        }
+    }
+}
+//# sourceMappingURL=mcp-schema-sanitizer.js.map

package/dist/shared/mcp-schema-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-schema-sanitizer.js","sourceRoot":"","sources":["../../src/shared/mcp-schema-sanitizer.ts"],"names":[],"mappings":"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"}

package/dist/shared/mcp-tool-listing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Lists the tools an MCP server offers now, with the one mark the approval
+ * default reads: whether the tool's own MCP annotation says
+ * `destructiveHint: true`. Nothing is stored; every listing asks the server.
+ *
+ * Two readers: a tools listing a person asks for from a plugin's page
+ * (activities/list-plugin-tools.ts, the connect workflow's one step), and
+ * the start of a turn on an engine that does not bind the tools itself (the
+ * Cursor engine's tools are loaded by its SDK, not by this runner), whose
+ * approval default needs the marks before the turn runs
+ * ({@link listTurnTools}). The native engine reads the same marks from the
+ * tools it loads, so it never lists twice.
+ *
+ * Annotations are untrusted (the MCP spec says so), so they are read only in
+ * the direction that adds a question: `readOnlyHint` is never read, and a
+ * tool marked both read-only and destructive asks. MCP's own default for an
+ * unannotated tool is "destructive"; Stigmer acts only on an explicit true,
+ * so a server that annotates nothing gates nothing. A server whose listing
+ * fails asks before every one of its tools (`McpToolListing.unlisted`): an
+ * unread mark never means "ask nothing".
+ *
+ * Bounds (issue #239): a remote endpoint that accepts a connection but never
+ * completes the handshake would otherwise hang forever, so HTTP servers get
+ * a short init bound and stdio servers a generous one, because a first run
+ * may compile or install packages (issue #243). A local program is started
+ * as the agent user on a separating runner (`stdioAsAgent`): its command is
+ * the plugin's, and must never run with the runner's rights.
+ */
+import { type Connection } from "@langchain/mcp-adapters";
+import { type AgentIdentity } from "./agent-identity.js";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+/** One tool a server lists. */
+export interface ListedTool {
+    readonly name: string;
+    readonly description: string;
+    /** The tool's MCP annotation `destructiveHint === true`, and nothing else. */
+    readonly destructive: boolean;
+}
+/** What a turn's listing found: each listed server's tool names, each destructive tool, and the servers whose listing failed. */
+export interface McpToolListing {
+    readonly listed: readonly {
+        readonly server: string;
+        readonly tools: readonly string[];
+    }[];
+    readonly destructive: readonly {
+        readonly server: string;
+        readonly tool: string;
+    }[];
+    readonly unlisted: readonly string[];
+}
+/** The session-init bound for a server's transport. */
+export declare function initTimeoutMsFor(connectionType: ResolvedMcpServer["connectionType"]): number;
+/**
+ * The user-facing message for a session-init timeout. Names the endpoint (or
+ * command) so the failure is diagnosable from the message alone, and explains
+ * the known silent-hang shape for HTTP endpoints — issue #239's mechanism.
+ */
+export declare function initTimeoutMessageFor(slug: string, resolved: ResolvedMcpServer): string;
+/**
+ * A stdio server's connection rewritten to start as the agent user through
+ * `setpriv`, with the agent's home as `HOME`, on a separating runner
+ * (`shared/agent-identity.ts`). An HTTP server, and every server on a runner
+ * that does not separate, is unchanged.
+ */
+export declare function stdioAsAgent(config: Record<string, Connection>, identity?: AgentIdentity | null): Record<string, Connection>;
+/**
+ * Connects to one resolved server and lists its tools. Throws the server's
+ * failure; an HTTP server asking for a sign-in is re-probed once so the
+ * failure says so instead of the MCP client's opaque aggregate.
+ */
+export declare function listServerTools(server: ResolvedMcpServer): Promise<ListedTool[]>;
+/**
+ * Lists every server of a turn in parallel, the agent's own and its
+ * plugins', for an engine that does not bind the tools itself, so a tool
+ * either marks destructive asks first whichever kind of server holds it.
+ * The platform's own servers are never listed:
+ * none of their tools asks. A server whose listing fails is named in
+ * `unlisted`, with the reason logged.
+ */
+export declare function listTurnTools(servers: readonly ResolvedMcpServer[], list?: (server: ResolvedMcpServer) => Promise<readonly ListedTool[]>): Promise<McpToolListing>;