agent-trellis 0.5.2 → 0.6.2

package/dist/core/adapter.d.ts

@@ -50,6 +50,13 @@ export interface AdapterPlanItem {
     /** Human-readable description of one change this adapter would make
      * ("create" / "remove") or why it refused to ("conflict"). */
     description: string;
+    /** Only set (and only meaningful) when `action === "conflict"`: the
+     * concrete next action a user can take, distinct from restating why
+     * it conflicted (`description` already does that) — surfaced in
+     * `trellis onboard`'s verdict block (trellis-onboard-closed-loop
+     * design.md D7). Optional so existing conflict sites keep compiling
+     * and rendering cleanly before each is given one. */
+    remediation?: string;
     /** What's being touched, for the collision/audit checks to reason
      * about. For `kind: "mcp"`, the config file being modified (e.g.
      * `~/.codex/config.toml`), not a per-server path — there isn't one. */

package/dist/core/canonical.d.ts

@@ -4,7 +4,7 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { CanonicalSource, McpServerDef } from "./types.js";
+import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
@@ -31,6 +31,32 @@ export declare function upsertServerYaml(path: string, name: string, def: McpSer
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
 export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
+/**
+ * `trellis onboard --mcp-mode <value>` (trellis-onboard-mcp-mode) —
+ * everything needed to select or clear the top-level `hub`/`gateway`
+ * mode fields, mutually exclusive by construction (design.md D3): a
+ * `"direct"` mode carries nothing to set, only two keys to clear.
+ */
+export type McpMode = {
+    kind: "direct";
+} | {
+    kind: "hub";
+    url: string;
+} | {
+    kind: "gateway";
+    agents?: AgentId[];
+};
+/**
+ * Sets or clears `servers.yaml`'s top-level `hub`/`gateway` keys — the
+ * write path `upsertServerYaml`/`removeServerYaml` don't cover, since
+ * both are scoped to one `servers` entry (design.md D2). Same
+ * `Document`-based mechanism, same refusal posture on a missing or
+ * unparseable file, same `forceBlockStyle` correction for a key set for
+ * the first time into a still-flow-style document (`trellis init`'s
+ * starter file). Selecting one mode always clears the other two
+ * (design.md D3) — never left for the caller to remember.
+ */
+export declare function writeMcpModeYaml(path: string, mode: McpMode): ServersYamlWriteResult;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use

package/dist/core/canonical.js

@@ -88,8 +88,24 @@ function loadServersYaml(path) {
         servers,
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
+        gateway: fromGatewayYaml(parsed.gateway),
     };
 }
+/**
+ * A `gateway:` block with no `enabled` key reads as off, not as on — the
+ * only safe default for a field whose whole effect is to stop writing the
+ * per-server entries an agent is currently working with. Absent entirely,
+ * the field stays `undefined` so `resolveMcpPlan` can tell "never
+ * configured" from "explicitly disabled" if that ever matters.
+ */
+function fromGatewayYaml(gateway) {
+    if (!gateway)
+        return undefined;
+    const out = { enabled: gateway.enabled === true };
+    if (gateway.agents)
+        out.agents = gateway.agents;
+    return out;
+}
 /**
  * Writes or replaces one server entry in `servers.yaml`, preserving
  * every other entry's and comment's exact formatting (trellis-
@@ -149,6 +165,52 @@ export function removeServerYaml(path, name) {
     writeFileSync(path, doc.toString());
     return { ok: true };
 }
+/**
+ * Sets or clears `servers.yaml`'s top-level `hub`/`gateway` keys — the
+ * write path `upsertServerYaml`/`removeServerYaml` don't cover, since
+ * both are scoped to one `servers` entry (design.md D2). Same
+ * `Document`-based mechanism, same refusal posture on a missing or
+ * unparseable file, same `forceBlockStyle` correction for a key set for
+ * the first time into a still-flow-style document (`trellis init`'s
+ * starter file). Selecting one mode always clears the other two
+ * (design.md D3) — never left for the caller to remember.
+ */
+export function writeMcpModeYaml(path, mode) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    switch (mode.kind) {
+        case "direct":
+            doc.delete("hub");
+            doc.delete("gateway");
+            break;
+        case "hub":
+            doc.setIn(["hub", "url"], mode.url);
+            doc.delete("gateway");
+            forceBlockStyle(doc.get("hub", true));
+            break;
+        case "gateway":
+            doc.setIn(["gateway", "enabled"], true);
+            if (mode.agents !== undefined) {
+                doc.setIn(["gateway", "agents"], mode.agents);
+            }
+            else {
+                doc.deleteIn(["gateway", "agents"]);
+            }
+            doc.delete("hub");
+            forceBlockStyle(doc.get("gateway", true));
+            break;
+    }
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
 function loadSecretsPolicyYaml(path, homeDir) {
     if (!existsSync(path)) {
         return { allowedVars: [], rejectPatterns: [] };

package/dist/core/types.d.ts

@@ -87,20 +87,46 @@ export interface McpServerDef {
 export interface HubConfig {
     url: string;
 }
+/**
+ * Converge an agent's MCP config onto one local stdio process Trellis
+ * itself spawns (`trellis mcp-gateway --agent <id>`), instead of writing
+ * one native entry per server.
+ *
+ * Deliberately NOT the same field as `hub`: `hub` names an HTTP endpoint
+ * the user operates somewhere else and Trellis never starts; this names a
+ * subprocess Trellis owns. Overloading one field to mean both would force
+ * every future reader to disambiguate two unrelated concepts by context
+ * (trellis-mcp-gateway-hosting design.md D5).
+ */
+export interface GatewayConfig {
+    enabled: boolean;
+    /**
+     * Which agents converge through the gateway. Omit — the expected normal
+     * case — and `enabled` applies to every managed agent; which agents
+     * converge is not a question a user should have to answer to get the
+     * feature. Present, it narrows to exactly these, leaving the rest in
+     * direct or hub mode.
+     */
+    agents?: AgentId[];
+}
 export interface McpConfig {
     servers: Record<string, McpServerDef>;
     /**
      * Server names a host environment (e.g. mirasim) is known to inject at
      * runtime. Checked against every server name Trellis would write per
-     * agent when `hub` is unset; against the single hub entry name only when
-     * `hub` is set (there's nothing else to collide) — see docs/research.md
-     * "Codex — three hard constraints" for why a same-name collision is not
-     * a soft failure on every agent.
+     * agent in direct mode; against the single converged entry name only in
+     * hub or gateway mode (there's nothing else to collide) — see
+     * docs/research.md "Codex — three hard constraints" for why a same-name
+     * collision is not a soft failure on every agent.
      */
     knownHostInjected: string[];
     /** Omit for direct mode (today's default: every agent gets all N server
      * definitions written into its native config). See `HubConfig`. */
     hub?: HubConfig;
+    /** Omit for direct mode. See `GatewayConfig`. Independent of `hub`: the
+     * two mean different things and may both be set, in which case gateway
+     * wins per agent (trellis-mcp-gateway-hosting design.md D5/D6). */
+    gateway?: GatewayConfig;
 }
 export interface SkillRef {
     name: string;

package/dist/lib/backup.js

@@ -15,11 +15,40 @@ import { basename, join } from "node:path";
 function sha256(content) {
     return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
-/** `:` and `.` are legal in POSIX filenames but awkward across shells and
- * some tooling; replaced so a run id is safe to pass around bare. */
+let lastTimestamp = "";
+let sameMillisecondSeq = 0;
+/**
+ * `<iso-timestamp>-<seq>-<command>`.
+ *
+ * `:` and `.` are legal in POSIX filenames but awkward across shells and
+ * some tooling; replaced so a run id is safe to pass around bare.
+ *
+ * The sequence number is what makes `rollback.ts`'s "lexical sort is
+ * chronological sort" assumption actually true. Without it, two sessions
+ * opened in the same millisecond tie on the timestamp and the *command
+ * name* decides the order — so `...469Z-mcp-sync` sorts before
+ * `...469Z-sync` even though it ran second, and `trellis rollback` with
+ * no run id restores the wrong run. It is always present, never omitted
+ * for the first run of a millisecond: an id that sometimes has the field
+ * and sometimes doesn't reintroduces the same tie-break-by-command bug
+ * between those two shapes.
+ *
+ * Scope of the guarantee: within one process. Two separate `trellis`
+ * invocations landing in the same millisecond would still tie — not
+ * realistically reachable for a CLI that reads canonical and touches the
+ * filesystem before opening a session, and no worse than the behavior
+ * this replaces.
+ */
 function runIdFor(command) {
     const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    return `${ts}-${command}`;
+    if (ts === lastTimestamp) {
+        sameMillisecondSeq += 1;
+    }
+    else {
+        lastTimestamp = ts;
+        sameMillisecondSeq = 0;
+    }
+    return `${ts}-${String(sameMillisecondSeq).padStart(3, "0")}-${command}`;
 }
 export function backupsRoot(homeDir) {
     return join(homeDir, ".trellis", "backups");

package/dist/lib/envVarNames.d.ts

@@ -20,12 +20,29 @@ export declare function extractTemplateVarNames(value: string): string[];
  * same answer to "what names does this def reference," not two
  * separately-maintained collections. */
 export declare function declaredEnvNames(def: McpServerDef): string[];
-/** Claude Code / Kiro's config is real JSON — parse it and walk each
- * server's `env` object keys plus names embedded in `headers` object
- * *values* (unlike `env`, a header's key is an arbitrary header name,
- * not a variable name — the variable name lives inside the `${...}`
- * value). Returns `[]` (not a throw) on invalid JSON; that's a
- * diagnostic for a different command, not this extractor's job. */
+/**
+ * Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object *values*, plus names embedded in `headers`
+ * object values. Both read the same way: the variable name lives inside
+ * a `${...}` reference in the value, never the key alone.
+ *
+ * This matters because `env`/`staticEnv` share one JSON object with no
+ * structural tag distinguishing them (`renderJsonServerEntry`'s own doc
+ * comment) — `env`/`envAliases` render as a `${NAME}` reference,
+ * `staticEnv` renders as its literal value verbatim, same map. Reading
+ * every KEY unconditionally (as this function did before) swept
+ * `staticEnv`'s literal, never-a-secret keys into the same
+ * `allowed_vars` check `env` names need, and got `envAliases` wrong in
+ * the opposite direction — its value's `${sourceName}` differs from its
+ * own key, so a key-based read checked the wrong name against
+ * `allowed_vars` entirely. Extracting from the value fixes both at once:
+ * a literal `staticEnv` value has no `${...}` to match, so it
+ * contributes nothing; an `envAliases` entry correctly contributes its
+ * referenced source name, not its target key.
+ *
+ * Returns `[]` (not a throw) on invalid JSON; that's a diagnostic for a
+ * different command, not this extractor's job.
+ */
 export declare function extractJsonEnvVarNames(content: string): string[];
 /** Codex's config is TOML. The shapes audit needs: every `env_vars = [...]`
  * line's quoted string contents, plus a `bearer_token_env_var = "VAR"`

package/dist/lib/envVarNames.js

@@ -29,12 +29,29 @@ export function declaredEnvNames(def) {
     }
     return [...names];
 }
-/** Claude Code / Kiro's config is real JSON — parse it and walk each
- * server's `env` object keys plus names embedded in `headers` object
- * *values* (unlike `env`, a header's key is an arbitrary header name,
- * not a variable name — the variable name lives inside the `${...}`
- * value). Returns `[]` (not a throw) on invalid JSON; that's a
- * diagnostic for a different command, not this extractor's job. */
+/**
+ * Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object *values*, plus names embedded in `headers`
+ * object values. Both read the same way: the variable name lives inside
+ * a `${...}` reference in the value, never the key alone.
+ *
+ * This matters because `env`/`staticEnv` share one JSON object with no
+ * structural tag distinguishing them (`renderJsonServerEntry`'s own doc
+ * comment) — `env`/`envAliases` render as a `${NAME}` reference,
+ * `staticEnv` renders as its literal value verbatim, same map. Reading
+ * every KEY unconditionally (as this function did before) swept
+ * `staticEnv`'s literal, never-a-secret keys into the same
+ * `allowed_vars` check `env` names need, and got `envAliases` wrong in
+ * the opposite direction — its value's `${sourceName}` differs from its
+ * own key, so a key-based read checked the wrong name against
+ * `allowed_vars` entirely. Extracting from the value fixes both at once:
+ * a literal `staticEnv` value has no `${...}` to match, so it
+ * contributes nothing; an `envAliases` entry correctly contributes its
+ * referenced source name, not its target key.
+ *
+ * Returns `[]` (not a throw) on invalid JSON; that's a diagnostic for a
+ * different command, not this extractor's job.
+ */
 export function extractJsonEnvVarNames(content) {
     let parsed;
     try {
@@ -45,7 +62,9 @@ export function extractJsonEnvVarNames(content) {
     }
     const names = [];
     for (const server of Object.values(parsed.mcpServers ?? {})) {
-        names.push(...Object.keys(server.env ?? {}));
+        for (const value of Object.values(server.env ?? {})) {
+            names.push(...extractTemplateVarNames(value));
+        }
         for (const value of Object.values(server.headers ?? {})) {
             names.push(...extractTemplateVarNames(value));
         }

package/dist/lib/gatewayBackend.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The gateway's one seam (trellis-mcp-gateway-hosting design.md D11).
+ *
+ * `src/commands/mcpGateway.ts` — the MCP `Server` an agent actually talks
+ * to over stdio — may depend on nothing but `GatewayBackend`. It must
+ * never reference a connection, a transport, or a server definition. That
+ * restriction is the entire point: v1 ships `LocalBackend`, which connects
+ * upstreams in-process, and v2 adds a backend that forwards to one shared
+ * service instead. Swapping them is a single construction site, and by D2
+ * the agent's own config is identical either way, so converging every
+ * agent onto one process later needs no re-sync and no user-visible change.
+ *
+ * The three methods deliberately mirror the MCP operations the agent
+ * itself issues, so a future forwarding backend is a thin wrapper over a
+ * standard `Client` rather than something with its own shape to maintain
+ * (D12).
+ */
+import type { McpServerDef, SecretsPolicy } from "../core/types.js";
+import { type McpClientInfo } from "./mcpConnect.js";
+import { type AggregatedTool } from "./mcpToolRegistry.js";
+export interface GatewayBackend {
+    /** Every tool available through this backend, under its aggregated name. */
+    listTools(): Promise<AggregatedTool[]>;
+    /** Invoke one aggregated tool; implementations route it to its owner. */
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Release everything this backend holds. Must be safe to call twice. */
+    close(): Promise<void>;
+}
+/** One in-scope upstream, already resolved from canonical by the caller —
+ * `LocalBackend` does not decide scope, it connects what it is given. */
+export interface UpstreamSpec {
+    name: string;
+    def: McpServerDef;
+}
+export interface LocalBackendOptions {
+    secretsPolicy: SecretsPolicy;
+    clientInfo: McpClientInfo;
+    connectTimeoutMs: number;
+    /** Where per-upstream failures are reported. Defaults to stderr, which
+     * on a stdio MCP server is the only stream that is not the protocol. */
+    onWarning?: (message: string) => void;
+    /**
+     * Set to enable OAuth: before connecting an http/sse upstream, any
+     * stored token for it is refreshed if expired and attached as a Bearer
+     * header. Omitted, no OAuth is attempted at all — which is what keeps
+     * this class usable by callers that have no home directory.
+     *
+     * Never performs an interactive authorization: a refresh needs no
+     * browser, the initial grant does, and this runs inside a process with
+     * no terminal attached (design.md D9).
+     */
+    homeDir?: string;
+}
+/**
+ * v1's backend: connects each upstream itself and aggregates the result.
+ *
+ * Failure isolation is the invariant here — one upstream that is
+ * unreachable, misconfigured, or permanently hanging must never prevent
+ * the others' tools from being served (spec: connection-failure
+ * isolation). Every per-upstream step is therefore individually guarded,
+ * and a failure reports and drops that upstream alone.
+ */
+export declare class LocalBackend implements GatewayBackend {
+    private readonly warn;
+    private readonly registry;
+    private readonly connected;
+    private closed;
+    private constructor();
+    static connect(upstreams: readonly UpstreamSpec[], options: LocalBackendOptions): Promise<LocalBackend>;
+    private addUpstream;
+    listTools(): Promise<AggregatedTool[]>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+    private closeUpstream;
+}

package/dist/lib/gatewayBackend.js

@@ -0,0 +1,131 @@
+/**
+ * The gateway's one seam (trellis-mcp-gateway-hosting design.md D11).
+ *
+ * `src/commands/mcpGateway.ts` — the MCP `Server` an agent actually talks
+ * to over stdio — may depend on nothing but `GatewayBackend`. It must
+ * never reference a connection, a transport, or a server definition. That
+ * restriction is the entire point: v1 ships `LocalBackend`, which connects
+ * upstreams in-process, and v2 adds a backend that forwards to one shared
+ * service instead. Swapping them is a single construction site, and by D2
+ * the agent's own config is identical either way, so converging every
+ * agent onto one process later needs no re-sync and no user-visible change.
+ *
+ * The three methods deliberately mirror the MCP operations the agent
+ * itself issues, so a future forwarding backend is a thin wrapper over a
+ * standard `Client` rather than something with its own shape to maintain
+ * (D12).
+ */
+import { connectServer } from "./mcpConnect.js";
+import { withTimeout } from "./mcpConnect.js";
+import { ensureFreshToken } from "./oauth/refresh.js";
+import { McpToolRegistry } from "./mcpToolRegistry.js";
+/**
+ * v1's backend: connects each upstream itself and aggregates the result.
+ *
+ * Failure isolation is the invariant here — one upstream that is
+ * unreachable, misconfigured, or permanently hanging must never prevent
+ * the others' tools from being served (spec: connection-failure
+ * isolation). Every per-upstream step is therefore individually guarded,
+ * and a failure reports and drops that upstream alone.
+ */
+export class LocalBackend {
+    warn;
+    registry = new McpToolRegistry();
+    connected = new Set();
+    closed = false;
+    constructor(warn) {
+        this.warn = warn;
+    }
+    static async connect(upstreams, options) {
+        const warn = options.onWarning ?? ((message) => console.error(message));
+        const backend = new LocalBackend(warn);
+        await Promise.all(upstreams.map((upstream) => backend.addUpstream(upstream, options)));
+        return backend;
+    }
+    async addUpstream({ name, def }, options) {
+        let effectiveDef = def;
+        if (options.homeDir && def.url) {
+            try {
+                effectiveDef = await withOAuthHeader(name, def, options.homeDir);
+            }
+            catch (err) {
+                // A dead or unrenewable credential is reported and that upstream
+                // dropped — the same isolation a failed connection gets, never a
+                // browser and never a blocked startup.
+                this.warn(`trellis-mcp-gateway: skipping MCP server "${name}": ${errorText(err)}`);
+                return;
+            }
+        }
+        let client;
+        try {
+            client = (await connectServer(effectiveDef, options.secretsPolicy, options.connectTimeoutMs, options.clientInfo));
+        }
+        catch (err) {
+            this.warn(`trellis-mcp-gateway: failed to connect to MCP server "${name}": ${errorText(err)}`);
+            return;
+        }
+        this.connected.add(client);
+        let tools;
+        try {
+            const result = await withTimeout(client.listTools(), options.connectTimeoutMs, `listTools timed out after ${options.connectTimeoutMs}ms`);
+            tools = result.tools;
+        }
+        catch (err) {
+            this.warn(`trellis-mcp-gateway: failed to list tools for MCP server "${name}": ${errorText(err)}`);
+            await this.closeUpstream(client);
+            return;
+        }
+        const { skipped } = this.registry.add(name, client, tools);
+        for (const collided of skipped) {
+            this.warn(`trellis-mcp-gateway: tool "${collided}" from server "${name}" collides with an already-registered tool and was skipped`);
+        }
+    }
+    async listTools() {
+        return this.registry.listTools();
+    }
+    async callTool(name, args) {
+        return this.registry.callTool(name, args);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const pending = [...this.connected];
+        this.connected.clear();
+        await Promise.all(pending.map((client) => this.closeUpstream(client)));
+    }
+    async closeUpstream(client) {
+        this.connected.delete(client);
+        try {
+            await client.close();
+        }
+        catch (err) {
+            // Cleanup is best-effort; one transport must not block the others.
+            this.warn(`trellis-mcp-gateway: failed to close MCP client: ${errorText(err)}`);
+        }
+    }
+}
+/**
+ * Attaches a stored OAuth token, refreshing it first if it has expired.
+ *
+ * Returns the definition unchanged when nothing is stored for this
+ * server: the overwhelmingly common case is a remote server that uses no
+ * OAuth at all, or one whose credential lives in `headers` already, and
+ * neither should be disturbed.
+ *
+ * An explicit `Authorization` header in canonical wins. Someone who wrote
+ * one meant it, and silently overriding it with a stored token would be
+ * the kind of invisible precedence that is impossible to debug.
+ */
+async function withOAuthHeader(name, def, homeDir) {
+    const hasExplicitAuth = Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
+    if (hasExplicitAuth)
+        return def;
+    const token = await ensureFreshToken(homeDir, name);
+    if (!token)
+        return def;
+    return { ...def, headers: { ...(def.headers ?? {}), Authorization: `Bearer ${token.accessToken}` } };
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/lib/mcpConnect.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent-agnostic MCP upstream connection logic, extracted verbatim from
+ * `src/pi-bridge/index.ts` (trellis-mcp-gateway-hosting design.md D3).
+ *
+ * Everything here carries real bug-fix history — the leaked-child-process
+ * -on-timeout fix (trellis-mcp-connect-timeout), the envAliases literal
+ * -placeholder fix (trellis-migrate-env-var-alias) — which is exactly why
+ * it lives in one module rather than being reimplemented for the gateway:
+ * a future fix to either has to land once, not be remembered twice.
+ *
+ * Deliberately free of any consumer's concerns. Nothing here logs, decides
+ * which servers are in scope, or knows what a tool is; callers isolate
+ * failures in whatever way suits them.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpServerDef, SecretsPolicy } from "../core/types.js";
+/** What an MCP upstream is told this client is. Each consumer passes its
+ * own so an upstream's logs name the thing that actually connected. */
+export interface McpClientInfo {
+    name: string;
+    version: string;
+}
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+/**
+ * A hanging server (process alive, protocol response never sent) leaves
+ * `promise` permanently unsettled — indistinguishable from "still
+ * starting up" without a bound. Racing against a timeout converts that
+ * into an ordinary rejection, which every caller here already knows how
+ * to isolate (design.md D1, trellis-mcp-connect-timeout).
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+/**
+ * A timed-out (or otherwise failed) connect attempt must not leak the
+ * transport's own resources — for `StdioClientTransport` specifically,
+ * an unclosed transport means an orphaned child process that outlives
+ * this failed attempt indefinitely (confirmed by a real leaked
+ * subprocess during this change's own test run). `transport.close()` is
+ * best-effort: a transport that never fully connected may itself error
+ * on close, but the original connect failure is what the caller needs
+ * to see, not a secondary cleanup error.
+ */
+export declare function connectWithCleanup(client: Client, transport: Transport, timeoutMs: number, message: string): Promise<Client>;
+export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
+export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
+export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
+export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
+/**
+ * Transport dispatch, matching the original bridge's own ordering: `http`
+ * and `sse` are explicit, everything else (including an absent
+ * `transport`) is stdio — a default the canonical schema relies on.
+ */
+export declare function connectServer(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;