agent-trellis 0.4.0 → 0.6.0

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

package/dist/lib/mcpConnect.js

@@ -0,0 +1,123 @@
+/**
+ * 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 { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { resolveSecretEnv } from "./secretEnv.js";
+import { extractTemplateVarNames } from "./envVarNames.js";
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * 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 function withTimeout(promise, timeoutMs, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * 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 async function connectWithCleanup(client, transport, timeoutMs, message) {
+    try {
+        await withTimeout(client.connect(transport), timeoutMs, message);
+        return client;
+    }
+    catch (err) {
+        try {
+            await transport.close();
+        }
+        catch {
+            // best-effort; the original connect failure is what matters
+        }
+        throw err;
+    }
+}
+export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
+    const client = new Client(clientInfo, { capabilities: {} });
+    const envAliases = def.envAliases ?? {};
+    // `envAliases`' values are source variable names — resolved through the
+    // exact same call as `env`'s own names, never delivered as the raw
+    // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
+    // of its own (like this bridge) would otherwise crash on parsing
+    // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
+    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
+    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
+    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
+    const transport = new StdioClientTransport({
+        command: def.command,
+        args: def.args,
+        // staticEnv merges last: a literal, intentionally-plain value (an
+        // email, an environment tag) always wins over an unresolved name-only
+        // entry's empty-string fallback for the same key — though in practice
+        // resolveMcpPlan's D6 refusal never lets an unresolved name reach
+        // this point at all (trellis-mcp-static-env-and-disabled-servers).
+        env: { ...getDefaultEnvironment(), ...namedEnv, ...aliasEnv, ...(def.staticEnv ?? {}) },
+    });
+    return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+export function resolveHeaders(def, secretsPolicy) {
+    if (!def.headers || Object.keys(def.headers).length === 0)
+        return undefined;
+    const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
+    const resolved = resolveSecretEnv(names, secretsPolicy);
+    const result = {};
+    for (const [key, template] of Object.entries(def.headers)) {
+        result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
+    }
+    return result;
+}
+export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo) {
+    const client = new Client(clientInfo, { capabilities: {} });
+    const headers = resolveHeaders(def, secretsPolicy);
+    const opts = headers ? { requestInit: { headers } } : undefined;
+    return connectWithCleanup(client, new StreamableHTTPClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo) {
+    const client = new Client(clientInfo, { capabilities: {} });
+    const headers = resolveHeaders(def, secretsPolicy);
+    const opts = headers ? { requestInit: { headers } } : undefined;
+    return connectWithCleanup(client, new SSEClientTransport(new URL(def.url), opts), timeoutMs, `connect timed out after ${timeoutMs}ms`);
+}
+/**
+ * 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 function connectServer(def, secretsPolicy, timeoutMs, clientInfo) {
+    if (def.transport === "http")
+        return connectHttp(def, secretsPolicy, timeoutMs, clientInfo);
+    if (def.transport === "sse")
+        return connectSse(def, secretsPolicy, timeoutMs, clientInfo);
+    return connectStdio(def, secretsPolicy, timeoutMs, clientInfo);
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -23,6 +23,18 @@ export interface McpMigrateReadResult {
     entries: McpMigrateEntry[];
     unsupported: McpMigrateUnsupported[];
 }
+/**
+ * Inverse of `splitJsonEnvMap`: the resolved literal/reference text every
+ * env-classification key would produce on disk, regardless of which of
+ * `env`/`envAliases`/`staticEnv` it's currently filed under — a self-
+ * referencing `env` name and a differently-named `envAliases` entry
+ * both resolve to a `${...}` placeholder, a `staticEnv` entry resolves
+ * to its own literal text as-is. Shared by `renderJsonServerEntry` (the
+ * JSON write path) and migrate's own safe-reclassification check
+ * (`trellis-migrate-reclassify-repair`) — the same mechanism, not two
+ * independent derivations of it.
+ */
+export declare function resolvedEnvTextMap(def: Pick<McpServerDef, "env" | "envAliases" | "staticEnv">): Record<string, string>;
 export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
 export interface CodexMcpEntryRich {

package/dist/lib/mcpMigrateRead.js

@@ -17,25 +17,47 @@ import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
 const EMPTY_RESULT = { entries: [], unsupported: [] };
 /**
- * Trellis's own `env` (name-only reference) vs. `staticEnv` (literal
- * value) split lives in one JSON object on disk (`jsonMcp.ts`'s
- * `renderJsonServerEntry`) — a value is a "name" entry only when it's
- * exactly `${KEY}` referencing its OWN key, matching exactly what that
- * renderer ever produces; anything else (a literal value, or a `${...}`
- * referencing a *different* name) is treated as a literal `staticEnv`
- * value instead of guessed at.
+ * Trellis's own `env` (self-referencing name) vs. `envAliases`
+ * (differently-named reference) vs. `staticEnv` (literal value) split
+ * lives in one JSON object on disk (`jsonMcp.ts`'s
+ * `renderJsonServerEntry`) — any value matching exactly `${NAME}` is a
+ * reference needing resolution, regardless of whether `NAME` equals its
+ * own key (trellis-migrate-env-var-alias; previously only the
+ * same-name case was recognized, silently shipping a differently-named
+ * reference as an unresolved literal). Anything not shaped like
+ * `${NAME}` at all remains a literal `staticEnv` value.
  */
-const SELF_VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * Inverse of `splitJsonEnvMap`: the resolved literal/reference text every
+ * env-classification key would produce on disk, regardless of which of
+ * `env`/`envAliases`/`staticEnv` it's currently filed under — a self-
+ * referencing `env` name and a differently-named `envAliases` entry
+ * both resolve to a `${...}` placeholder, a `staticEnv` entry resolves
+ * to its own literal text as-is. Shared by `renderJsonServerEntry` (the
+ * JSON write path) and migrate's own safe-reclassification check
+ * (`trellis-migrate-reclassify-repair`) — the same mechanism, not two
+ * independent derivations of it.
+ */
+export function resolvedEnvTextMap(def) {
+    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
+    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]));
+    return { ...nameRefs, ...aliasRefs, ...(def.staticEnv ?? {}) };
+}
 function splitJsonEnvMap(env) {
     if (!env)
         return {};
     const names = [];
+    const aliases = {};
     const literal = {};
     for (const [key, value] of Object.entries(env)) {
-        const match = SELF_VAR_REF_RE.exec(value);
+        const match = VAR_REF_RE.exec(value);
         if (match && match[1] === key) {
             names.push(key);
         }
+        else if (match) {
+            aliases[key] = match[1];
+        }
         else {
             literal[key] = value;
         }
@@ -43,6 +65,8 @@ function splitJsonEnvMap(env) {
     const result = {};
     if (names.length > 0)
         result.env = names;
+    if (Object.keys(aliases).length > 0)
+        result.envAliases = aliases;
     if (Object.keys(literal).length > 0)
         result.staticEnv = literal;
     return result;
@@ -115,9 +139,20 @@ export function buildCodexMcpReadResult(mcpEntries, tomlContent) {
         if (entry.transport.env_vars && entry.transport.env_vars.length > 0)
             def.env = entry.transport.env_vars;
         if (tomlContent) {
-            const staticEnv = readServerEnvTable(tomlContent, entry.name);
-            if (staticEnv && Object.keys(staticEnv).length > 0)
-                def.staticEnv = staticEnv;
+            const envTable = readServerEnvTable(tomlContent, entry.name);
+            if (envTable && Object.keys(envTable).length > 0) {
+                // Same `${NAME}`-reference-vs-literal classification as the
+                // JSON-source path (trellis-migrate-env-var-alias D2) — Codex's
+                // `[mcp_servers.<name>.env]` table can hold either, same as
+                // Claude Code/Kiro's `env` object can.
+                const classified = splitJsonEnvMap(envTable);
+                if (classified.env)
+                    def.env = [...(def.env ?? []), ...classified.env];
+                if (classified.envAliases)
+                    def.envAliases = classified.envAliases;
+                if (classified.staticEnv)
+                    def.staticEnv = classified.staticEnv;
+            }
         }
         entries.push({ name: entry.name, def });
     }

package/dist/lib/mcpToolRegistry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Aggregation of many upstream MCP servers' tools into one flat namespace,
+ * and routing a call on that namespace back to the exact upstream that
+ * owns it (trellis-mcp-gateway-hosting spec: tool prefix/routing).
+ *
+ * Agent-agnostic by construction: this module knows nothing about pi's
+ * `registerTool`, about MCP's `Server`, or about which servers were in
+ * scope. It is handed already-connected upstreams and answers two
+ * questions — what tools exist, and who owns a given one.
+ *
+ * Upstreams are held behind the structural `ToolUpstream` interface rather
+ * than the SDK's concrete `Client` so that a test fake, and later a
+ * forwarding client to a shared gateway service, both fit without this
+ * module changing (design.md D11).
+ */
+/** The subset of an MCP client this registry actually uses. */
+export interface ToolUpstream {
+    listTools(): Promise<{
+        tools: UpstreamTool[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/** An upstream tool as reported by `tools/list`, narrowed to the fields
+ * aggregation touches. Anything else an upstream sends is carried through
+ * untouched — see `AggregatedTool`. */
+export interface UpstreamTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    [key: string]: unknown;
+}
+export type AggregatedTool = UpstreamTool;
+/**
+ * `${serverName}__${toolName}`, the separator every consumer of this
+ * registry shares. Two underscores rather than one because single
+ * underscores are common inside real tool names, and because pi's bridge
+ * already established this exact shape (pi-mcp-bridge design.md D5) — the
+ * gateway matching it keeps one naming convention across both consumers.
+ */
+export declare const TOOL_NAME_SEPARATOR = "__";
+export declare function prefixedToolName(serverName: string, toolName: string): string;
+export interface AddResult {
+    /** Prefixed names actually registered by this call. */
+    added: string[];
+    /**
+     * Prefixed names refused because an earlier server already owns them.
+     * Reachable when a server name itself contains the separator: server
+     * `a`'s tool `b__c` and server `a__b`'s tool `c` both want `a__b__c`.
+     * First registration wins — silently overwriting would silently
+     * re-route an already-advertised tool to a different server, which is
+     * precisely the mis-routing this registry exists to prevent.
+     */
+    skipped: string[];
+}
+export declare class McpToolRegistry {
+    private readonly entries;
+    private readonly order;
+    /**
+     * Register one connected upstream's tools. Callers add each upstream
+     * independently, so an upstream that failed to connect or to list its
+     * tools is simply never added — every other upstream's tools remain
+     * aggregated, with no special-casing here.
+     */
+    add(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
+    /** Every registered tool, under its prefixed name, in registration
+     * order. Each tool's own `description`/`inputSchema` and any additional
+     * fields the upstream sent are preserved verbatim; only `name` changes. */
+    listTools(): AggregatedTool[];
+    /** The owning upstream and original tool name for a prefixed name, or
+     * `undefined` if nothing owns it. */
+    resolve(prefixedName: string): {
+        serverName: string;
+        toolName: string;
+        upstream: ToolUpstream;
+    } | undefined;
+    /**
+     * Route a call to the owning upstream, unprefixing the name on the way
+     * out — an upstream knows its tool only by its own name, never by the
+     * aggregated one. A name no upstream owns throws rather than guessing.
+     */
+    callTool(prefixedName: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Distinct server names with at least one registered tool, in
+     * registration order. */
+    servers(): string[];
+    get size(): number;
+}