agent-trellis 0.7.0 → 0.8.0

package/dist/lib/backup.js

@@ -67,6 +67,7 @@ export function openBackupSession(homeDir, command) {
         dirCreated = true;
     }
     return {
+        runId,
         writeFile(path, content) {
             ensureDir();
             const afterHash = sha256(content);
@@ -105,6 +106,9 @@ export function openBackupSession(homeDir, command) {
             await rm(path, { force: true });
             operations.push({ kind: "symlink-remove", path, beforeLinkTarget: oldLinkTarget });
         },
+        hasOperations() {
+            return operations.length > 0;
+        },
         finalize() {
             if (!dirCreated)
                 return;

package/dist/lib/builtinSkills.d.ts

@@ -0,0 +1,2 @@
+export declare const TRELLIS_RUNTIME_SKILL_NAME = "trellis-runtime";
+export declare function isBuiltinSkillName(name: string): boolean;

package/dist/lib/builtinSkills.js

@@ -0,0 +1,4 @@
+export const TRELLIS_RUNTIME_SKILL_NAME = "trellis-runtime";
+export function isBuiltinSkillName(name) {
+    return name === TRELLIS_RUNTIME_SKILL_NAME;
+}

package/dist/lib/cliMetadata.d.ts

@@ -0,0 +1 @@
+export declare const TRELLIS_VERSION: string;

package/dist/lib/cliMetadata.js

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+/**
+ * Read the package version relative to the compiled/source CLI entrypoint.
+ * `src/lib` and `dist/lib` are both exactly two levels below package.json,
+ * so the same URL works under tsx and from an installed package.
+ */
+function loadPackageVersion() {
+    const manifest = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+        throw new Error("agent-trellis package.json does not declare a version");
+    }
+    return manifest.version;
+}
+export const TRELLIS_VERSION = loadPackageVersion();

package/dist/lib/gatewayBackend.d.ts

@@ -23,6 +23,8 @@ export interface GatewayBackend {
     listTools(): Promise<AggregatedTool[]>;
     /** Invoke one aggregated tool; implementations route it to its owner. */
     callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Sanitized connection state for user/Agent remediation. */
+    listStatus?(): readonly UpstreamStatus[];
     /** Release everything this backend holds. Must be safe to call twice. */
     close(): Promise<void>;
 }
@@ -32,6 +34,17 @@ export interface UpstreamSpec {
     name: string;
     def: McpServerDef;
 }
+export type UpstreamStatusKind = "ready" | "auth-required" | "unavailable" | "timeout" | "degraded";
+export interface UpstreamStatus {
+    name: string;
+    transport: "stdio" | "http" | "sse";
+    status: UpstreamStatusKind;
+    detail?: string;
+    remediation?: string;
+    remediationKind?: "oauth" | "environment" | "install" | "endpoint" | "router";
+    requiresHuman?: boolean;
+    requiresSessionRestart?: boolean;
+}
 export interface LocalBackendOptions {
     secretsPolicy: SecretsPolicy;
     clientInfo: McpClientInfo;
@@ -64,12 +77,27 @@ export declare class LocalBackend implements GatewayBackend {
     private readonly warn;
     private readonly registry;
     private readonly connected;
+    private readonly statuses;
     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>;
+    listStatus(): readonly UpstreamStatus[];
     close(): Promise<void>;
     private closeUpstream;
 }
+/**
+ * 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.
+ */
+export declare function withOAuthHeader(name: string, def: McpServerDef, homeDir: string): Promise<McpServerDef>;

package/dist/lib/gatewayBackend.js

@@ -32,6 +32,7 @@ export class LocalBackend {
     warn;
     registry = new McpToolRegistry();
     connected = new Set();
+    statuses = new Map();
     closed = false;
     constructor(warn) {
         this.warn = warn;
@@ -43,6 +44,8 @@ export class LocalBackend {
         return backend;
     }
     async addUpstream({ name, def }, options) {
+        const transport = def.transport === "http" || def.transport === "sse" ? def.transport : "stdio";
+        this.statuses.set(name, { name, transport, status: "unavailable", detail: "connecting" });
         let effectiveDef = def;
         if (options.homeDir && def.url) {
             try {
@@ -53,6 +56,7 @@ export class LocalBackend {
                 // 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)}`);
+                this.statuses.set(name, failureStatus(name, def, err));
                 return;
             }
         }
@@ -62,6 +66,7 @@ export class LocalBackend {
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to connect to MCP server "${name}": ${errorText(err)}`);
+            this.statuses.set(name, failureStatus(name, def, err));
             return;
         }
         this.connected.add(client);
@@ -73,12 +78,28 @@ export class LocalBackend {
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to list tools for MCP server "${name}": ${errorText(err)}`);
             await this.closeUpstream(client);
+            this.statuses.set(name, failureStatus(name, def, err));
             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`);
         }
+        if (tools.length === 0 && name === "mcp-router") {
+            this.statuses.set(name, {
+                name,
+                transport,
+                status: "degraded",
+                detail: "router connected but exposed no downstream tools",
+                remediationKind: "router",
+                requiresHuman: true,
+                remediation: "check the MCP router's provider login/configuration and reconnect it, then restart the Agent session",
+                requiresSessionRestart: true,
+            });
+        }
+        else {
+            this.statuses.set(name, { name, transport, status: "ready", detail: `connected; ${tools.length} tool(s) available` });
+        }
     }
     async listTools() {
         return this.registry.listTools();
@@ -86,6 +107,9 @@ export class LocalBackend {
     async callTool(name, args) {
         return this.registry.callTool(name, args);
     }
+    listStatus() {
+        return [...this.statuses.values()];
+    }
     async close() {
         if (this.closed)
             return;
@@ -105,6 +129,53 @@ export class LocalBackend {
         }
     }
 }
+function failureStatus(name, def, error) {
+    const detail = errorText(error).slice(0, 300);
+    const auth = def.url !== undefined && /401|403|unauthorized|forbidden|authentication|required|login/i.test(detail);
+    const timeout = /timed out|timeout/i.test(detail);
+    if (auth) {
+        return {
+            name,
+            transport: def.transport === "sse" ? "sse" : "http",
+            status: "auth-required",
+            detail,
+            remediationKind: "oauth",
+            requiresHuman: true,
+            requiresSessionRestart: true,
+            remediation: `run \`trellis mcp auth ${name}\` in a human terminal, then restart the Agent session`,
+        };
+    }
+    if (timeout) {
+        return {
+            name,
+            transport: def.transport === "sse" ? "sse" : def.url ? "http" : "stdio",
+            status: "timeout",
+            detail,
+            remediationKind: def.url ? "endpoint" : "environment",
+            requiresHuman: true,
+            requiresSessionRestart: true,
+            remediation: def.url
+                ? `check the endpoint/network; if it requires OAuth, run \`trellis mcp auth ${name}\``
+                : `check that \`${def.command ?? "the MCP command"}\` is installed and responsive`,
+        };
+    }
+    const envNames = [...(def.env ?? []), ...Object.keys(def.envAliases ?? {})];
+    const missingExecutable = /ENOENT|not found|no such file/i.test(detail);
+    return {
+        name,
+        transport: def.transport === "sse" ? "sse" : def.url ? "http" : "stdio",
+        status: "unavailable",
+        detail,
+        remediationKind: def.url ? "endpoint" : (missingExecutable ? "install" : "environment"),
+        requiresHuman: true,
+        requiresSessionRestart: true,
+        remediation: def.url
+            ? `check the MCP endpoint and credentials; run \`trellis mcp auth ${name}\` if it uses OAuth`
+            : envNames.length > 0
+                ? `check the configured environment variables (${envNames.join(", ")}) and rerun \`trellis mcp sync\``
+                : `check that \`${def.command ?? "the MCP command"}\` is installed and responsive`,
+    };
+}
 /**
  * Attaches a stored OAuth token, refreshing it first if it has expired.
  *
@@ -117,7 +188,7 @@ export class LocalBackend {
  * 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) {
+export async function withOAuthHeader(name, def, homeDir) {
     const hasExplicitAuth = Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
     if (hasExplicitAuth)
         return def;

package/dist/lib/installAgent.d.ts

@@ -2,14 +2,15 @@
  * Install-then-manage (trellis-managed-agents design.md D5): selecting a
  * not-yet-present agent into the managed set is itself the authorization
  * to install it, but never silently — one confirmation, then a real
- * `npm install -g <package>` child process. Kiro has no npm package (a
- * desktop download) and is refused before this module is ever reached.
+ * `npm install -g <package>` child process. Kiro and Kimi Code use official
+ * install scripts rather than an npm package and are refused before this
+ * module is ever reached.
  */
 import type { AgentId } from "../core/types.js";
 /** Only agents with a real `npm install -g <pkg>` command — Kiro's own
  * `INSTALL_HINTS` entry is a download URL, not a package, and is never
  * looked up here. */
-export declare const NPM_INSTALLABLE: Record<Exclude<AgentId, "kiro">, string>;
+export declare const NPM_INSTALLABLE: Record<Exclude<AgentId, "kiro" | "kimi-code">, string>;
 export interface ConfirmAndInstallOptions {
     /** Test/real seam, same pattern as onboard's `promptForAgent` — a real
      * terminal confirmation by default. */
@@ -19,8 +20,9 @@ export interface ConfirmAndInstallOptions {
 }
 export interface ConfirmAndInstallResult {
     installed: boolean;
-    /** False only when the agent has no npm package at all (Kiro) — the
-     * caller refuses this agent with its download URL instead of prompting. */
+    /** False when the agent has no supported npm installation path — the
+     * caller refuses it with its official installation hint instead of
+     * prompting. */
     installable: boolean;
 }
 export declare function confirmAndInstall(agent: AgentId, opts?: ConfirmAndInstallOptions): Promise<ConfirmAndInstallResult>;

package/dist/lib/installAgent.js

@@ -2,8 +2,9 @@
  * Install-then-manage (trellis-managed-agents design.md D5): selecting a
  * not-yet-present agent into the managed set is itself the authorization
  * to install it, but never silently — one confirmation, then a real
- * `npm install -g <package>` child process. Kiro has no npm package (a
- * desktop download) and is refused before this module is ever reached.
+ * `npm install -g <package>` child process. Kiro and Kimi Code use official
+ * install scripts rather than an npm package and are refused before this
+ * module is ever reached.
  */
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
@@ -31,7 +32,7 @@ function runInstallReal(pkg) {
     execFileSync("npm", ["install", "-g", pkg], { stdio: "inherit" });
 }
 export async function confirmAndInstall(agent, opts = {}) {
-    if (agent === "kiro") {
+    if (agent === "kiro" || agent === "kimi-code") {
         return { installed: false, installable: false };
     }
     const pkg = NPM_INSTALLABLE[agent];

package/dist/lib/mcpConnect.js

@@ -19,6 +19,7 @@ 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;
+const FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1_000;
 /**
  * A hanging server (process alive, protocol response never sent) leaves
  * `promise` permanently unsettled — indistinguishable from "still
@@ -55,7 +56,10 @@ export async function connectWithCleanup(client, transport, timeoutMs, message)
     }
     catch (err) {
         try {
-            await transport.close();
+            // A failed HTTP transport can itself hang while closing. Cleanup is
+            // best-effort and must not turn one bad upstream into a Gateway-wide
+            // startup timeout; preserve the original connect error below.
+            await withTimeout(Promise.resolve().then(() => transport.close()), FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS, "transport cleanup timed out");
         }
         catch {
             // best-effort; the original connect failure is what matters

package/dist/lib/mcpMigrateRead.d.ts

@@ -37,6 +37,7 @@ export interface McpMigrateReadResult {
 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 declare function readKimiCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export interface CodexMcpEntryRich {
     name: string;
     enabled: boolean;

package/dist/lib/mcpMigrateRead.js

@@ -108,6 +108,9 @@ export function readClaudeCodeMcpDefs(homeDir) {
 export function readKiroMcpDefs(homeDir) {
     return readRichJsonMcpDefs(join(homeDir, ".kiro", "settings", "mcp.json"));
 }
+export function readKimiCodeMcpDefs(homeDir) {
+    return readRichJsonMcpDefs(join(homeDir, ".kimi-code", "mcp.json"));
+}
 /**
  * Pure conversion half — separated from the subprocess/file-read effects
  * below so the stdio/non-stdio/malformed decision logic is unit-testable

package/dist/lib/mcpRuntime.d.ts

@@ -0,0 +1,46 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { CallToolResult, GetPromptResult, Implementation, Prompt, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { AgentId } from "../core/types.js";
+import type { GatewayBackend } from "./gatewayBackend.js";
+export interface RuntimeContext {
+    agentId: AgentId;
+    homeDir: string;
+}
+export interface TrellisProvider {
+    readonly id: string;
+    listTools?(context: RuntimeContext): Promise<Tool[]> | Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources?(context: RuntimeContext): Promise<Resource[]> | Resource[];
+    readResource?(uri: URL, context: RuntimeContext): Promise<ReadResourceResult> | ReadResourceResult;
+    listPrompts?(context: RuntimeContext): Promise<Prompt[]> | Prompt[];
+    getPrompt?(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult> | GetPromptResult;
+    close?(): Promise<void>;
+}
+export declare class BuiltinRegistry {
+    private readonly providers;
+    private readonly warn;
+    private readonly toolOwners;
+    private readonly originalToolOwners;
+    private readonly exposedToOriginal;
+    private readonly resourceOwners;
+    private readonly promptOwners;
+    constructor(providers: readonly TrellisProvider[], warn?: (message: string) => void);
+    listTools(context: RuntimeContext): Promise<Tool[]>;
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    listResources(context: RuntimeContext): Promise<Resource[]>;
+    readResource(uri: URL, context: RuntimeContext): Promise<ReadResourceResult>;
+    listPrompts(context: RuntimeContext): Promise<Prompt[]>;
+    getPrompt(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult>;
+    close(): Promise<void>;
+}
+/** Adapts the existing gateway tool backend without duplicating its routing
+ * or upstream connection logic. */
+export declare class UpstreamProvider implements TrellisProvider {
+    private readonly backend;
+    readonly id = "upstream";
+    constructor(backend: GatewayBackend);
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: unknown): Promise<CallToolResult>;
+    close(): Promise<void>;
+}
+export declare function createRuntimeServer(serverInfo: Implementation, context: RuntimeContext, registry: BuiltinRegistry): Server;

package/dist/lib/mcpRuntime.js

@@ -0,0 +1,185 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { allocateExposedToolNames } from "./mcpToolRegistry.js";
+function compactBuiltinToolName(name) {
+    return name.startsWith("trellis.") ? name.slice("trellis.".length).replaceAll(".", "_") : name;
+}
+function providerError(provider, error) {
+    return `trellis-mcp-runtime: provider "${provider}" failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+export class BuiltinRegistry {
+    providers;
+    warn;
+    toolOwners = new Map();
+    originalToolOwners = new Map();
+    exposedToOriginal = new Map();
+    resourceOwners = new Map();
+    promptOwners = new Map();
+    constructor(providers, warn = console.error) {
+        this.providers = providers;
+        this.warn = warn;
+    }
+    async listTools(context) {
+        const candidates = [];
+        this.toolOwners.clear();
+        this.originalToolOwners.clear();
+        this.exposedToOriginal.clear();
+        for (const provider of this.providers) {
+            if (!provider.listTools)
+                continue;
+            try {
+                for (const tool of await provider.listTools(context)) {
+                    candidates.push({ provider, tool });
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        const exposedNames = allocateExposedToolNames(candidates.map(({ provider, tool }) => ({
+            serverName: provider.id,
+            toolName: provider.id === "upstream" ? tool.name : compactBuiltinToolName(tool.name),
+        })));
+        return candidates.map(({ provider, tool }, index) => {
+            const exposedName = exposedNames[index];
+            this.toolOwners.set(exposedName, provider);
+            this.exposedToOriginal.set(exposedName, tool.name);
+            if (!this.originalToolOwners.has(tool.name))
+                this.originalToolOwners.set(tool.name, provider);
+            const title = exposedName === tool.name || tool.title !== undefined
+                ? tool.title
+                : `${provider.id} / ${tool.name}`;
+            return { ...tool, name: exposedName, ...(title === undefined ? {} : { title }) };
+        });
+    }
+    async callTool(name, args, context) {
+        let provider = this.toolOwners.get(name);
+        let originalName = this.exposedToOriginal.get(name) ?? name;
+        if (!provider) {
+            await this.listTools(context);
+            provider = this.toolOwners.get(name);
+            originalName = this.exposedToOriginal.get(name) ?? name;
+            // Keep direct programmatic calls using the logical pre-normalization
+            // name working, while never advertising an invalid alias to an Agent.
+            if (!provider)
+                provider = this.originalToolOwners.get(name);
+        }
+        if (!provider)
+            return { content: [{ type: "text", text: `unknown Trellis tool "${name}"` }], isError: true };
+        try {
+            return await provider.callTool(originalName, args, context);
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: providerError(provider.id, err) }], isError: true };
+        }
+    }
+    async listResources(context) {
+        const resources = [];
+        this.resourceOwners.clear();
+        for (const provider of this.providers) {
+            if (!provider.listResources)
+                continue;
+            try {
+                for (const resource of await provider.listResources(context)) {
+                    if (this.resourceOwners.has(resource.uri)) {
+                        this.warn(`trellis-mcp-runtime: duplicate resource "${resource.uri}" from provider "${provider.id}"`);
+                        continue;
+                    }
+                    this.resourceOwners.set(resource.uri, provider);
+                    resources.push(resource);
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return resources;
+    }
+    async readResource(uri, context) {
+        const key = uri.toString();
+        let provider = this.resourceOwners.get(key);
+        if (!provider) {
+            await this.listResources(context);
+            provider = this.resourceOwners.get(key);
+        }
+        if (!provider?.readResource)
+            throw new Error(`unknown Trellis resource "${key}"`);
+        return provider.readResource(uri, context);
+    }
+    async listPrompts(context) {
+        const prompts = [];
+        this.promptOwners.clear();
+        for (const provider of this.providers) {
+            if (!provider.listPrompts)
+                continue;
+            try {
+                for (const prompt of await provider.listPrompts(context)) {
+                    if (this.promptOwners.has(prompt.name)) {
+                        this.warn(`trellis-mcp-runtime: duplicate prompt "${prompt.name}" from provider "${provider.id}"`);
+                        continue;
+                    }
+                    this.promptOwners.set(prompt.name, provider);
+                    prompts.push(prompt);
+                }
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return prompts;
+    }
+    async getPrompt(name, args, context) {
+        let provider = this.promptOwners.get(name);
+        if (!provider) {
+            await this.listPrompts(context);
+            provider = this.promptOwners.get(name);
+        }
+        if (!provider?.getPrompt)
+            throw new Error(`unknown Trellis prompt "${name}"`);
+        return provider.getPrompt(name, args, context);
+    }
+    async close() {
+        await Promise.all(this.providers.map(async (provider) => {
+            try {
+                await provider.close?.();
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }));
+    }
+}
+/** Adapts the existing gateway tool backend without duplicating its routing
+ * or upstream connection logic. */
+export class UpstreamProvider {
+    backend;
+    id = "upstream";
+    constructor(backend) {
+        this.backend = backend;
+    }
+    async listTools() {
+        return (await this.backend.listTools());
+    }
+    async callTool(name, args) {
+        return (await this.backend.callTool(name, args));
+    }
+    async close() {
+        await this.backend.close();
+    }
+}
+export function createRuntimeServer(serverInfo, context, registry) {
+    const server = new Server(serverInfo, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true },
+            prompts: { listChanged: true },
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await registry.listTools(context) }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => registry.callTool(request.params.name, request.params.arguments, context));
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await registry.listResources(context) }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => registry.readResource(new URL(request.params.uri), context));
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await registry.listPrompts(context) }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => registry.getPrompt(request.params.name, request.params.arguments, context));
+    return server;
+}

package/dist/lib/mcpStatusProvider.d.ts

@@ -0,0 +1,10 @@
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { GatewayBackend } from "./gatewayBackend.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+export declare class McpStatusProvider implements TrellisProvider {
+    private readonly backend;
+    readonly id = "mcp";
+    constructor(backend: GatewayBackend);
+    listTools(): Tool[];
+    callTool(name: string, _args: unknown, _context: RuntimeContext): Promise<CallToolResult>;
+}

package/dist/lib/mcpStatusProvider.js

@@ -0,0 +1,25 @@
+const STATUS_TOOL = {
+    name: "trellis.mcp.status",
+    description: "Show MCP upstream availability and the safe next action for authentication or configuration failures.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+export class McpStatusProvider {
+    backend;
+    id = "mcp";
+    constructor(backend) {
+        this.backend = backend;
+    }
+    listTools() {
+        return [STATUS_TOOL];
+    }
+    async callTool(name, _args, _context) {
+        if (name !== STATUS_TOOL.name)
+            return { content: [{ type: "text", text: `unknown MCP status tool "${name}"` }], isError: true };
+        const statuses = this.backend.listStatus?.() ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify({ servers: statuses }, null, 2) }],
+            structuredContent: { servers: statuses },
+        };
+    }
+}

package/dist/lib/mcpToolRegistry.d.ts

@@ -33,6 +33,11 @@ export interface UpstreamTool {
     [key: string]: unknown;
 }
 export type AggregatedTool = UpstreamTool;
+/** The strictest Agent-facing tool-name contract currently exercised by the
+ * local stack (notably the Codex-compatible model tool surface). */
+export declare const MAX_EXPOSED_TOOL_NAME_LENGTH = 64;
+export declare const SHORT_EXPOSED_TOOL_NAME_LENGTH = 12;
+export declare const EXPOSED_TOOL_NAME_PATTERN: RegExp;
 /**
  * `${serverName}__${toolName}`, the separator every consumer of this
  * registry shares. Two underscores rather than one because single
@@ -41,7 +46,17 @@ export type AggregatedTool = UpstreamTool;
  * gateway matching it keeps one naming convention across both consumers.
  */
 export declare const TOOL_NAME_SEPARATOR = "__";
+/** Normalize one raw tool name without adding a server prefix. */
+export declare function normalizedToolName(toolName: string): string;
 export declare function prefixedToolName(serverName: string, toolName: string): string;
+export interface ToolNameCandidate {
+    serverName: string;
+    toolName: string;
+}
+/** Allocate all exposed names together so normalization collisions are
+ * deterministic and no upstream tool is silently lost. The returned array
+ * is indexed like `candidates`. */
+export declare function allocateExposedToolNames(candidates: readonly ToolNameCandidate[]): string[];
 export interface AddResult {
     /** Prefixed names actually registered by this call. */
     added: string[];
@@ -58,6 +73,8 @@ export interface AddResult {
 export declare class McpToolRegistry {
     private readonly entries;
     private readonly order;
+    private readonly candidates;
+    private rebuild;
     /**
      * Register one connected upstream's tools. Callers add each upstream
      * independently, so an upstream that failed to connect or to list its
@@ -65,6 +82,7 @@ export declare class McpToolRegistry {
      * aggregated, with no special-casing here.
      */
     add(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
+    private exposedNameFor;
     /** 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. */