@cyanmycelium/mcp-broker 0.2.0 → 0.3.0

package/src/broker/aggregate/aggregate.server.ts

@@ -0,0 +1,178 @@
+import type { IMessageTransport } from "@cyanmycelium/mcp-core";
+import type { InternalClient } from "../../ws.tunnel.js";
+import { AggregateCatalog } from "./aggregate.catalog.js";
+import { ProviderClientSession } from "./provider.client.session.js";
+
+/** MCP protocol version advertised by the aggregate server. */
+const PROTOCOL_VERSION = "2024-11-05";
+
+/** Opens an in-process client to a named provider slot. Supplied by WsTunnel. */
+export type InternalClientFactory = (providerName: string) => InternalClient;
+
+interface ClientMessage {
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+
+interface CallParams {
+    name?: string;
+    arguments?: Record<string, unknown>;
+}
+
+/**
+ * The `_all` aggregate MCP server. Presents the union of every opted-in
+ * provider's tools and prompts as a single MCP server, reachable on the
+ * reserved `_all` slot.
+ *
+ * It implements {@link IMessageTransport} so it can be registered on the
+ * WsTunnel as a loopback provider: `send` receives client requests, `onMessage`
+ * (assigned by the tunnel) carries responses and notifications back to clients.
+ */
+export class AggregateServer implements IMessageTransport {
+    /** Reserved provider slot the aggregate is published on. */
+    static readonly SLOT = "_all";
+
+    private readonly _catalog = new AggregateCatalog();
+    private readonly _sessions = new Map<string, ProviderClientSession>();
+    private readonly _openClient: InternalClientFactory;
+    private _running = false;
+
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    constructor(openClient: InternalClientFactory) {
+        this._openClient = openClient;
+    }
+
+    get isOpen(): boolean {
+        return this._running;
+    }
+
+    /** Number of providers currently in the aggregate. */
+    get providerCount(): number {
+        return this._sessions.size;
+    }
+
+    /** Marks the aggregate transport open. Call before registering it. */
+    start(): void {
+        this._running = true;
+    }
+
+    /** WsTunnel hands a client request for the `_all` slot here. */
+    send(data: string): void {
+        void this._handleClientMessage(data);
+    }
+
+    /** Closes every provider session and the aggregate transport. */
+    close(): void {
+        if (!this._running) return;
+        this._running = false;
+        for (const session of this._sessions.values()) session.close();
+        this._sessions.clear();
+        this.onClose?.();
+    }
+
+    /**
+     * Adds a provider to the aggregate: opens an internal client, runs the
+     * session handshake, and merges the provider's catalog. A no-op for an
+     * already-aggregated provider or the reserved `_all` slot itself.
+     */
+    async addProvider(name: string): Promise<void> {
+        if (name === AggregateServer.SLOT || this._sessions.has(name)) return;
+
+        const session = new ProviderClientSession(name, this._openClient(name));
+        this._sessions.set(name, session);
+
+        session.onCatalogChanged = (): void => {
+            this._catalog.setProvider(name, { tools: session.tools, prompts: session.prompts });
+            this._emitListChanged();
+        };
+        session.onClosed = (): void => this.removeProvider(name);
+
+        try {
+            await session.initialize();
+        } catch {
+            this.removeProvider(name);
+        }
+    }
+
+    /** Removes a provider from the aggregate. */
+    removeProvider(name: string): void {
+        const session = this._sessions.get(name);
+        if (!session) return;
+        this._sessions.delete(name);
+        session.close();
+        this._catalog.removeProvider(name);
+        this._emitListChanged();
+    }
+
+    private async _handleClientMessage(data: string): Promise<void> {
+        let msg: ClientMessage;
+        try {
+            msg = JSON.parse(data) as ClientMessage;
+        } catch {
+            return;
+        }
+        const id = msg.id;
+        if (id == null) return; // client notification — nothing to answer
+
+        switch (msg.method) {
+            case "initialize":
+                this._reply(id, {
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        serverInfo: { name: AggregateServer.SLOT, version: "0" },
+                        capabilities: { tools: { listChanged: true }, prompts: { listChanged: true } },
+                    },
+                });
+                break;
+            case "ping":
+                this._reply(id, { result: {} });
+                break;
+            case "tools/list":
+                this._reply(id, { result: { tools: this._catalog.tools } });
+                break;
+            case "prompts/list":
+                this._reply(id, { result: { prompts: this._catalog.prompts } });
+                break;
+            case "tools/call":
+                await this._route(id, msg.params, "tool");
+                break;
+            case "prompts/get":
+                await this._route(id, msg.params, "prompt");
+                break;
+            default:
+                this._reply(id, { error: { code: -32601, message: `Method not found: ${msg.method ?? "(none)"}` } });
+        }
+    }
+
+    private async _route(id: string | number, params: unknown, kind: "tool" | "prompt"): Promise<void> {
+        const p = (params ?? {}) as CallParams;
+        const route = p.name ? (kind === "tool" ? this._catalog.resolveTool(p.name) : this._catalog.resolvePrompt(p.name)) : undefined;
+        if (!route) {
+            this._reply(id, { error: { code: -32602, message: `Unknown aggregated ${kind}: ${p.name ?? "(none)"}` } });
+            return;
+        }
+        const session = this._sessions.get(route.provider);
+        if (!session) {
+            this._reply(id, { error: { code: -32000, message: `Provider "${route.provider}" is no longer connected` } });
+            return;
+        }
+        const args = p.arguments ?? {};
+        const outcome = kind === "tool" ? await session.callTool(route.original, args) : await session.getPrompt(route.original, args);
+        this._reply(id, outcome.error !== undefined ? { error: outcome.error } : { result: outcome.result });
+    }
+
+    private _reply(id: string | number, body: { result?: unknown; error?: unknown }): void {
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", id, ...body }));
+    }
+
+    private _emitListChanged(): void {
+        if (!this._running) return;
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" }));
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" }));
+    }
+}

package/src/broker/aggregate/provider.client.session.ts

@@ -0,0 +1,172 @@
+import type { InternalClient } from "../../ws.tunnel.js";
+import type { CatalogTool, CatalogPrompt } from "./aggregate.catalog.js";
+
+/** MCP protocol version the aggregate sessions negotiate with sub-providers. */
+const PROTOCOL_VERSION = "2024-11-05";
+
+/** Per-request timeout for sub-provider calls. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** Outcome of a JSON-RPC request: exactly one of `result` / `error` is set. */
+interface RpcOutcome {
+    result?: unknown;
+    error?: unknown;
+}
+
+interface PendingRequest {
+    resolve: (outcome: RpcOutcome) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+
+interface IncomingMessage {
+    id?: string | number | null;
+    method?: string;
+    result?: unknown;
+    error?: unknown;
+}
+
+/**
+ * A hand-rolled JSON-RPC client session to one aggregated provider, running
+ * over an in-process {@link InternalClient}.
+ *
+ * Performs the MCP `initialize` handshake, caches the provider's `tools/list`
+ * and `prompts/list`, and re-fetches them when the provider emits a
+ * `list_changed` notification. `tools/call` and `prompts/get` are forwarded and
+ * their raw result or error relayed back unchanged.
+ */
+export class ProviderClientSession {
+    readonly provider: string;
+
+    private readonly _client: InternalClient;
+    private readonly _idPrefix: string;
+    private readonly _pending = new Map<string, PendingRequest>();
+    private _nextId = 0;
+    private _tools: CatalogTool[] = [];
+    private _prompts: CatalogPrompt[] = [];
+    private _closed = false;
+
+    /** Fires after the cached catalog changes (initial load or `list_changed`). */
+    onCatalogChanged: (() => void) | null = null;
+
+    /** Fires when the underlying provider slot disconnects. */
+    onClosed: (() => void) | null = null;
+
+    constructor(provider: string, client: InternalClient) {
+        this.provider = provider;
+        this._client = client;
+        this._idPrefix = `agg-${provider}-`;
+        client.onMessage = (data: string): void => this._handleMessage(data);
+        client.onClose = (): void => {
+            if (this._closed) return;
+            this._rejectAll("provider disconnected");
+            this.onClosed?.();
+        };
+    }
+
+    get tools(): CatalogTool[] {
+        return this._tools;
+    }
+
+    get prompts(): CatalogPrompt[] {
+        return this._prompts;
+    }
+
+    /** Runs the `initialize` handshake and the first catalog fetch. */
+    async initialize(): Promise<void> {
+        await this._request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "mcp-broker-aggregate", version: "0" },
+        });
+        this._client.send(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+        await this._refresh();
+    }
+
+    /** Forwards a `tools/call` to the provider, relaying the raw outcome. */
+    callTool(name: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+        return this._request("tools/call", { name, arguments: args });
+    }
+
+    /** Forwards a `prompts/get` to the provider, relaying the raw outcome. */
+    getPrompt(name: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+        return this._request("prompts/get", { name, arguments: args });
+    }
+
+    /** Detaches the session and its internal client. */
+    close(): void {
+        if (this._closed) return;
+        this._closed = true;
+        this._rejectAll("session closed");
+        this._client.close();
+    }
+
+    private async _refresh(): Promise<void> {
+        this._tools = await this._listAll<CatalogTool>("tools/list", "tools");
+        this._prompts = await this._listAll<CatalogPrompt>("prompts/list", "prompts");
+        this.onCatalogChanged?.();
+    }
+
+    /**
+     * Calls a list method, following `nextCursor` pagination. A provider that
+     * does not implement the primitive answers with an error, which is treated
+     * as an empty list.
+     */
+    private async _listAll<T>(method: string, key: string): Promise<T[]> {
+        const items: T[] = [];
+        let cursor: string | undefined;
+        do {
+            const { result, error } = await this._request(method, cursor ? { cursor } : {});
+            if (error) return [];
+            const page = (result ?? {}) as Record<string, unknown>;
+            const list = page[key];
+            if (Array.isArray(list)) items.push(...(list as T[]));
+            cursor = typeof page.nextCursor === "string" ? page.nextCursor : undefined;
+        } while (cursor);
+        return items;
+    }
+
+    private _request(method: string, params: unknown): Promise<RpcOutcome> {
+        return new Promise<RpcOutcome>((resolve) => {
+            if (this._closed) {
+                resolve({ error: { code: -32000, message: "session closed" } });
+                return;
+            }
+            const id = this._idPrefix + String(++this._nextId);
+            const timer = setTimeout(() => {
+                this._pending.delete(id);
+                resolve({ error: { code: -32000, message: `request "${method}" timed out` } });
+            }, REQUEST_TIMEOUT_MS);
+            this._pending.set(id, { resolve, timer });
+            this._client.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+        });
+    }
+
+    private _handleMessage(data: string): void {
+        let msg: IncomingMessage;
+        try {
+            msg = JSON.parse(data) as IncomingMessage;
+        } catch {
+            return;
+        }
+        if (typeof msg.id === "string") {
+            const pending = this._pending.get(msg.id);
+            if (pending) {
+                this._pending.delete(msg.id);
+                clearTimeout(pending.timer);
+                pending.resolve({ result: msg.result, error: msg.error });
+            }
+            return;
+        }
+        if (msg.id == null && (msg.method === "notifications/tools/list_changed" || msg.method === "notifications/prompts/list_changed")) {
+            void this._refresh();
+        }
+    }
+
+    private _rejectAll(reason: string): void {
+        for (const pending of this._pending.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve({ error: { code: -32000, message: reason } });
+        }
+        this._pending.clear();
+    }
+}

package/src/broker/broker.server.ts

@@ -81,7 +81,18 @@ export async function startBrokerServer(
 
     const [serverEnd, clientEnd] = LoopbackTransport.createPair();
 
-    const builder = new McpServerBuilder().withName(BROKER_PROVIDER_NAME).withTransport(serverEnd).register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
+    // Without an initializer, McpServerBuilder reports `version: "0.0.0"` in the
+    // `initialize` handshake. Supply the real package version from the context.
+    const builder = new McpServerBuilder()
+        .withName(BROKER_PROVIDER_NAME)
+        .withTransport(serverEnd)
+        .withInitializer({
+            initialize: () => ({
+                protocolVersion: "2024-11-05",
+                serverInfo: { name: BROKER_PROVIDER_NAME, version: context.version },
+            }),
+        })
+        .register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
 
     // Discover every grammar by scanning two directories:
     //   1. The packaged grammars shipped with the broker.

package/src/config.ts

@@ -73,6 +73,43 @@ export interface BrokerConfig {
         command: string;
         args?: string[];
         env?: Record<string, string>;
+        /** When `true`, the upstream joins the `_all` aggregate slot once connected. */
+        aggregate?: boolean;
+    }>;
+
+    /**
+     * Remote MCP servers the broker connects out to and exposes as provider
+     * slots. Each entry is reached by URL (Streamable HTTP / SSE / WebSocket);
+     * local servers should be shipped as `.mcpb` bundles instead.
+     */
+    mcpServers?: Array<{
+        name: string;
+        url: string;
+        transport?: "streamable-http" | "sse" | "websocket";
+        headers?: Record<string, string>;
+        /** Defaults to `true`; set to `false` to exclude this upstream from the `_all` aggregate slot. */
+        aggregate?: boolean;
+    }>;
+
+    /**
+     * Local `.mcpb` bundles the broker loads at startup and runs as stdio
+     * provider slots. A bundle is a ZIP with a `manifest.json`; the broker
+     * verifies a detached signature against a trusted public key before
+     * unpacking and spawning it.
+     */
+    mcpbBundles?: Array<{
+        /** Provider slot name the bundle is bound to. */
+        name: string;
+        /** Path to the `.mcpb` file (resolved against the config file's directory). */
+        path: string;
+        /** Path to the trusted public key (PEM) used to verify the detached signature. */
+        publicKey: string;
+        /** Path to the detached signature file. Defaults to `<path>.sig`. */
+        signature?: string;
+        /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+        userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+        /** Defaults to `true`; set to `false` to exclude this bundle from the `_all` aggregate slot. */
+        aggregate?: boolean;
     }>;
 }
 

package/src/index.ts

@@ -3,6 +3,14 @@ export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
 export type { WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
 export { StdioUpstream } from "./stdio.upstream.js";
 export type { StdioUpstreamConfig } from "./stdio.upstream.js";
+export { RemoteUpstream } from "./remote.upstream.js";
+export type { RemoteUpstreamConfig } from "./remote.upstream.js";
+export type { Upstream } from "./upstream.js";
+
+// `.mcpb` bundle loading — verifies + unpacks a bundle into a stdio upstream.
+export { loadMcpbBundle } from "./mcpb.loader.js";
+export type { McpbBundleConfig } from "./mcpb.loader.js";
+export { unzipMcpb } from "./mcpb.unzip.js";
 
 // Broker introspection — tier 1.
 export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";

package/src/mcpb.loader.ts

@@ -0,0 +1,186 @@
+/**
+ * Loads a local `.mcpb` bundle into a {@link StdioUpstreamConfig}.
+ *
+ * A `.mcpb` bundle is a ZIP holding a `manifest.json` whose `server.mcp_config`
+ * describes a stdio MCP server process. The broker:
+ *
+ * 1. verifies a **detached signature** of the `.mcpb` file against a trusted
+ *    public key (PEM) — integrity *and* provenance, using `node:crypto` only;
+ * 2. unpacks the archive;
+ * 3. reads the manifest, expands the `mcp_config` placeholders, and produces a
+ *    `StdioUpstreamConfig` that the existing upstream wiring spawns.
+ *
+ * The broker stays compatible with the `.mcpb` format without depending on the
+ * `@anthropic-ai/mcpb` package: the bundle's *own* (native PKCS#7) signature is
+ * never parsed — the detached signature layer is the broker's trust anchor.
+ *
+ * Any failure (missing files, bad signature, malformed manifest, missing
+ * `user_config` value) is logged and yields `null`: the bundle is refused and
+ * no process is ever spawned. Never auto-runs an unverified bundle.
+ */
+import { createPublicKey, verify, X509Certificate, type KeyObject } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { unzipMcpb } from "./mcpb.unzip.js";
+import type { StdioUpstreamConfig } from "./stdio.upstream.js";
+
+/** A `.mcpb` bundle entry from the broker config file. */
+export interface McpbBundleConfig {
+    /** Provider slot name the bundle is bound to. */
+    name: string;
+    /** Path to the `.mcpb` file. */
+    path: string;
+    /** Path to the trusted public key (PEM) verifying the detached signature. */
+    publicKey: string;
+    /** Path to the detached signature file. Defaults to `<path>.sig`. */
+    signature?: string;
+    /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+    userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+    /** When `false`, the bundle stays out of the `_all` aggregate slot. Defaults to `true`. */
+    aggregate?: boolean;
+}
+
+interface McpConfig {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    platform_overrides?: Record<string, { command?: string; args?: string[]; env?: Record<string, string> }>;
+}
+
+/** Loads a PEM that holds either an X.509 certificate or a bare public key. */
+function loadPublicKey(pem: string): KeyObject {
+    if (pem.includes("BEGIN CERTIFICATE")) {
+        return new X509Certificate(pem).publicKey;
+    }
+    return createPublicKey(pem);
+}
+
+/** Verifies the detached `signature` of `data` against `publicKey`. */
+function verifyDetachedSignature(data: Buffer, signature: Buffer, publicKey: KeyObject): boolean {
+    // Ed25519/Ed448 are used without a separate hash algorithm; RSA/EC need one.
+    const keyType = publicKey.asymmetricKeyType;
+    const algorithm = keyType === "ed25519" || keyType === "ed448" ? null : "sha256";
+    return verify(algorithm, data, publicKey, signature);
+}
+
+/** Resolves a single `${...}` placeholder key, or `undefined` when unknown. */
+function resolvePlaceholder(key: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string | number | boolean | Array<string | number> | undefined {
+    if (key === "__dirname") return dirname;
+    if (key === "HOME") return homedir();
+    if (key === "DESKTOP") return join(homedir(), "Desktop");
+    if (key === "DOCUMENTS") return join(homedir(), "Documents");
+    if (key === "DOWNLOADS") return join(homedir(), "Downloads");
+    if (key === "pathSeparator" || key === "/") return sep;
+    if (key.startsWith("user_config.")) {
+        const name = key.slice("user_config.".length);
+        const value = userConfig?.[name];
+        if (value === undefined) throw new Error(`missing user_config value: "${name}"`);
+        return value;
+    }
+    return undefined;
+}
+
+/** Expands placeholders in a scalar string (command, env value). */
+function expandScalar(input: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string {
+    return input.replace(/\$\{([^}]+)\}/g, (match, key: string) => {
+        const value = resolvePlaceholder(key, dirname, userConfig);
+        if (value === undefined) return match; // unknown placeholder — leave verbatim
+        if (Array.isArray(value)) throw new Error(`placeholder "\${${key}}" is multi-valued and cannot be used here`);
+        return String(value);
+    });
+}
+
+/** Expands one manifest argument; a standalone multi-valued placeholder spreads. */
+function expandArg(arg: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string[] {
+    const standalone = /^\$\{(user_config\.[^}]+)\}$/.exec(arg);
+    if (standalone) {
+        const value = resolvePlaceholder(standalone[1], dirname, userConfig);
+        if (Array.isArray(value)) return value.map(String);
+        return [String(value)];
+    }
+    return [expandScalar(arg, dirname, userConfig)];
+}
+
+/**
+ * Verifies, unpacks and resolves a `.mcpb` bundle into a `StdioUpstreamConfig`.
+ *
+ * @param cfg      The bundle entry from the broker config.
+ * @param baseDir  Directory the bundle paths are resolved against.
+ * @returns        A ready upstream config, or `null` when the bundle is refused.
+ */
+export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Promise<StdioUpstreamConfig | null> {
+    const tag = `[mcp-broker] mcpb bundle "${cfg.name}"`;
+    try {
+        const mcpbPath = resolve(baseDir, cfg.path);
+        const publicKeyPath = resolve(baseDir, cfg.publicKey);
+        const signaturePath = cfg.signature ? resolve(baseDir, cfg.signature) : `${mcpbPath}.sig`;
+
+        for (const [label, file] of [
+            ["bundle", mcpbPath],
+            ["public key", publicKeyPath],
+            ["signature", signaturePath],
+        ] as const) {
+            if (!existsSync(file)) {
+                console.error(`${tag}: ${label} file not found at ${file} — bundle refused.`);
+                return null;
+            }
+        }
+
+        // ── Signature verification (mandatory) ──────────────────────────────
+        const bundleBytes = readFileSync(mcpbPath);
+        const signatureBytes = readFileSync(signaturePath);
+        const publicKey = loadPublicKey(readFileSync(publicKeyPath, "utf8"));
+        if (!verifyDetachedSignature(bundleBytes, signatureBytes, publicKey)) {
+            console.error(`${tag}: detached signature is invalid for the configured public key — bundle refused.`);
+            return null;
+        }
+
+        // ── Unpack ──────────────────────────────────────────────────────────
+        const outputDir = resolve(baseDir, ".cache", "mcpb", cfg.name);
+        rmSync(outputDir, { recursive: true, force: true });
+        unzipMcpb(mcpbPath, outputDir);
+
+        // ── Manifest → mcp_config ───────────────────────────────────────────
+        const manifestPath = join(outputDir, "manifest.json");
+        if (!existsSync(manifestPath)) {
+            console.error(`${tag}: manifest.json missing inside the bundle — bundle refused.`);
+            return null;
+        }
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { server?: { mcp_config?: McpConfig } };
+        const mcpConfig = manifest.server?.mcp_config;
+        if (!mcpConfig) {
+            console.error(`${tag}: manifest has no server.mcp_config — bundle refused.`);
+            return null;
+        }
+
+        // Platform-specific overrides replace the base fields when present.
+        const override = mcpConfig.platform_overrides?.[process.platform];
+        const command = override?.command ?? mcpConfig.command;
+        const rawArgs = override?.args ?? mcpConfig.args ?? [];
+        const rawEnv = { ...mcpConfig.env, ...override?.env };
+        if (!command) {
+            console.error(`${tag}: manifest mcp_config has no command — bundle refused.`);
+            return null;
+        }
+
+        // ── Placeholder expansion ───────────────────────────────────────────
+        const expandedCommand = expandScalar(command, outputDir, cfg.userConfig);
+        const expandedArgs = rawArgs.flatMap((arg) => expandArg(arg, outputDir, cfg.userConfig));
+        const expandedEnv: Record<string, string> = {};
+        for (const [key, value] of Object.entries(rawEnv)) {
+            expandedEnv[key] = expandScalar(value, outputDir, cfg.userConfig);
+        }
+
+        return {
+            name: cfg.name,
+            command: expandedCommand,
+            args: expandedArgs,
+            env: Object.keys(expandedEnv).length > 0 ? expandedEnv : undefined,
+            aggregate: cfg.aggregate ?? true,
+        };
+    } catch (err) {
+        console.error(`${tag}: ${(err as Error).message} — bundle refused.`);
+        return null;
+    }
+}