agent-trellis 0.5.2 → 0.6.0

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

package/dist/lib/mcpToolRegistry.js

@@ -0,0 +1,94 @@
+/**
+ * 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).
+ */
+/**
+ * `${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 const TOOL_NAME_SEPARATOR = "__";
+export function prefixedToolName(serverName, toolName) {
+    return `${serverName}${TOOL_NAME_SEPARATOR}${toolName}`;
+}
+export class McpToolRegistry {
+    entries = new Map();
+    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, upstream, tools) {
+        const added = [];
+        const skipped = [];
+        for (const tool of tools) {
+            const name = prefixedToolName(serverName, tool.name);
+            if (this.entries.has(name)) {
+                skipped.push(name);
+                continue;
+            }
+            this.entries.set(name, { serverName, toolName: tool.name, upstream, tool });
+            this.order.push(name);
+            added.push(name);
+        }
+        return { added, skipped };
+    }
+    /** 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() {
+        return this.order.map((name) => {
+            const entry = this.entries.get(name);
+            return { ...entry.tool, name };
+        });
+    }
+    /** The owning upstream and original tool name for a prefixed name, or
+     * `undefined` if nothing owns it. */
+    resolve(prefixedName) {
+        const entry = this.entries.get(prefixedName);
+        if (!entry)
+            return undefined;
+        return { serverName: entry.serverName, toolName: entry.toolName, upstream: entry.upstream };
+    }
+    /**
+     * 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.
+     */
+    async callTool(prefixedName, args) {
+        const target = this.resolve(prefixedName);
+        if (!target) {
+            throw new Error(`unknown tool "${prefixedName}"`);
+        }
+        return target.upstream.callTool({ name: target.toolName, arguments: args });
+    }
+    /** Distinct server names with at least one registered tool, in
+     * registration order. */
+    servers() {
+        const seen = [];
+        for (const name of this.order) {
+            const { serverName } = this.entries.get(name);
+            if (!seen.includes(serverName))
+                seen.push(serverName);
+        }
+        return seen;
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/dist/lib/oauth/discovery.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Authorization server metadata discovery (RFC 8414 / RFC 9728), with
+ * the fallback ladder real MCP servers actually need.
+ *
+ * There is no single well-known path that works everywhere. The MCP
+ * ecosystem has three shapes in the wild, and this walks them in the
+ * order that gets the most specific answer first:
+ *
+ *   1. RFC 9728 protected-resource metadata, which points at whichever
+ *      authorization server actually guards this resource — the only
+ *      strategy that is correct when the resource and the AS are
+ *      different origins.
+ *   2. RFC 8414 path-aware AS metadata, for a server mounted under a
+ *      path (`/mcp`) whose AS metadata lives beside it rather than at
+ *      the origin root.
+ *   3. RFC 8414 root AS metadata, and then OpenID Connect discovery,
+ *      which many providers serve instead.
+ *
+ * A `WWW-Authenticate` header naming `resource_metadata` short-circuits
+ * all of it — that is the server telling us directly where to look, and
+ * is preferred over guessing when present.
+ */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string;
+    scopesSupported?: string[];
+    codeChallengeMethodsSupported?: string[];
+}
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+/** RFC 9728: `WWW-Authenticate: Bearer resource_metadata="https://..."` */
+export declare function parseResourceMetadataUrl(header: string | null): string | undefined;
+export interface DiscoverOptions {
+    fetchImpl?: FetchLike;
+    /** A `WWW-Authenticate` value already seen on a 401 from the resource,
+     * if the caller happens to have one — skips straight to the address it
+     * names instead of probing. */
+    wwwAuthenticate?: string | null;
+}
+export declare function discoverAuthorizationServer(resourceUrl: string, opts?: DiscoverOptions): Promise<AuthorizationServerMetadata | undefined>;

package/dist/lib/oauth/discovery.js

@@ -0,0 +1,95 @@
+/**
+ * Authorization server metadata discovery (RFC 8414 / RFC 9728), with
+ * the fallback ladder real MCP servers actually need.
+ *
+ * There is no single well-known path that works everywhere. The MCP
+ * ecosystem has three shapes in the wild, and this walks them in the
+ * order that gets the most specific answer first:
+ *
+ *   1. RFC 9728 protected-resource metadata, which points at whichever
+ *      authorization server actually guards this resource — the only
+ *      strategy that is correct when the resource and the AS are
+ *      different origins.
+ *   2. RFC 8414 path-aware AS metadata, for a server mounted under a
+ *      path (`/mcp`) whose AS metadata lives beside it rather than at
+ *      the origin root.
+ *   3. RFC 8414 root AS metadata, and then OpenID Connect discovery,
+ *      which many providers serve instead.
+ *
+ * A `WWW-Authenticate` header naming `resource_metadata` short-circuits
+ * all of it — that is the server telling us directly where to look, and
+ * is preferred over guessing when present.
+ */
+function toMetadata(raw) {
+    // An AS is only usable if it says where to send the user and where to
+    // redeem the code. A partial document is treated as no document rather
+    // than being papered over with a guessed endpoint.
+    if (!raw.issuer || !raw.authorization_endpoint || !raw.token_endpoint)
+        return undefined;
+    const out = {
+        issuer: raw.issuer,
+        authorizationEndpoint: raw.authorization_endpoint,
+        tokenEndpoint: raw.token_endpoint,
+    };
+    if (raw.registration_endpoint)
+        out.registrationEndpoint = raw.registration_endpoint;
+    if (raw.scopes_supported)
+        out.scopesSupported = raw.scopes_supported;
+    if (raw.code_challenge_methods_supported)
+        out.codeChallengeMethodsSupported = raw.code_challenge_methods_supported;
+    return out;
+}
+async function tryJson(fetchImpl, url) {
+    try {
+        const response = await fetchImpl(url);
+        if (!response.ok)
+            return undefined;
+        return await response.json();
+    }
+    catch {
+        // A discovery probe failing is ordinary — most of these URLs are
+        // expected to 404 on any given server. Only the last one failing
+        // matters, and the caller reports that.
+        return undefined;
+    }
+}
+/** `https://host/mcp/v1` → `https://host/.well-known/<suffix>/mcp/v1`,
+ * the path-aware form RFC 8414 §3.1 specifies (the well-known segment is
+ * inserted after the host, not appended to the path). */
+function wellKnownUrls(resourceUrl, suffix) {
+    const url = new URL(resourceUrl);
+    const path = url.pathname.replace(/\/+$/, "");
+    const root = `${url.origin}/.well-known/${suffix}`;
+    return path && path !== "" ? [`${url.origin}/.well-known/${suffix}${path}`, root] : [root];
+}
+/** RFC 9728: `WWW-Authenticate: Bearer resource_metadata="https://..."` */
+export function parseResourceMetadataUrl(header) {
+    if (!header)
+        return undefined;
+    const match = /resource_metadata\s*=\s*"([^"]+)"/i.exec(header);
+    return match?.[1];
+}
+export async function discoverAuthorizationServer(resourceUrl, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const candidates = [];
+    const advertised = parseResourceMetadataUrl(opts.wwwAuthenticate ?? null);
+    const resourceMetadataUrls = advertised ? [advertised] : wellKnownUrls(resourceUrl, "oauth-protected-resource");
+    for (const url of resourceMetadataUrls) {
+        const resource = (await tryJson(fetchImpl, url));
+        for (const issuer of resource?.authorization_servers ?? []) {
+            // An issuer identifier is not itself a metadata document; its
+            // metadata lives at the well-known path derived from it.
+            candidates.push(...wellKnownUrls(issuer, "oauth-authorization-server"));
+            candidates.push(...wellKnownUrls(issuer, "openid-configuration"));
+        }
+    }
+    candidates.push(...wellKnownUrls(resourceUrl, "oauth-authorization-server"));
+    candidates.push(...wellKnownUrls(resourceUrl, "openid-configuration"));
+    for (const url of candidates) {
+        const raw = (await tryJson(fetchImpl, url));
+        const metadata = raw ? toMetadata(raw) : undefined;
+        if (metadata)
+            return metadata;
+    }
+    return undefined;
+}

package/dist/lib/oauth/flow.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The interactive half: dynamic client registration (RFC 7591) plus the
+ * authorization-code grant with PKCE (RFC 6749 §4.1, RFC 7636).
+ *
+ * Only ever reached from `trellis mcp auth`, run by a human. The gateway
+ * must never call into this file: it is spawned silently by an agent,
+ * typically with no terminal and no display, so it can neither show a
+ * browser nor wait for one (design.md D9).
+ */
+import type { AuthorizationServerMetadata, FetchLike } from "./discovery.js";
+import type { StoredToken } from "./store.js";
+export declare class AuthorizationError extends Error {
+}
+export interface AuthorizeOptions {
+    fetchImpl?: FetchLike;
+    now?: () => number;
+    scope?: string;
+    /** Existing registration to reuse instead of registering again. */
+    clientId?: string;
+    clientSecret?: string;
+    /** Replaced in tests with something that drives the AS directly rather
+     * than launching a real browser. */
+    openBrowser?: (url: string) => void | Promise<void>;
+    /** 0 = let the OS choose. The redirect URI is built from whatever port
+     * is actually bound, so a fixed one is never required. */
+    callbackPort?: number;
+    timeoutMs?: number;
+}
+/**
+ * RFC 7591. Returns `undefined` when the AS advertises no registration
+ * endpoint — that is a legitimate configuration (a pre-registered
+ * client), not an error, so the caller falls back to whatever client id
+ * it was given.
+ */
+export declare function registerClient(metadata: AuthorizationServerMetadata, redirectUri: string, opts?: {
+    fetchImpl?: FetchLike;
+    scope?: string;
+}): Promise<{
+    clientId: string;
+    clientSecret?: string;
+} | undefined>;
+/**
+ * Runs the full authorization-code-plus-PKCE exchange and returns a
+ * token ready to persist. Does not write anything — storage is the
+ * caller's decision, so this stays testable without a home directory.
+ */
+export declare function authorize(serverName: string, metadata: AuthorizationServerMetadata, opts?: AuthorizeOptions): Promise<StoredToken>;