agent-trellis 0.7.0 → 0.8.2

package/dist/commands/mcpGateway.js

@@ -14,17 +14,24 @@
  * 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 { isGatewayAgent, isOAuthMcpServer, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { LocalBackend } from "../lib/gatewayBackend.js";
 import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
+import { BuiltinRegistry, createRuntimeServer, UpstreamProvider } from "../lib/mcpRuntime.js";
+import { McpStatusProvider } from "../lib/mcpStatusProvider.js";
+import { RuntimeControlProvider } from "../lib/runtimeControlProvider.js";
+import { TaskProvider } from "../lib/taskProvider.js";
+import { AgentBridgeProvider } from "../lib/agentBridgeProvider.js";
+import { RuntimeMemoryProvider } from "../lib/memoryProvider.js";
+import { SkillProvider } from "../lib/skillProvider.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" };
+const RUNTIME_CLIENT_INFO = { name: "trellis-mcp-runtime", version: "0.0.0" };
+const RUNTIME_SERVER_INFO = { name: "trellis-mcp-runtime", version: "0.0.0" };
 export function parseMcpGatewayArgs(argv) {
     const index = argv.indexOf("--agent");
     if (index === -1 || index === argv.length - 1) {
@@ -50,7 +57,16 @@ export function parseMcpGatewayArgs(argv) {
  * canonical gives the set gateway mode replaced.
  */
 export function resolveGatewayUpstreams(agentId, canonical) {
-    const direct = { ...canonical.mcp, gateway: undefined };
+    const route = canonical.mcp.routes?.[agentId];
+    const hubActive = route ? route.mode === "hub" : Boolean(canonical.mcp.hub) && !isGatewayAgent(agentId, canonical.mcp, canonical.managedAgents);
+    if (hubActive) {
+        return { upstreams: [], conflicts: [] };
+    }
+    const directRoutes = canonical.mcp.routes && route
+        ? { ...canonical.mcp.routes, [agentId]: { mode: "direct", ...(route.servers ? { servers: route.servers } : {}) } }
+        : canonical.mcp.routes;
+    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => !isOAuthMcpServer(def)));
+    const direct = { ...canonical.mcp, servers: ordinaryServers, gateway: undefined, hub: undefined, routes: directRoutes, runtime: 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
@@ -69,6 +85,15 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     };
 }
 export async function runMcpGateway(opts) {
+    return runMcpEdge(opts, CLIENT_INFO, SERVER_INFO);
+}
+/** The first-class runtime entrypoint. mcp-gateway remains a compatibility
+ * alias for existing native agent config, but both edges use the same
+ * provider registry and backend construction path. */
+export async function runMcpRuntime(opts) {
+    return runMcpEdge(opts, RUNTIME_CLIENT_INFO, RUNTIME_SERVER_INFO);
+}
+async function runMcpEdge(opts, clientInfo, serverInfo) {
     const homeDir = opts.homeDir ?? homedir();
     const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     let canonical;
@@ -90,22 +115,18 @@ export async function runMcpGateway(opts) {
         ? await opts.backendFactory(upstreams, homeDir)
         : await LocalBackend.connect(upstreams, {
             secretsPolicy: canonical.secretsPolicy,
-            clientInfo: CLIENT_INFO,
+            clientInfo,
             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 registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend), new TaskProvider(), new AgentBridgeProvider(), new UpstreamProvider(backend)]);
+    const server = createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    await waitForShutdown(backend, server);
+    await waitForShutdown(registry, server);
     return { exitCode: 0 };
 }
 /**
@@ -118,7 +139,7 @@ export async function runMcpGateway(opts) {
  * Without this, each agent session would permanently leak a gateway plus
  * its entire upstream process set (design.md D13).
  */
-function waitForShutdown(backend, server) {
+function waitForShutdown(registry, server) {
     return new Promise((resolve) => {
         let settled = false;
         const shutdown = async () => {
@@ -126,7 +147,7 @@ function waitForShutdown(backend, server) {
                 return;
             settled = true;
             try {
-                await backend.close();
+                await registry.close();
             }
             catch (err) {
                 console.error(`trellis-mcp-gateway: failed to close backend: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands/mcpImport.d.ts

@@ -0,0 +1,46 @@
+/** Safe import of standard JSON `mcpServers` exports.
+ *
+ * This is deliberately separate from `mcp add`: an export may contain real
+ * credentials, multiple differently-named copies of one server, and shapes
+ * that cannot be expressed safely for every native Agent. The source file is
+ * read-only; plans never carry secret values.
+ */
+import { type BackupSession } from "../lib/backup.js";
+import type { McpSyncReport } from "./mcp.js";
+export type McpImportAction = "create" | "already-present" | "duplicate" | "skipped" | "conflict" | "invalid-input";
+export interface McpImportItem {
+    name: string;
+    action: McpImportAction;
+    detail: string;
+}
+export interface McpImportPlan {
+    source: string;
+    items: McpImportItem[];
+}
+export declare function collectMcpImportPlan(path: string, homeDir?: string): McpImportPlan;
+export declare function applyMcpImportPlan(path: string, homeDir?: string, backup?: BackupSession): McpImportPlan;
+export interface McpImportOutcome {
+    plan: McpImportPlan;
+    sync?: McpSyncReport;
+}
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller (trellis-gui's sidecar) gets the same
+ * structured result a JSON-mode CLI run prints, without scraping
+ * stdout or re-deriving the plan-then-apply-then-cascade-sync
+ * sequencing itself. Unlike `mcp add`/`mcp remove`, `applyMcpImportPlan`
+ * already opens its own backup session unconditionally (it always has,
+ * per design.md's original survey of `openBackupSession` call sites) —
+ * no tasks.md 3.5-style fix needed here.
+ */
+export declare function applyMcpImportWithSync(path: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+}): Promise<McpImportOutcome>;
+export declare function runMcpImport(path: string | undefined, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/mcpImport.js

@@ -0,0 +1,359 @@
+/** Safe import of standard JSON `mcpServers` exports.
+ *
+ * This is deliberately separate from `mcp add`: an export may contain real
+ * credentials, multiple differently-named copies of one server, and shapes
+ * that cannot be expressed safely for every native Agent. The source file is
+ * read-only; plans never carry secret values.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadCanonicalSource, ensureGitignoreEntry, ensureShellEnvSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { openBackupSession } from "../lib/backup.js";
+import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
+import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
+const DEFAULT_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+class SkipImport extends Error {
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${field} must be a non-empty string`);
+    return value;
+}
+function stringArray(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`${field} must be an array of strings`);
+    return value;
+}
+function looksLikeCredentialKey(key) {
+    return /(token|secret|password|authorization|api.?key|bearer|credential|private.?key|headers?)/i.test(key);
+}
+function looksLikeCredentialValue(value) {
+    return /(mcpr_|ghp_|glpat-|sk-[A-Za-z0-9]{8,}|basic\s+[A-Za-z0-9+/=]{12,}|bearer\s+\S+)/i.test(value);
+}
+function exactReference(value) {
+    const match = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(value);
+    return match?.[1];
+}
+function sanitizeEnvPart(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "X";
+}
+function generatedSecretName(server, key) {
+    return `TRELLIS_${sanitizeEnvPart(server)}_${sanitizeEnvPart(key)}`;
+}
+function defaultShellRcPath(homeDir) {
+    const shell = process.env.SHELL ?? "";
+    if (shell.includes("zsh"))
+        return join(homeDir, ".zshrc");
+    if (shell.includes("bash"))
+        return join(homeDir, ".bash_profile");
+    return join(homeDir, ".profile");
+}
+function inferTransport(raw) {
+    const value = raw.transport ?? raw.type;
+    if (value === "http" || value === "sse" || value === "stdio")
+        return value;
+    if (raw.url !== undefined)
+        return "http";
+    return "stdio";
+}
+function sorted(values) {
+    return [...values].sort();
+}
+function identityArgs(def) {
+    if (!def.args)
+        return undefined;
+    if (def.command !== "npx")
+        return def.args;
+    // MCP exports often omit npx's non-interactive confirmation flag while the
+    // canonical adapter adds it. It changes prompting, not server identity.
+    const normalized = def.args.filter((arg) => arg !== "-y" && arg !== "--yes");
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeMcpRemote(serverName, args, secrets) {
+    const remoteIndex = args.indexOf("mcp-remote");
+    if (remoteIndex < 0)
+        return undefined;
+    const url = args[remoteIndex + 1];
+    if (!url || !/^https?:\/\//.test(url))
+        throw new Error(`MCP server "${serverName}" has an invalid mcp-remote URL`);
+    const headerIndex = args.indexOf("--header", remoteIndex + 2);
+    const allowed = new Set(["-y", "--yes", "mcp-remote", url, "--header", ...(headerIndex >= 0 && args[headerIndex + 1] ? [args[headerIndex + 1]] : [])]);
+    if (args.some((arg) => !allowed.has(arg)))
+        throw new Error(`MCP server "${serverName}" has unsupported mcp-remote arguments; import it manually after reviewing the shape`);
+    if (headerIndex < 0)
+        return { transport: "http", url };
+    const header = args[headerIndex + 1];
+    const match = /^Authorization:\s*Basic\s+(.+)$/i.exec(header ?? "");
+    if (!match)
+        throw new Error(`MCP server "${serverName}" has an unsupported mcp-remote header; only Basic Authorization can be migrated safely`);
+    const rawCredential = match[1];
+    const reference = exactReference(rawCredential);
+    const sourceName = generatedSecretName(serverName, "AUTHORIZATION");
+    if (reference) {
+        return { transport: "http", url, headers: { Authorization: `Basic \${${reference}}` } };
+    }
+    secrets.push({ name: sourceName, value: rawCredential });
+    return { transport: "http", url, headers: { Authorization: `Basic \${${sourceName}}` } };
+}
+/** Identity deliberately ignores secret values and generated source names but
+ * retains target env/header keys, so notion and notionApi do not collapse. */
+function semanticIdentity(def) {
+    return JSON.stringify({
+        transport: def.transport,
+        auth: def.auth,
+        command: def.command,
+        args: identityArgs(def),
+        url: def.url,
+        enabled: def.enabled,
+        agents: def.agents ? sorted(def.agents) : undefined,
+        staticEnv: def.staticEnv,
+        envKeys: sorted([...(def.env ?? []), ...Object.keys(def.envAliases ?? {})]),
+        headerKeys: sorted(Object.keys(def.headers ?? {})),
+    });
+}
+function normalizeEntry(serverName, raw, secrets) {
+    if (!isRecord(raw))
+        throw new Error(`MCP server "${serverName}" must be an object`);
+    const transport = inferTransport(raw);
+    const command = stringValue(raw.command, `${serverName}.command`);
+    const parsedArgs = stringArray(raw.args, `${serverName}.args`);
+    const args = parsedArgs && parsedArgs.length > 0 ? parsedArgs : undefined;
+    const url = stringValue(raw.url, `${serverName}.url`);
+    if (transport === "stdio" && !command)
+        throw new Error(`MCP server "${serverName}" is stdio but has no command`);
+    if ((transport === "http" || transport === "sse") && !url)
+        throw new Error(`MCP server "${serverName}" is ${transport} but has no url`);
+    if (command === "npx" && args) {
+        const remote = normalizeMcpRemote(serverName, args, secrets);
+        if (remote) {
+            if (raw.env !== undefined || raw.headers !== undefined) {
+                throw new Error(`MCP server "${serverName}" combines mcp-remote arguments with env/headers fields; import it manually after reviewing the merge`);
+            }
+            return {
+                ...remote,
+                ...(raw.auth === "oauth" ? { auth: "oauth" } : {}),
+                ...(raw.disabled === true || raw.enabled === false ? { enabled: false } : {}),
+            };
+        }
+    }
+    const env = [];
+    const envAliases = {};
+    const staticEnv = {};
+    if (raw.env !== undefined) {
+        if (!isRecord(raw.env))
+            throw new Error(`${serverName}.env must be an object`);
+        for (const [targetKey, rawValue] of Object.entries(raw.env)) {
+            const value = stringValue(rawValue, `${serverName}.env.${targetKey}`);
+            const reference = exactReference(value);
+            if (reference) {
+                if (reference === targetKey)
+                    env.push(reference);
+                else
+                    envAliases[targetKey] = reference;
+                continue;
+            }
+            if (looksLikeCredentialKey(targetKey) || looksLikeCredentialValue(value)) {
+                const sourceName = generatedSecretName(serverName, targetKey);
+                envAliases[targetKey] = sourceName;
+                secrets.push({ name: sourceName, value });
+            }
+            else {
+                staticEnv[targetKey] = value;
+            }
+        }
+    }
+    const headers = {};
+    if (raw.headers !== undefined) {
+        if (!isRecord(raw.headers))
+            throw new Error(`${serverName}.headers must be an object`);
+        for (const [key, rawValue] of Object.entries(raw.headers)) {
+            const value = stringValue(rawValue, `${serverName}.headers.${key}`);
+            const reference = exactReference(value);
+            if (reference) {
+                headers[key] = `\${${reference}}`;
+                continue;
+            }
+            throw new Error(`MCP server "${serverName}" has a literal header "${key}"; move it to an environment variable before importing`);
+        }
+    }
+    const inlineText = [command, ...(args ?? []), url].filter(Boolean).join(" ");
+    if (looksLikeCredentialValue(inlineText)) {
+        throw new Error(`MCP server "${serverName}" has a credential embedded in command, args, or url; importer will not store it in canonical`);
+    }
+    for (const arg of args ?? []) {
+        if (/^(\/Users\/|\/home\/|[A-Za-z]:[\\/])/.test(arg) && !existsSync(arg)) {
+            throw new SkipImport(`MCP server "${serverName}" references missing absolute path "${arg}"; skipped as unavailable on this machine`);
+        }
+    }
+    const disabled = raw.disabled === true || raw.enabled === false;
+    const auth = raw.auth === "oauth" ? "oauth" : undefined;
+    return {
+        transport,
+        ...(auth ? { auth } : {}),
+        ...(command ? { command } : {}),
+        ...(args ? { args } : {}),
+        ...(url ? { url } : {}),
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+        ...(env.length > 0 ? { env } : {}),
+        ...(Object.keys(envAliases).length > 0 ? { envAliases } : {}),
+        ...(Object.keys(staticEnv).length > 0 ? { staticEnv } : {}),
+        ...(disabled ? { enabled: false } : {}),
+    };
+}
+function readExport(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed.mcpServers))
+        throw new Error(`MCP import requires a top-level "mcpServers" object in ${path}`);
+    return parsed.mcpServers;
+}
+function publicPlan(plan) {
+    return { source: plan.source, items: plan.items };
+}
+export function collectMcpImportPlan(path, homeDir = homedir()) {
+    return publicPlan(collectInternalPlan(path, homeDir));
+}
+function collectInternalPlan(path, homeDir) {
+    if (!existsSync(path))
+        throw new Error(`MCP import file does not exist: ${path}`);
+    const source = readExport(path);
+    const canonical = loadCanonicalSource(homeDir);
+    const existingByIdentity = new Map(Object.entries(canonical.mcp.servers).map(([name, def]) => [semanticIdentity(def), name]));
+    const additions = [];
+    const secrets = [];
+    const items = [];
+    const envFilePath = canonical.secretsPolicy.envFile ?? join(homeDir, ".trellis", "mcp", "servers.local.env");
+    const existingSecrets = existsSync(envFilePath) ? parseDotenv(readFileSync(envFilePath, "utf8")) : {};
+    for (const [name, raw] of Object.entries(source)) {
+        let def;
+        const beforeSecretCount = secrets.length;
+        try {
+            def = normalizeEntry(name, raw, secrets);
+        }
+        catch (err) {
+            secrets.splice(beforeSecretCount);
+            if (err instanceof SkipImport) {
+                items.push({ name, action: "skipped", detail: err.message });
+                continue;
+            }
+            items.push({ name, action: "conflict", detail: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        const identity = semanticIdentity(def);
+        const existing = canonical.mcp.servers[name];
+        if (existing) {
+            secrets.splice(beforeSecretCount);
+            items.push(existing && semanticIdentity(existing) === identity
+                ? { name, action: "already-present", detail: "canonical entry is already semantically identical; existing credentials are preserved" }
+                : { name, action: "conflict", detail: `servers.yaml already has "${name}" with different non-secret settings — left unchanged` });
+            continue;
+        }
+        const duplicate = existingByIdentity.get(identity) ?? additions.find((item) => semanticIdentity(item.def) === identity)?.name;
+        if (duplicate) {
+            secrets.splice(beforeSecretCount);
+            items.push({ name, action: "duplicate", detail: `same non-secret MCP definition is already represented by "${duplicate}" — not added` });
+            continue;
+        }
+        const newSecrets = secrets.slice(beforeSecretCount);
+        const secretConflict = newSecrets.find((secret) => Object.hasOwn(existingSecrets, secret.name) && existingSecrets[secret.name] !== secret.value);
+        if (secretConflict) {
+            secrets.splice(beforeSecretCount);
+            items.push({ name, action: "conflict", detail: `local secret variable "${secretConflict.name}" already has a different value — not overwritten` });
+            continue;
+        }
+        additions.push({ name, def });
+        items.push({ name, action: "create", detail: `will add to canonical and extract ${newSecrets.length} credential value(s) to the ignored local secrets file` });
+    }
+    return { source: path, items, additions, secrets, envFilePath, envFileIsDefault: !canonical.secretsPolicy.envFile };
+}
+function applySecrets(plan, homeDir, backup) {
+    if (plan.secrets.length === 0)
+        return;
+    if (plan.envFileIsDefault)
+        ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env", backup);
+    for (const secret of plan.secrets) {
+        const secretResult = writeLocalSecretValue(plan.envFilePath, secret.name, secret.value, backup);
+        if (secretResult === "conflict")
+            throw new Error(`local secret variable "${secret.name}" changed during import — refusing to overwrite it`);
+        const policyResult = writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName: secret.name, envFilePath: DEFAULT_ENV_FILE_TILDE }, backup);
+        if (!policyResult.ok)
+            throw new Error(policyResult.error);
+    }
+    ensureShellEnvSource(defaultShellRcPath(homeDir), plan.envFilePath, backup);
+}
+export function applyMcpImportPlan(path, homeDir = homedir(), backup) {
+    const plan = collectInternalPlan(path, homeDir);
+    const ownSession = backup ?? openBackupSession(homeDir, "mcp-import");
+    try {
+        for (const addition of plan.additions) {
+            const result = upsertServerYaml(join(homeDir, ".trellis", "mcp", "servers.yaml"), addition.name, addition.def, ownSession);
+            if (!result.ok)
+                throw new Error(result.error);
+        }
+        applySecrets(plan, homeDir, ownSession);
+    }
+    catch (error) {
+        // Keep the manifest even on failure so the caller can use the normal
+        // `trellis rollback` path to undo writes that happened before the error.
+        if (!backup)
+            ownSession.finalize();
+        throw error;
+    }
+    if (!backup)
+        ownSession.finalize();
+    return publicPlan(plan);
+}
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller (trellis-gui's sidecar) gets the same
+ * structured result a JSON-mode CLI run prints, without scraping
+ * stdout or re-deriving the plan-then-apply-then-cascade-sync
+ * sequencing itself. Unlike `mcp add`/`mcp remove`, `applyMcpImportPlan`
+ * already opens its own backup session unconditionally (it always has,
+ * per design.md's original survey of `openBackupSession` call sites) —
+ * no tasks.md 3.5-style fix needed here.
+ */
+export async function applyMcpImportWithSync(path, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = opts.dryRun ? collectMcpImportPlan(path, homeDir) : applyMcpImportPlan(path, homeDir);
+    const failed = plan.items.some((item) => item.action === "conflict" || item.action === "invalid-input");
+    const changed = plan.items.some((item) => item.action === "create");
+    let syncReport;
+    if (!failed && changed && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runMcpImport(path, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (!path) {
+        console.error("Usage: trellis mcp import <json-file> [--dry-run]");
+        return { exitCode: 1 };
+    }
+    try {
+        const { plan: result, sync: syncReport } = await applyMcpImportWithSync(path, { homeDir, dryRun: opts.dryRun });
+        const failed = result.items.some((item) => item.action === "conflict" || item.action === "invalid-input");
+        if (opts.json)
+            console.log(JSON.stringify(syncReport ? { ...result, sync: syncReport } : result, null, 2));
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}mcp import ${path}`);
+            for (const item of result.items)
+                console.log(`  [${item.action}] ${item.name} — ${item.detail}`);
+            if (syncReport)
+                printMcpSyncReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: failed || syncConflict ? 1 : 0 };
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+}

package/dist/commands/memory.d.ts

@@ -12,8 +12,21 @@
  * server process — both are plain file operations, same posture as
  * every other Trellis write.
  */
-import type { McpServerDef } from "../core/types.js";
+import type { AgentId, McpConfig, McpServerDef } from "../core/types.js";
+import type { BackupSession } from "../lib/backup.js";
 import { type MemoryExtractionPlan, type MemorySyncPlan } from "../lib/memoryGraph.js";
+export interface MemoryListEntry {
+    name: string;
+    scope: readonly AgentId[];
+}
+/** Canonical `memories/*.md` profile files — the list `trellis-gui`'s
+ * Memory view reads (tasks.md 6.2), mirroring `collectSkillList`'s
+ * shape exactly (skill.ts) since both are "canonical files with a
+ * resolved managed-agent scope" lists. Distinct from this file's own
+ * `MEMORY_SERVER_NAME` sync/extraction pipeline below, which is about
+ * the separate shared-Memory-MCP-server knowledge graph, not these
+ * per-topic markdown files. */
+export declare function collectMemoryList(homeDir?: string): MemoryListEntry[];
 /** 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. */
@@ -32,6 +45,7 @@ export interface RunMemorySyncOptions {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
+    selectedMemoryNames?: readonly string[];
 }
 export type MemorySyncResult = {
     configured: true;
@@ -41,8 +55,8 @@ export type MemorySyncResult = {
     configured: false;
     reason: string;
 };
-export declare function collectMemorySyncResult(homeDir?: string): MemorySyncResult;
-export declare function applyMemorySync(result: MemorySyncResult): void;
+export declare function collectMemorySyncResult(homeDir?: string, selectedMemoryNames?: readonly string[], mcpOverride?: McpConfig): MemorySyncResult;
+export declare function applyMemorySync(result: MemorySyncResult, backup?: BackupSession): void;
 /**
  * Extracted from `runMemorySync` (trellis-onboard-mcp-memory) so
  * `onboard`'s own chained output can print this stage in the exact same

package/dist/commands/memory.js

@@ -16,7 +16,22 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
 import { parseMemoryGraph, planMemoryExtraction, planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
+/** Canonical `memories/*.md` profile files — the list `trellis-gui`'s
+ * Memory view reads (tasks.md 6.2), mirroring `collectSkillList`'s
+ * shape exactly (skill.ts) since both are "canonical files with a
+ * resolved managed-agent scope" lists. Distinct from this file's own
+ * `MEMORY_SERVER_NAME` sync/extraction pipeline below, which is about
+ * the separate shared-Memory-MCP-server knowledge graph, not these
+ * per-topic markdown files. */
+export function collectMemoryList(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return canonical.memories.map((memory) => ({
+        name: memory.name,
+        scope: resolveScope(memory.scope, canonical.managedAgents),
+    }));
+}
 /** 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. */
@@ -50,9 +65,9 @@ export const DEFAULT_MEMORY_SERVER_DEF = {
  * about which graph file they're reading/writing
  * (trellis-memory-extraction).
  */
-function resolveMemoryServerGraphPath(homeDir) {
+function resolveMemoryServerGraphPath(homeDir, mcpOverride) {
     const canonical = loadCanonicalSource(homeDir);
-    const server = canonical.mcp.servers[MEMORY_SERVER_NAME];
+    const server = (mcpOverride ?? canonical.mcp).servers[MEMORY_SERVER_NAME];
     const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
     if (!server || !rawPath) {
         return {
@@ -62,20 +77,24 @@ function resolveMemoryServerGraphPath(homeDir) {
     }
     return { configured: true, graphPath: rawPath.replace(/^~(?=$|\/)/, homeDir) };
 }
-export function collectMemorySyncResult(homeDir = homedir()) {
-    const lookup = resolveMemoryServerGraphPath(homeDir);
+export function collectMemorySyncResult(homeDir = homedir(), selectedMemoryNames, mcpOverride) {
+    const lookup = resolveMemoryServerGraphPath(homeDir, mcpOverride);
     if (!lookup.configured)
         return lookup;
     const canonical = loadCanonicalSource(homeDir);
     const currentContent = existsSync(lookup.graphPath) ? readFileSync(lookup.graphPath, "utf-8") : undefined;
-    const plan = planMemorySync(canonical, currentContent);
+    const plan = planMemorySync(canonical, currentContent, selectedMemoryNames);
     return { configured: true, graphPath: lookup.graphPath, plan };
 }
-export function applyMemorySync(result) {
+export function applyMemorySync(result, backup) {
     if (!result.configured || !result.plan.nextGraph)
         return;
     mkdirSync(dirname(result.graphPath), { recursive: true });
-    writeFileSync(result.graphPath, renderMemoryGraph(result.plan.nextGraph));
+    const content = renderMemoryGraph(result.plan.nextGraph);
+    if (backup)
+        backup.writeFile(result.graphPath, content);
+    else
+        writeFileSync(result.graphPath, content);
 }
 /**
  * Extracted from `runMemorySync` (trellis-onboard-mcp-memory) so
@@ -101,7 +120,7 @@ export function runMemorySync(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
     try {
-        result = collectMemorySyncResult(homeDir);
+        result = collectMemorySyncResult(homeDir, opts.selectedMemoryNames);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));