agent-trellis 0.7.0 → 0.8.2

package/dist/pi-bridge/index.js

@@ -15,29 +15,17 @@ import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { McpToolRegistry } from "../lib/mcpToolRegistry.js";
+import { withOAuthHeader } from "../lib/gatewayBackend.js";
 import { ALL_AGENTS } from "../core/types.js";
-import { bridgedToolName, toParametersSchema, toPiContent } from "./schemaTranslate.js";
+import { toParametersSchema, toPiContent } from "./schemaTranslate.js";
 /** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
  * importing it from the module it was written against — proving the
  * extraction changed nothing it could observe. */
 export { withTimeout };
 const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
-function registerServerTools(pi, serverName, client, timeoutMs) {
-    return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => {
-        for (const tool of result.tools) {
-            pi.registerTool({
-                name: bridgedToolName(serverName, tool.name),
-                label: tool.name,
-                description: tool.description ?? `MCP tool "${tool.name}" from server "${serverName}"`,
-                parameters: toParametersSchema(tool.inputSchema),
-                async execute(_toolCallId, params) {
-                    const result = await client.callTool({ name: tool.name, arguments: params });
-                    const content = Array.isArray(result.content) ? result.content : [];
-                    return { content: toPiContent(content), details: result };
-                },
-            });
-        }
-    });
+function listServerTools(client, timeoutMs) {
+    return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => result.tools);
 }
 /**
  * `homeDir`/`connectTimeoutMs` default to the real `~` / 10s — only
@@ -57,6 +45,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // is pi reading canonical directly at its own runtime, P4's own concern.
     const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
     const clients = new Set();
+    const registry = new McpToolRegistry();
     const closeClient = async (client) => {
         if (!clients.delete(client))
             return;
@@ -83,25 +72,57 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // pi 0.85.x emits this before tearing down an extension runtime. Keep the
     // hook optional so the bridge remains loadable in older compatible hosts.
     pi.on?.("session_shutdown", closeAllClients);
-    await Promise.all(desired.map(async ({ name, def }) => {
+    const discovered = await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            client = await connectServer(def, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
+            const effectiveDef = def.auth === "oauth" && def.url
+                ? await withOAuthHeader(name, def, homeDir)
+                : def;
+            client = await connectServer(effectiveDef, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);
         }
         catch (err) {
             // One unreachable/misconfigured (including permanently hanging —
             // trellis-mcp-connect-timeout) server must never prevent every
             // other server's tools from registering (tasks.md 3.2).
             console.error(`trellis-mcp-bridge: failed to connect to MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
-            return;
+            return undefined;
         }
         clients.add(client);
         try {
-            await registerServerTools(pi, name, client, connectTimeoutMs);
+            const tools = await listServerTools(client, connectTimeoutMs);
+            return { name, client, tools };
         }
         catch (err) {
             console.error(`trellis-mcp-bridge: failed to list tools for MCP server "${name}": ${err instanceof Error ? err.message : String(err)}`);
             await closeClient(client);
+            return undefined;
         }
     }));
+    // Add in canonical plan order, not completion order, so allocation remains
+    // stable when multiple upstreams answer concurrently.
+    for (const result of discovered) {
+        if (!result)
+            continue;
+        registry.add(result.name, result.client, result.tools);
+    }
+    for (const tool of registry.listTools()) {
+        const target = registry.resolve(tool.name);
+        if (!target)
+            continue;
+        const originalName = target.toolName;
+        const serverName = target.serverName;
+        pi.registerTool({
+            name: tool.name,
+            label: originalName,
+            description: tool.description ?? `MCP tool "${originalName}" from server "${serverName}"`,
+            parameters: toParametersSchema(tool.inputSchema),
+            async execute(_toolCallId, params) {
+                const result = await registry.callTool(tool.name, params);
+                const content = Array.isArray(result.content)
+                    ? result.content
+                    : [];
+                return { content: toPiContent(content), details: result };
+            },
+        });
+    }
 }

package/dist/pi-bridge/schemaTranslate.d.ts

@@ -50,12 +50,8 @@ export declare function toParametersSchema(inputSchema: unknown): TSchema;
  * own `AgentToolResult.content` has no representation for them
  * (design.md D3). */
 export declare function toPiContent(items: McpContentItem[]): PiContent[];
-/** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
- *
- * Now one implementation shared with the gateway's own aggregation rather
- * than two identical ones: the naming convention is the contract between
- * a prefixed name and the server it routes to, and two copies of it could
- * drift into routing tools to the wrong upstream
- * (trellis-mcp-gateway-hosting design.md D3). */
+/** Legacy direct prefix helper kept for callers/tests that need to render a
+ * source-qualified name. The live bridge uses `McpToolRegistry` so it can
+ * allocate short names across all connected servers, normalize invalid
+ * characters, and retain the raw name for routing. */
 export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/pi-bridge/schemaTranslate.js

@@ -33,12 +33,8 @@ export function toPiContent(items) {
         }
     });
 }
-/** `${serverName}__${toolName}` — deterministic, collision-free across
- * servers sharing pi.registerTool()'s single flat namespace (design.md D5).
- *
- * Now one implementation shared with the gateway's own aggregation rather
- * than two identical ones: the naming convention is the contract between
- * a prefixed name and the server it routes to, and two copies of it could
- * drift into routing tools to the wrong upstream
- * (trellis-mcp-gateway-hosting design.md D3). */
+/** Legacy direct prefix helper kept for callers/tests that need to render a
+ * source-qualified name. The live bridge uses `McpToolRegistry` so it can
+ * allocate short names across all connected servers, normalize invalid
+ * characters, and retain the raw name for routing. */
 export { prefixedToolName as bridgedToolName } from "../lib/mcpToolRegistry.js";

package/dist/probes/codex.d.ts

@@ -21,4 +21,11 @@ export interface ProbeOptions {
      * default — see docs/architecture.md "MCP handshake probing is opt-in". */
     probeMcp?: boolean;
 }
+/**
+ * Codex resolves its config through HOME, but Volta's shim resolves its own
+ * installation through VOLTA_HOME. A probe against a scratch HOME must keep
+ * those identities separate or `codex mcp list` fails before it can read the
+ * scratch config.
+ */
+export declare function codexEnv(homeDir: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/codex.js

@@ -11,7 +11,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { delimiter, join } from "node:path";
 import { probeMcpServer } from "../lib/mcpProbe.js";
 import { pathRef, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
 /**
@@ -30,6 +30,30 @@ export function readInstructionsPath(configTomlPath) {
     }
     return /^\s*instructions\s*=\s*"([^"]*)"/m.exec(content)?.[1];
 }
+/**
+ * Codex resolves its config through HOME, but Volta's shim resolves its own
+ * installation through VOLTA_HOME. A probe against a scratch HOME must keep
+ * those identities separate or `codex mcp list` fails before it can read the
+ * scratch config.
+ */
+export function codexEnv(homeDir, env = process.env) {
+    const voltaHome = env.VOLTA_HOME ?? join(homedir(), ".volta");
+    const voltaBin = join(voltaHome, "bin");
+    const pathParts = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const hasVolta = existsSync(voltaBin);
+    if (hasVolta && !pathParts.includes(voltaBin))
+        pathParts.unshift(voltaBin);
+    return {
+        ...env,
+        HOME: homeDir,
+        // A host may inject CODEX_HOME for its own relay/session state. It has
+        // higher priority than HOME inside Codex, so override it as well or a
+        // scratch-home probe silently reads the host's real configuration.
+        CODEX_HOME: join(homeDir, ".codex"),
+        ...(hasVolta ? { VOLTA_HOME: voltaHome } : {}),
+        ...(pathParts.length ? { PATH: pathParts.join(delimiter) } : {}),
+    };
+}
 export async function probe(homeDir = homedir(), opts = {}) {
     const configTomlPath = join(homeDir, ".codex", "config.toml");
     if (!existsSync(configTomlPath)) {
@@ -43,21 +67,29 @@ export async function probe(homeDir = homedir(), opts = {}) {
     // default `homeDir` would silently get this real machine's real MCP
     // server list instead (trellis-migrate-mcp-servers found this gap in
     // src/lib/mcpMigrateRead.ts's own equivalent call; fixed there first).
-    const codexEnv = { ...process.env, HOME: homeDir };
+    const scopedCodexEnv = codexEnv(homeDir);
     let version;
     try {
-        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000, env: codexEnv }).trim();
+        version = execFileSync("codex", ["--version"], { encoding: "utf-8", timeout: 5_000, env: scopedCodexEnv }).trim();
     }
     catch {
         // config exists without the binary on PATH — unusual, still probeable
     }
     let mcpEntries = [];
     try {
-        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: codexEnv });
+        const raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: scopedCodexEnv });
         mcpEntries = JSON.parse(raw);
     }
     catch (err) {
-        diagnostics.push(`codex mcp list --json failed: ${err instanceof Error ? err.message : String(err)}`);
+        // ENOENT means the binary itself isn't on PATH — the same benign,
+        // config-without-binary condition the `--version` check above already
+        // swallows silently, not a real failure worth alarming the user with a
+        // raw spawn error string. Anything else (malformed JSON, a non-zero
+        // exit for another reason, a timeout) is a genuine, unexpected failure
+        // and stays a diagnostic.
+        if (err?.code !== "ENOENT") {
+            diagnostics.push(`codex mcp list --json failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     const mcpServers = mcpEntries.map((entry) => ({
         name: entry.name,

package/dist/probes/kimi-code.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Kimi Code probe. Kimi 2.x stores user MCP declarations in
+ * `~/.kimi-code/mcp.json`, user Skills in `~/.kimi-code/skills`, and global
+ * instructions in `~/.kimi-code/AGENTS.md`. Kimi also discovers the generic
+ * `~/.agents/skills` root; it is reported so doctor can observe it, while the
+ * Runtime-only launcher can explicitly isolate it later.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export interface ProbeOptions {
+    probeMcp?: boolean;
+}
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/kimi-code.js

@@ -0,0 +1,55 @@
+/**
+ * Kimi Code probe. Kimi 2.x stores user MCP declarations in
+ * `~/.kimi-code/mcp.json`, user Skills in `~/.kimi-code/skills`, and global
+ * instructions in `~/.kimi-code/AGENTS.md`. Kimi also discovers the generic
+ * `~/.agents/skills` root; it is reported so doctor can observe it, while the
+ * Runtime-only launcher can explicitly isolate it later.
+ */
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+function kimiEnv(homeDir) {
+    return { ...process.env, HOME: homeDir, KIMI_CODE_HOME: join(homeDir, ".kimi-code") };
+}
+export async function probe(homeDir = homedir(), opts = {}) {
+    const root = join(homeDir, ".kimi-code");
+    const mcpPath = join(root, "mcp.json");
+    const mcpConfig = readJsonFile(mcpPath);
+    const kimiRoot = pathRef(root);
+    if (kimiRoot === undefined) {
+        return { agent: "kimi-code", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    }
+    let version;
+    try {
+        version = execFileSync("kimi", ["--version"], { encoding: "utf-8", timeout: 5_000, env: kimiEnv(homeDir) }).trim();
+    }
+    catch {
+        // A config-only fixture remains probeable without a binary on PATH.
+    }
+    const mcpServers = Object.entries(mcpConfig?.mcpServers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? (def.transport === "sse" ? "sse" : "http") : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(mcpConfig?.mcpServers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, kimiEnv(homeDir)));
+        }));
+    }
+    const skillRoots = [
+        scanSkillRoot(join(root, "skills")),
+        scanSkillRoot(join(homeDir, ".agents", "skills")),
+    ].filter((entry) => entry !== undefined);
+    return {
+        agent: "kimi-code",
+        present: true,
+        version,
+        skillRoots,
+        mcpServers,
+        instructionsFile: pathRef(join(root, "AGENTS.md")),
+        diagnostics: [],
+    };
+}

package/dist/probes/zcode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ZCode probe and profile selection.
+ *
+ * ZCode has two public configuration layouts in circulation. The official
+ * source/distribution reads ~/.zcode/cli/config.json, while the installed
+ * zcode-app-cli compatibility distribution keeps runtime settings (including
+ * mcp.servers) in ~/.zcode/cli/setting.json. We select one profile before any
+ * adapter plans a write; writing both would make ZCode's native precedence
+ * ambiguous and can hide a managed MCP entry.
+ */
+import type { AgentSnapshot } from "../core/types.js";
+export type ZcodeProfileKind = "community-cli" | "official" | "configuration-only";
+export interface ZcodeProfile {
+    kind: ZcodeProfileKind;
+    configPath: string;
+    executable?: string;
+    executableVersion?: string;
+    supportsExecution: boolean;
+}
+export interface ProbeOptions {
+    probeMcp?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function zcodeEnv(homeDir: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function selectZcodeProfile(homeDir: string, facts?: {
+    command?: string;
+    version?: string;
+    help?: string;
+    outputFormatSupported?: boolean;
+}): ZcodeProfile | undefined;
+export declare function resolveZcodeProfile(homeDir?: string, env?: NodeJS.ProcessEnv): ZcodeProfile | undefined;
+export declare function probe(homeDir?: string, opts?: ProbeOptions): Promise<AgentSnapshot>;

package/dist/probes/zcode.js

@@ -0,0 +1,140 @@
+/**
+ * ZCode probe and profile selection.
+ *
+ * ZCode has two public configuration layouts in circulation. The official
+ * source/distribution reads ~/.zcode/cli/config.json, while the installed
+ * zcode-app-cli compatibility distribution keeps runtime settings (including
+ * mcp.servers) in ~/.zcode/cli/setting.json. We select one profile before any
+ * adapter plans a write; writing both would make ZCode's native precedence
+ * ambiguous and can hide a managed MCP entry.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { probeMcpServer } from "../lib/mcpProbe.js";
+import { pathRef, readJsonFile, resolveEnvRefs, scanSkillRoot } from "../lib/probeCommon.js";
+export function zcodeEnv(homeDir, env = process.env) {
+    // A Node host can inherit Volta's selected Node binary without inheriting
+    // Volta's shim directory in PATH. Keep the user's explicit PATH order, but
+    // add the documented Volta bin location when necessary so `zcode` resolves
+    // the same way it does in their interactive terminal.
+    const voltaBin = env.VOLTA_HOME ? join(env.VOLTA_HOME, "bin") : undefined;
+    const pathParts = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    if (voltaBin && !pathParts.includes(voltaBin))
+        pathParts.unshift(voltaBin);
+    return { ...env, HOME: homeDir, ...(pathParts.length ? { PATH: pathParts.join(delimiter) } : {}) };
+}
+function configPaths(homeDir) {
+    const root = join(homeDir, ".zcode");
+    return {
+        root,
+        community: join(root, "cli", "setting.json"),
+        official: join(root, "cli", "config.json"),
+    };
+}
+function publicCommand(env) {
+    return env.TRELLIS_ZCODE_BIN?.trim() || "zcode";
+}
+function cliFacts(homeDir, env) {
+    const command = publicCommand(env);
+    const childEnv = zcodeEnv(homeDir, env);
+    try {
+        const version = execFileSync(command, ["version"], { encoding: "utf-8", timeout: 5_000, env: childEnv }).trim();
+        let help;
+        let outputFormatSupported = false;
+        try {
+            help = execFileSync(command, ["--help"], { encoding: "utf-8", timeout: 5_000, env: childEnv });
+        }
+        catch {
+            // A version identity still permits a configuration-only profile.
+        }
+        try {
+            // Some zcode-app-cli builds accept --output-format but omit it from
+            // their generated help text. --version never starts a model turn, so
+            // it is a safe capability probe for the public argument contract.
+            execFileSync(command, ["--output-format", "stream-json", "--version"], { encoding: "utf-8", timeout: 5_000, env: childEnv });
+            outputFormatSupported = true;
+        }
+        catch {
+            // Keep the false value; callers then leave execution disabled.
+        }
+        return { command, version, ...(help ? { help } : {}), outputFormatSupported };
+    }
+    catch {
+        return {};
+    }
+}
+export function selectZcodeProfile(homeDir, facts = {}) {
+    const paths = configPaths(homeDir);
+    const version = facts.version ?? "";
+    const supportsExecution = Boolean(facts.command
+        && facts.help?.includes("--prompt")
+        && facts.help.includes("--resume")
+        && (facts.help.includes("--output-format") || facts.outputFormatSupported === true));
+    if (/^zcode-app-cli\b/im.test(version) || (existsSync(paths.community) && !existsSync(paths.official))) {
+        return {
+            kind: "community-cli",
+            configPath: paths.community,
+            ...(facts.command ? { executable: facts.command } : {}),
+            ...(facts.version ? { executableVersion: facts.version } : {}),
+            supportsExecution,
+        };
+    }
+    if (facts.command || existsSync(paths.official)) {
+        return {
+            kind: facts.command ? "official" : "configuration-only",
+            configPath: paths.official,
+            ...(facts.command ? { executable: facts.command } : {}),
+            ...(facts.version ? { executableVersion: facts.version } : {}),
+            supportsExecution,
+        };
+    }
+    if (existsSync(paths.root)) {
+        return { kind: "configuration-only", configPath: paths.official, supportsExecution: false };
+    }
+    return undefined;
+}
+export function resolveZcodeProfile(homeDir = homedir(), env = process.env) {
+    // A public `zcode` binary is installed system-wide, whereas probes run
+    // against an explicit home directory. Do not let the real machine's CLI
+    // make an empty sandbox home appear to have ZCode installed; the profile
+    // must have local `.zcode` state before any executable is queried.
+    if (!existsSync(configPaths(homeDir).root))
+        return undefined;
+    return selectZcodeProfile(homeDir, cliFacts(homeDir, env));
+}
+export async function probe(homeDir = homedir(), opts = {}) {
+    const env = opts.env ?? process.env;
+    const profile = resolveZcodeProfile(homeDir, env);
+    if (!profile)
+        return { agent: "zcode", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
+    const config = readJsonFile(profile.configPath);
+    const mcpServers = Object.entries(config?.mcp?.servers ?? {}).map(([name, def]) => ({
+        name,
+        transport: def.url ? (def.type === "sse" ? "sse" : "http") : "stdio",
+    }));
+    if (opts.probeMcp) {
+        await Promise.all(Object.entries(config?.mcp?.servers ?? {}).map(async ([name, def], index) => {
+            if (def.url || !def.command)
+                return;
+            mcpServers[index].probe = await probeMcpServer({ transport: "stdio", command: def.command, args: def.args }, resolveEnvRefs(def.env, zcodeEnv(homeDir, env)));
+        }));
+    }
+    const skillRoots = [
+        scanSkillRoot(join(homeDir, ".zcode", "skills")),
+        scanSkillRoot(join(homeDir, ".agents", "skills")),
+    ].filter((root) => root !== undefined);
+    const diagnostics = [];
+    if (!profile.supportsExecution)
+        diagnostics.push("ZCode public CLI execution is unavailable; configuration-only management is supported");
+    return {
+        agent: "zcode",
+        present: true,
+        ...(profile.executableVersion ? { version: profile.executableVersion } : {}),
+        skillRoots,
+        mcpServers,
+        instructionsFile: pathRef(join(homeDir, ".zcode", "AGENTS.md")),
+        diagnostics,
+    };
+}

package/dist/sdk.d.ts

@@ -11,4 +11,4 @@
  */
 export { loadCanonicalSource } from "./core/canonical.js";
 export { ALL_AGENTS, resolveScope } from "./core/types.js";
-export type { AgentId, AgentProfile, CanonicalSource, HubConfig, McpConfig, McpServerDef, MemoryEntry, Scope, SecretsPolicy, SkillRef, Transport, } from "./core/types.js";
+export type { AgentId, AgentProfile, CapabilityDelivery, CanonicalSource, HubConfig, McpConfig, McpRuntimeConfig, McpServerDef, MemoryEntry, Scope, SecretsPolicy, SkillRef, Transport, } from "./core/types.js";