agent-trellis 0.5.2 → 0.6.2

package/dist/commands/mcpGateway.js

@@ -0,0 +1,148 @@
+/**
+ * `trellis mcp-gateway --agent <id>` — the stdio MCP server an agent
+ * spawns in gateway mode (trellis-mcp-gateway-hosting).
+ *
+ * Not a user-facing command in the usual sense: nobody types this. An
+ * agent's own MCP client spawns it exactly the way it spawns any other
+ * stdio server, talks to it for the session, and closes the pipe on exit
+ * (design.md D2). There is no daemon, no lifecycle command, and nothing
+ * for the user to notice.
+ *
+ * This file depends on `GatewayBackend` and nothing below it — no
+ * connection, no transport, no server definition (design.md D11). That is
+ * what lets v2 point the same stdio edge at one shared service instead of
+ * an in-process backend without this file, or any agent's config,
+ * changing.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { LocalBackend } from "../lib/gatewayBackend.js";
+import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { ALL_AGENTS } from "../core/types.js";
+const CLIENT_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+const SERVER_INFO = { name: "trellis-mcp-gateway", version: "0.0.0" };
+export function parseMcpGatewayArgs(argv) {
+    const index = argv.indexOf("--agent");
+    if (index === -1 || index === argv.length - 1) {
+        return { error: `mcp-gateway requires --agent <${ALL_AGENTS.join("|")}>` };
+    }
+    const value = argv[index + 1];
+    if (!ALL_AGENTS.includes(value)) {
+        return { error: `unknown agent "${value}" — expected one of ${ALL_AGENTS.join(", ")}` };
+    }
+    return { agentId: value };
+}
+/**
+ * The in-scope upstream set for this agent, resolved through the very same
+ * `resolveMcpPlan` that direct mode uses — per-server `agents:` scope,
+ * `enabled: false`, host-injected collisions, literal-secret refusals and
+ * unresolved `env` names all apply here identically, because it is
+ * literally the same function (design.md D6).
+ *
+ * The one thing that must be stripped is gateway mode itself: asking
+ * `resolveMcpPlan` for this agent's plan while gateway mode is on would
+ * answer "one entry, pointing at the gateway" — the gateway being told to
+ * connect to itself. Resolving against a gateway-less view of the same
+ * canonical gives the set gateway mode replaced.
+ */
+export function resolveGatewayUpstreams(agentId, canonical) {
+    const direct = { ...canonical.mcp, gateway: undefined };
+    // The managed set is passed through unchanged, so an unmanaged agent
+    // reaches nothing. Being spawned is NOT treated as consent here, which
+    // is a deliberate divergence from `src/pi-bridge/index.ts` (which passes
+    // ALL_AGENTS on the grounds that pi loading the extension is itself the
+    // signal). The triggers differ: pi's bridge only exists on disk because
+    // Trellis symlinked it into pi's own directory while pi was managed, so
+    // its presence IS the marker. A gateway entry, by contrast, outlives
+    // un-managing — it sits in the agent's config until a later sync's
+    // ownership-gated removal clears it. Serving that stale entry would hand
+    // every server, and every secret resolved into it, to the one agent the
+    // user just said to stop involving.
+    const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    return {
+        upstreams: desired.map(({ name, def }) => ({ name, def })),
+        conflicts: conflicts.map((conflict) => conflict.message),
+    };
+}
+export async function runMcpGateway(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (err) {
+        // stderr, never stdout: stdout IS the MCP protocol stream here, and a
+        // stray line on it corrupts the agent's parser rather than informing
+        // anyone.
+        console.error(`trellis-mcp-gateway: ${err instanceof Error ? err.message : String(err)}`);
+        return { exitCode: 1 };
+    }
+    const { upstreams, conflicts } = resolveGatewayUpstreams(opts.agentId, canonical);
+    for (const message of conflicts) {
+        console.error(`trellis-mcp-gateway: ${message}`);
+    }
+    const backend = opts.backendFactory
+        ? await opts.backendFactory(upstreams, homeDir)
+        : await LocalBackend.connect(upstreams, {
+            secretsPolicy: canonical.secretsPolicy,
+            clientInfo: CLIENT_INFO,
+            connectTimeoutMs,
+            // Enables silent OAuth refresh-before-connect. Never an
+            // interactive grant: that is `trellis mcp auth`'s job, and this
+            // process has no terminal to run one in (design.md D9).
+            homeDir,
+        });
+    const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await backend.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await backend.callTool(request.params.name, request.params.arguments);
+        return result;
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await waitForShutdown(backend, server);
+    return { exitCode: 0 };
+}
+/**
+ * Teardown on client disconnect — the piece neither layer below provides.
+ *
+ * `StdioServerTransport.start()` registers listeners for `'data'` and
+ * `'error'` only, so stdin reaching EOF never reaches `onclose`; and POSIX
+ * re-parents an orphan to launchd rather than killing it, while this
+ * process's own event loop is held open by every upstream it connected.
+ * Without this, each agent session would permanently leak a gateway plus
+ * its entire upstream process set (design.md D13).
+ */
+function waitForShutdown(backend, server) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const shutdown = async () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                await backend.close();
+            }
+            catch (err) {
+                console.error(`trellis-mcp-gateway: failed to close backend: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            try {
+                await server.close();
+            }
+            catch {
+                // best-effort; the process is going away regardless
+            }
+            resolve();
+        };
+        process.stdin.on("end", shutdown);
+        process.stdin.on("close", shutdown);
+        for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+            process.once(signal, shutdown);
+        }
+    });
+}

package/dist/commands/memory.d.ts

@@ -12,7 +12,22 @@
  * server process — both are plain file operations, same posture as
  * every other Trellis write.
  */
+import type { McpServerDef } from "../core/types.js";
 import { type MemoryExtractionPlan, type MemorySyncPlan } from "../lib/memoryGraph.js";
+/** Exported so `onboard` (`trellis onboard --memory on|off`,
+ * trellis-onboard-mcp-mode) can look up and write this same entry
+ * without hardcoding the name a second time. */
+export declare const MEMORY_SERVER_NAME = "memory";
+/**
+ * The literal definition `trellis onboard --memory on` writes — the
+ * same shape `schema/servers.example.yaml`'s commented-out `memory:`
+ * block documents, now a real, code-owned constant instead of the only
+ * place this shape existed being prose a user hand-transcribes
+ * (trellis-onboard-mcp-mode design.md D9). `MEMORY_FILE_PATH` must be
+ * set explicitly — see `resolveMemoryServerGraphPath`'s own comment for
+ * why an unset one isn't safe to leave to the server's own default.
+ */
+export declare const DEFAULT_MEMORY_SERVER_DEF: McpServerDef;
 export interface RunMemorySyncOptions {
     homeDir?: string;
     json?: boolean;

package/dist/commands/memory.js

@@ -17,7 +17,25 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { parseMemoryGraph, planMemoryExtraction, planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
-const MEMORY_SERVER_NAME = "memory";
+/** Exported so `onboard` (`trellis onboard --memory on|off`,
+ * trellis-onboard-mcp-mode) can look up and write this same entry
+ * without hardcoding the name a second time. */
+export const MEMORY_SERVER_NAME = "memory";
+/**
+ * The literal definition `trellis onboard --memory on` writes — the
+ * same shape `schema/servers.example.yaml`'s commented-out `memory:`
+ * block documents, now a real, code-owned constant instead of the only
+ * place this shape existed being prose a user hand-transcribes
+ * (trellis-onboard-mcp-mode design.md D9). `MEMORY_FILE_PATH` must be
+ * set explicitly — see `resolveMemoryServerGraphPath`'s own comment for
+ * why an unset one isn't safe to leave to the server's own default.
+ */
+export const DEFAULT_MEMORY_SERVER_DEF = {
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-memory"],
+    staticEnv: { MEMORY_FILE_PATH: "~/.trellis/memories/graph.jsonl" },
+};
 /**
  * Looks up `mcp.servers["memory"]` specifically (matching `schema/
  * servers.example.yaml`'s own naming convention for the default shared-

package/dist/commands/migrate.d.ts

@@ -17,6 +17,10 @@ export interface MigratePlanItem {
     name: string;
     action: MigrateAction;
     detail: string;
+    /** Only set (and only meaningful) when `action === "conflict"`: the
+     * concrete next action, distinct from `detail`'s restatement of why
+     * (trellis-onboard-closed-loop design.md D7). */
+    remediation?: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;

package/dist/commands/migrate.js

@@ -15,6 +15,7 @@ import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
 import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+import { findLiteralSecret } from "../adapters/mcpPlan.js";
 import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
@@ -44,7 +45,13 @@ function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
         case "already-present":
             return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
         case "conflict":
-            return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+            return {
+                kind: "skill",
+                name,
+                action: "conflict",
+                detail: `canonical skills/${name}/ already exists with different content — resolve by hand`,
+                remediation: `compare \`~/.trellis/skills/${name}/\` against the source agent's copy and either update canonical by hand or delete the source's copy if canonical's is the one to keep`,
+            };
     }
 }
 function planInstructions(snapshot, canonicalAgentsMd) {
@@ -58,7 +65,13 @@ function planInstructions(snapshot, canonicalAgentsMd) {
         sourceContent = readFileSync(snapshot.instructionsFile.path, "utf-8");
     }
     catch (err) {
-        return { kind: "instructions", name: "agents.md", action: "conflict", detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}` };
+        return {
+            kind: "instructions",
+            name: "agents.md",
+            action: "conflict",
+            detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: `check that ${snapshot.instructionsFile.path} exists and is readable, then re-run migrate`,
+        };
     }
     if (!existsSync(canonicalAgentsMd)) {
         return { kind: "instructions", name: "agents.md", action: "create", detail: "canonical agents.md does not exist yet", sourceContent };
@@ -70,7 +83,13 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     if (current === sourceContent) {
         return { kind: "instructions", name: "agents.md", action: "already-migrated", detail: "canonical content is byte-identical" };
     }
-    return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
+    return {
+        kind: "instructions",
+        name: "agents.md",
+        action: "conflict",
+        detail: "canonical agents.md already has different real content — resolve by hand",
+        remediation: `compare \`~/.trellis/agents.md\` against ${snapshot.instructionsFile.path} and either merge by hand or delete whichever copy you don't want to keep`,
+    };
 }
 /**
  * True when `existing` and `def` differ ONLY in which of `env`/
@@ -92,6 +111,23 @@ export function isSafeReclassification(existing, def) {
     return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
 }
 function planMcpServer(name, def, existing) {
+    // Checked first, before any comparison against `existing`: a source
+    // agent's real config holding a literal credential must never reach
+    // canonical at all, regardless of whether canonical already has
+    // something for this name. `resolveMcpPlan`'s own guard only protects
+    // the sync-OUT boundary (canonical -> agent) — this is the matching
+    // guard for the migrate-IN boundary (agent -> canonical), the gap a
+    // real `mcp-router` token in a real `kiro` config exposed.
+    const secretLabel = findLiteralSecret(def);
+    if (secretLabel) {
+        return {
+            kind: "mcp",
+            name,
+            action: "conflict",
+            detail: `refusing to import MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — canonical must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
+            remediation: `move the real value in the source agent's own config to an environment variable (or your secrets manager), leaving only a name behind, then re-run migrate — canonical never accepts a literal credential, even briefly`,
+        };
+    }
     if (existing === undefined) {
         return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
     }
@@ -101,7 +137,13 @@ function planMcpServer(name, def, existing) {
     if (isSafeReclassification(existing, def)) {
         return { kind: "mcp", name, action: "reclassify", detail: "same value, only its internal classification changed — safe to update", mcpDef: def };
     }
-    return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
+    return {
+        kind: "mcp",
+        name,
+        action: "conflict",
+        detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand`,
+        remediation: `compare the source agent's own definition for "${name}" against \`~/.trellis/mcp/servers.yaml\` and update canonical by hand if the source's is the one to keep`,
+    };
 }
 /**
  * `only` restricts which kind(s) are even considered — not a post-hoc

package/dist/commands/onboard.d.ts

@@ -18,7 +18,9 @@ import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
 import type { MemorySyncResult } from "./memory.js";
+import type { DoctorReport } from "./doctor.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
+import type { VerdictItem } from "./onboardVerdict.js";
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -44,6 +46,20 @@ export interface RunOnboardOptions {
      * the literal string "none" for "add nothing new this run" — distinct
      * from omitting the flag, which requires a prompt or refuses. */
     manage?: string;
+    /** Non-interactive MCP-mode choice (trellis-onboard-mcp-mode). Omitted
+     * leaves whatever canonical already has untouched and prompts for
+     * nothing — "no change requested," not "please choose" (design.md
+     * D1), unlike `agent`/`manage` above. */
+    mcpMode?: string;
+    /** Required when `mcpMode === "hub"`; refused if given otherwise. */
+    hubUrl?: string;
+    /** Optional when `mcpMode === "gateway"` (comma-separated agent ids;
+     * omitted = every managed agent); refused if given otherwise. */
+    gatewayAgents?: string;
+    /** Non-interactive shared-memory-server toggle: `"on"` or `"off"`.
+     * Omitted leaves whatever's already configured untouched — same
+     * no-prompt posture as `mcpMode` (design.md D12). */
+    memory?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */
@@ -64,6 +80,10 @@ export interface RunOnboardOptions {
      * answer — "skip migrate for this run" (design.md D6) — distinct from
      * `source` being unresolved at all. */
     promptForMigrateCategories?: (source: OnboardAgentSummary) => Promise<MigrateKind[]>;
+    /** Test-only: replaces the real end-of-`--dry-run` "apply now?" picker
+     * (design.md D9). `true` means "apply for real", matching what
+     * accepting the real picker's "Yes, apply now" option means. */
+    promptToApply?: () => Promise<boolean>;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -90,13 +110,60 @@ export interface OnboardResult {
     migrateSkipped?: string;
     syncReport?: SyncReport;
     mcpSyncReport?: McpSyncReport;
+    /**
+     * The self-verification re-plan (design.md D2b): a dry-run re-plan of
+     * `sync`/`mcp sync`, run immediately after their real apply, against
+     * the state that apply just wrote. Absent on `--dry-run` (nothing was
+     * written, so nothing to verify) and on every early-refusal path.
+     * Present, and empty, on a real run whose write actually held.
+     */
+    syncVerification?: SyncReport;
+    mcpSyncVerification?: McpSyncReport;
     memorySyncResult?: MemorySyncResult;
     secretsAuditReport?: SecretsAuditReport;
+    /**
+     * A broader, whole-machine health scan — the same detectors
+     * `trellis doctor` itself runs, against every agent (not scoped to
+     * `managedAgents`, design.md D3), never with MCP handshake probing
+     * (design.md D4). Complementary to, and distinct from, the
+     * write-verification above: this cannot itself prove a write took
+     * effect (it never reads canonical), only that something looks
+     * inconsistent across agents independent of this run.
+     */
+    doctorReport?: DoctorReport;
+    /**
+     * The resolved MCP mode after this run (trellis-onboard-mcp-mode
+     * design.md D7) — `current` reflects canonical's state whether or not
+     * this run changed it, `changed` is `true` only when `--mcp-mode` was
+     * given and differed from what canonical had before this run. Absent
+     * on every early-refusal path before mode resolution is reached.
+     */
+    mcpMode?: {
+        current: "direct" | "hub" | "gateway";
+        previous: "direct" | "hub" | "gateway";
+        changed: boolean;
+    };
+    /** The resolved shared-memory-server state after this run, mirroring
+     * `mcpMode` (design.md D13). */
+    memory?: {
+        current: "on" | "off";
+        previous: "on" | "off";
+        changed: boolean;
+    };
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and
      * text output both surface, so a machine caller doesn't have to
      * hardcode them a second time. */
     installHints?: Record<AgentId, string>;
+    /**
+     * Every stage's conflicts and findings, normalized to one shape
+     * (trellis-onboard-closed-loop design.md D5) — the single source
+     * `runOnboard`'s exit code and the terminal verdict block both derive
+     * from, so the two can never disagree. Always present, empty on a
+     * fully clean run (including refusal paths, where it reflects
+     * whatever partial data was collected before the refusal).
+     */
+    verdict: VerdictItem[];
 }
 export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
 export declare function runOnboard(opts?: RunOnboardOptions): Promise<{