agent-trellis 0.4.0 → 0.6.0

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/memoryGraph.d.ts

@@ -58,3 +58,38 @@ export interface MemorySyncPlan {
  * regardless of what canonical wants.
  */
 export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined): MemorySyncPlan;
+/**
+ * Renders one extraction candidate as readable markdown — the entity's
+ * real (unslugged) name as a heading, its type, its observations as a
+ * list, and (only when it participates in any) its relations as a short
+ * list. Not a serialization format meant to round-trip byte-for-byte
+ * back through `planMemorySync` (trellis-memory-extraction design.md
+ * D2/Non-Goals) — canonical's own memory model is a single flat blob per
+ * file, strictly less expressive than the graph's typed-entity-plus-
+ * relations shape.
+ */
+export declare function renderExtractedMemoryFile(entity: MemoryEntity, relations: readonly MemoryRelation[]): string;
+export type MemoryExtractionAction = "create" | "already-extracted" | "conflict";
+export interface MemoryExtractionItem {
+    /** The entity's real, unslugged name. */
+    name: string;
+    /** The derived target filename, without the `.md` extension. */
+    slug: string;
+    action: MemoryExtractionAction;
+    detail: string;
+    /** Only set when `action === "create"` — the file content to write. */
+    content?: string;
+}
+export interface MemoryExtractionPlan {
+    items: MemoryExtractionItem[];
+}
+/**
+ * Pure: given the graph's parsed lines and a way to read an existing
+ * canonical memory file by its (already-slugged) name, computes which
+ * non-`trellis-memory` entities (D1) should become new canonical files.
+ * `readCanonicalFile` returning `undefined` means "no such file yet" —
+ * the same "create vs. already-there vs. differs" three-way split
+ * `planMcpServer`/skill-migrate already use elsewhere in this codebase,
+ * applied to a new content type (trellis-memory-extraction design.md D4).
+ */
+export declare function planMemoryExtraction(graphLines: readonly MemoryGraphLine[], readCanonicalFile: (slug: string) => string | undefined): MemoryExtractionPlan;

package/dist/lib/memoryGraph.js

@@ -22,6 +22,7 @@
  * completely untouched — reported as a conflict, never overwritten.
  */
 import { readFileSync } from "node:fs";
+import { slugify } from "./slug.js";
 export const TRELLIS_MEMORY_ENTITY_TYPE = "trellis-memory";
 export function parseMemoryGraph(content) {
     const lines = [];
@@ -99,3 +100,64 @@ export function planMemorySync(canonical, currentGraphContent) {
     }
     return { items, nextGraph: [...untouchedLines, ...nextTrellisEntities] };
 }
+/**
+ * Renders one extraction candidate as readable markdown — the entity's
+ * real (unslugged) name as a heading, its type, its observations as a
+ * list, and (only when it participates in any) its relations as a short
+ * list. Not a serialization format meant to round-trip byte-for-byte
+ * back through `planMemorySync` (trellis-memory-extraction design.md
+ * D2/Non-Goals) — canonical's own memory model is a single flat blob per
+ * file, strictly less expressive than the graph's typed-entity-plus-
+ * relations shape.
+ */
+export function renderExtractedMemoryFile(entity, relations) {
+    const lines = [`# ${entity.name}`, "", `**Type:** ${entity.entityType}`, "", "## Observations"];
+    for (const observation of entity.observations) {
+        lines.push(`- ${observation}`);
+    }
+    const related = relations.filter((r) => r.from === entity.name || r.to === entity.name);
+    if (related.length > 0) {
+        lines.push("", "## Relations");
+        for (const r of related) {
+            lines.push(r.from === entity.name ? `- ${r.relationType} -> ${r.to}` : `- ${r.from} -> ${r.relationType} -> this entity`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Pure: given the graph's parsed lines and a way to read an existing
+ * canonical memory file by its (already-slugged) name, computes which
+ * non-`trellis-memory` entities (D1) should become new canonical files.
+ * `readCanonicalFile` returning `undefined` means "no such file yet" —
+ * the same "create vs. already-there vs. differs" three-way split
+ * `planMcpServer`/skill-migrate already use elsewhere in this codebase,
+ * applied to a new content type (trellis-memory-extraction design.md D4).
+ */
+export function planMemoryExtraction(graphLines, readCanonicalFile) {
+    const entities = graphLines.filter((line) => line.type === "entity");
+    const relations = graphLines.filter((line) => line.type === "relation");
+    const candidates = entities.filter((e) => e.entityType !== TRELLIS_MEMORY_ENTITY_TYPE && e.observations.length > 0);
+    const items = [];
+    const claimedSlugs = new Map();
+    for (const entity of candidates) {
+        const slug = slugify(entity.name);
+        const claimedBy = claimedSlugs.get(slug);
+        if (claimedBy !== undefined) {
+            items.push({ name: entity.name, slug, action: "conflict", detail: `slug "${slug}" collides with entity "${claimedBy}" — resolve by hand` });
+            continue;
+        }
+        claimedSlugs.set(slug, entity.name);
+        const content = renderExtractedMemoryFile(entity, relations);
+        const existing = readCanonicalFile(slug);
+        if (existing === undefined) {
+            items.push({ name: entity.name, slug, action: "create", detail: "will create a new canonical memory file", content });
+        }
+        else if (existing === content) {
+            items.push({ name: entity.name, slug, action: "already-extracted", detail: "canonical file content is already identical" });
+        }
+        else {
+            items.push({ name: entity.name, slug, action: "conflict", detail: `~/.trellis/memories/${slug}.md already exists with different content — resolve by hand` });
+        }
+    }
+    return { items };
+}

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

package/dist/lib/oauth/flow.js

@@ -0,0 +1,193 @@
+/**
+ * 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 { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { createPkcePair } from "./pkce.js";
+export class AuthorizationError extends Error {
+}
+/**
+ * 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 async function registerClient(metadata, redirectUri, opts = {}) {
+    if (!metadata.registrationEndpoint)
+        return undefined;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(metadata.registrationEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({
+            client_name: "Trellis",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            ...(opts.scope ? { scope: opts.scope } : {}),
+        }),
+    });
+    if (!response.ok) {
+        throw new AuthorizationError(`dynamic client registration failed with HTTP ${response.status}`);
+    }
+    const payload = (await response.json());
+    if (!payload.client_id) {
+        throw new AuthorizationError("dynamic client registration returned no client_id");
+    }
+    const out = { clientId: payload.client_id };
+    if (payload.client_secret)
+        out.clientSecret = payload.client_secret;
+    return out;
+}
+/** A one-shot loopback listener for the redirect. Bound to 127.0.0.1
+ * explicitly, never 0.0.0.0: the authorization code arrives in this URL,
+ * and a listener on all interfaces would accept it from the network. */
+function listenForCallback(port) {
+    return new Promise((resolve, reject) => {
+        let settle;
+        const received = new Promise((r) => {
+            settle = r;
+        });
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            const result = {};
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            if (code)
+                result.code = code;
+            if (state)
+                result.state = state;
+            if (error) {
+                result.error = error;
+                const description = url.searchParams.get("error_description");
+                if (description)
+                    result.errorDescription = description;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(result.error
+                ? `<html><body><h1>Authorization failed</h1><p>${escapeHtml(result.errorDescription ?? result.error)}</p></body></html>`
+                : "<html><body><h1>Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
+            settle(result);
+        });
+        server.on("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            resolve({ server, port: server.address().port, received });
+        });
+    });
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+/**
+ * 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 async function authorize(serverName, metadata, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? Date.now;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    try {
+        let clientId = opts.clientId;
+        let clientSecret = opts.clientSecret;
+        if (!clientId) {
+            const registered = await registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope });
+            if (!registered) {
+                throw new AuthorizationError(`"${serverName}"'s authorization server offers no dynamic client registration, and no client_id is configured for it`);
+            }
+            clientId = registered.clientId;
+            clientSecret = registered.clientSecret;
+        }
+        const pkce = createPkcePair();
+        const state = randomBytes(16).toString("base64url");
+        const authUrl = new URL(metadata.authorizationEndpoint);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", clientId);
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        authUrl.searchParams.set("code_challenge", pkce.challenge);
+        authUrl.searchParams.set("code_challenge_method", pkce.method);
+        authUrl.searchParams.set("state", state);
+        if (opts.scope)
+            authUrl.searchParams.set("scope", opts.scope);
+        await (opts.openBrowser ?? defaultOpenBrowser)(authUrl.toString());
+        const callback = await withTimeout(received, timeoutMs, `timed out waiting for the authorization callback for "${serverName}"`);
+        if (callback.error) {
+            throw new AuthorizationError(`authorization for "${serverName}" was refused: ${callback.errorDescription ?? callback.error}`);
+        }
+        if (!callback.code) {
+            throw new AuthorizationError(`authorization for "${serverName}" returned no code`);
+        }
+        // CSRF: a callback carrying someone else's state is not ours to
+        // redeem, regardless of how good the code looks.
+        if (callback.state !== state) {
+            throw new AuthorizationError(`authorization callback for "${serverName}" carried an unexpected state parameter`);
+        }
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: callback.code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: pkce.verifier,
+        });
+        if (clientSecret)
+            body.set("client_secret", clientSecret);
+        const response = await fetchImpl(metadata.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            throw new AuthorizationError(`token exchange for "${serverName}" failed with HTTP ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (!payload.access_token) {
+            throw new AuthorizationError(`token exchange for "${serverName}" returned no access_token`);
+        }
+        const token = {
+            accessToken: payload.access_token,
+            tokenEndpoint: metadata.tokenEndpoint,
+            clientId,
+        };
+        if (payload.refresh_token)
+            token.refreshToken = payload.refresh_token;
+        if (payload.expires_in !== undefined)
+            token.expiresAt = now() + payload.expires_in * 1000;
+        if (clientSecret)
+            token.clientSecret = clientSecret;
+        if (payload.scope ?? opts.scope)
+            token.scope = payload.scope ?? opts.scope;
+        return token;
+    }
+    finally {
+        server.close();
+    }
+}
+function withTimeout(promise, timeoutMs, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new AuthorizationError(message)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+async function defaultOpenBrowser(url) {
+    const { spawn } = await import("node:child_process");
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    // Detached and fully ignored: a browser that outlives this command is
+    // correct, and its stdio must not be inherited onto ours.
+    spawn(command, [url], { detached: true, stdio: "ignore" }).unref();
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Per-server exclusive lock around OAuth refresh
+ * (trellis-mcp-gateway-hosting design.md D16).
+ *
+ * Why this is a correctness fix and not an optimization: most
+ * authorization servers rotate the refresh token on each
+ * `refresh_token` grant and invalidate the previous one. Two processes
+ * refreshing the same server concurrently therefore leave one of them
+ * holding a token that is already dead — and it fails later, somewhere
+ * else, looking like an unrelated auth error. This is reachable today
+ * with a single gateway, because `trellis mcp auth` can be run by hand
+ * while one is live.
+ *
+ * Scoped to one server: a slow refresh for server A must never delay
+ * connecting to server B.
+ */
+/**
+ * Runs `fn` while holding this server's lock, releasing it even if `fn`
+ * throws. `wx` is the atomic primitive: it either creates the file or
+ * fails, with no check-then-create window between two processes.
+ */
+export declare function withServerLock<T>(homeDir: string, serverName: string, fn: () => Promise<T>, opts?: {
+    timeoutMs?: number;
+    now?: () => number;
+}): Promise<T>;