agent-trellis 0.5.2 → 0.6.0

package/dist/commands/onboardVerdict.js

@@ -0,0 +1,175 @@
+/**
+ * Normalizes every chained stage's own report shape into one flat list
+ * (trellis-onboard-closed-loop design.md D5) — the single source both
+ * `runOnboard`'s exit code and the terminal verdict block derive from,
+ * so the two can never disagree the way the five-clause inline boolean
+ * this replaces once could.
+ *
+ * Each normalizer reads its stage's existing report type; none of them
+ * re-implement conflict detection — they translate an already-computed
+ * verdict (a plan item's `action`, a finding being present at all) into
+ * one shared shape. A stage whose report is absent (never ran, e.g. no
+ * migration source) contributes nothing, not an error.
+ */
+function itemMessage(stage, agent, description) {
+    const item = { stage, severity: "blocked", message: description };
+    if (agent)
+        item.agent = agent;
+    return item;
+}
+/** Shared by `sync` and `mcp sync` — `AgentSyncReport` and
+ * `AgentMcpSyncReport` are structurally identical
+ * (`{ agent, present, items: AdapterPlanItem[] }`), so one function
+ * serves both rather than two copies that could drift. */
+function normalizePlanItems(stage, reports) {
+    if (!reports)
+        return [];
+    const items = [];
+    for (const report of reports) {
+        for (const item of report.items) {
+            if (item.action !== "conflict")
+                continue;
+            const verdict = itemMessage(stage, report.agent, item.description);
+            if (item.remediation)
+                verdict.remediation = item.remediation;
+            items.push(verdict);
+        }
+    }
+    return items;
+}
+export function normalizeMigrateVerdict(plan) {
+    if (!plan)
+        return [];
+    const items = [];
+    for (const item of plan.items) {
+        if (item.action !== "conflict")
+            continue;
+        const verdict = { stage: "migrate", severity: "blocked", message: item.detail };
+        if (item.remediation)
+            verdict.remediation = item.remediation;
+        items.push(verdict);
+    }
+    return items;
+}
+export function normalizeSyncVerdict(report) {
+    return normalizePlanItems("sync", report?.reports);
+}
+export function normalizeMcpSyncVerdict(report) {
+    return normalizePlanItems("mcp sync", report?.reports);
+}
+/**
+ * The self-verification re-plan (design.md D2b): a re-plan run
+ * immediately after a real apply, against the state that apply just
+ * wrote. Any remaining `"create"`/`"conflict"` item here means the
+ * write itself did not hold — distinct from, and always `blocked`
+ * regardless of what the original apply reported, because it directly
+ * contradicts this run's own claim of having written it.
+ */
+export function normalizeSelfVerificationVerdict(stage, reports) {
+    if (!reports)
+        return [];
+    const items = [];
+    for (const report of reports) {
+        for (const item of report.items) {
+            if (item.action !== "create" && item.action !== "conflict")
+                continue;
+            items.push({
+                stage: `${stage} (verify)`,
+                severity: "blocked",
+                agent: report.agent,
+                message: `expected to have written "${item.target}" but a re-plan still finds it outstanding: ${item.description}`,
+                remediation: `re-run \`trellis ${stage === "sync" ? "sync" : "mcp sync"}\` and, if this repeats, check for a filesystem permission or symlink problem at ${item.target}`,
+            });
+        }
+    }
+    return items;
+}
+export function normalizeMemorySyncVerdict(result) {
+    if (!result)
+        return [];
+    if (!result.configured) {
+        return [{ stage: "memory sync", severity: "warning", message: result.reason }];
+    }
+    const items = [];
+    for (const item of result.plan.items) {
+        if (item.action !== "conflict")
+            continue;
+        items.push({ stage: "memory sync", severity: "blocked", message: item.detail });
+    }
+    return items;
+}
+export function normalizeSecretsAuditVerdict(report) {
+    if (!report)
+        return [];
+    return report.findings.map((finding) => {
+        const item = { stage: "secrets audit", severity: "blocked", message: `${finding.file}: ${finding.detail}` };
+        if (finding.agent !== "environment")
+            item.agent = finding.agent;
+        return item;
+    });
+}
+/**
+ * A finding naming an agent outside the managed set is a `warning`, not
+ * `blocked` — onboard did not touch that agent, so its drift is not this
+ * run's failure (design.md D3). A finding with no `agent` at all (only
+ * cross-agent `"drift"`, per `src/commands/doctor.ts`'s own findings
+ * construction) is conservatively `blocked`: it inherently spans more
+ * than one agent, and there is no way to prove none of them are managed.
+ */
+/** Any path under `homeDir` prints as `~/…` rather than an absolute
+ * scratch/real path — the run's own `homeDir`, never `homedir()`, so a
+ * test's scratch home abbreviates the same way a real run does. */
+function abbreviate(text, homeDir) {
+    return text.split(homeDir).join("~");
+}
+/**
+ * Always the last thing `printResult` prints, on every run including a
+ * fully clean one — the exact regression this change exists to fix: a
+ * run with a real early-stage conflict must not end on a later stage's
+ * unrelated success line (trellis-onboard-closed-loop spec: "Every run
+ * terminates in a verdict that matches its exit code").
+ */
+export function printVerdict(verdict, homeDir) {
+    const blocked = verdict.filter((item) => item.severity === "blocked");
+    const warnings = verdict.filter((item) => item.severity === "warning");
+    console.log("");
+    console.log("verdict");
+    if (blocked.length === 0 && warnings.length === 0) {
+        console.log("✅ nothing needs attention — every stage completed cleanly and verified");
+        console.log("exit code: 0 — nothing blocked this run");
+        return;
+    }
+    if (blocked.length > 0) {
+        console.log(`❌ ${blocked.length} blocking issue(s):`);
+        for (const item of blocked) {
+            const where = item.agent ? `${item.stage}/${item.agent}` : item.stage;
+            console.log(`   - [${where}] ${abbreviate(item.message, homeDir)}`);
+            if (item.remediation)
+                console.log(`     → ${abbreviate(item.remediation, homeDir)}`);
+        }
+    }
+    if (warnings.length > 0) {
+        console.log(`⚠️  ${warnings.length} warning(s) — did not block this run:`);
+        for (const item of warnings) {
+            const where = item.agent ? `${item.stage}/${item.agent}` : item.stage;
+            console.log(`   - [${where}] ${abbreviate(item.message, homeDir)}`);
+            if (item.remediation)
+                console.log(`     → ${abbreviate(item.remediation, homeDir)}`);
+        }
+    }
+    console.log(blocked.length > 0 ? "exit code: 1 — at least one blocking issue above" : "exit code: 0 — warnings only, nothing blocked this run");
+}
+export function normalizeDoctorVerdict(report, managedAgents) {
+    if (!report)
+        return [];
+    const managed = new Set(managedAgents);
+    return report.findings.map((finding) => {
+        const concernsOnlyUnmanaged = finding.agent !== undefined && !managed.has(finding.agent);
+        const item = { stage: "doctor", severity: concernsOnlyUnmanaged ? "warning" : "blocked", message: finding.message };
+        if (finding.agent)
+            item.agent = finding.agent;
+        if (concernsOnlyUnmanaged)
+            item.remediation = `concerns "${finding.agent}", which this run does not manage — run \`trellis doctor\` directly if you want to look into it`;
+        return item;
+    });
+}

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.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-

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/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>;