agent-trellis 0.7.0 → 0.8.0

package/dist/commands/rollback.js

@@ -134,7 +134,10 @@ async function restoreOperation(homeDir, runId, op) {
 }
 export async function applyRollbackPlan(homeDir, runId, manifest, items) {
     const restorePaths = new Set(items.filter((i) => i.action === "restore").map((i) => i.path));
-    for (const op of manifest.operations) {
+    // Restore in reverse write order. A single onboarding transaction may
+    // update servers.yaml several times (mode, memory, routes); replaying
+    // restores forward would leave the file at an intermediate snapshot.
+    for (const op of [...manifest.operations].reverse()) {
         if (!restorePaths.has(op.path))
             continue;
         await restoreOperation(homeDir, runId, op);

package/dist/commands/skill.d.ts

@@ -8,6 +8,23 @@
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
 import type { AgentId } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
+export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
+export interface BuiltinSkillUpdatePlan {
+    name: "trellis-runtime";
+    action: BuiltinSkillUpdateAction;
+    detail: string;
+    path: string;
+}
+export declare function collectBuiltinSkillUpdatePlan(homeDir?: string): BuiltinSkillUpdatePlan;
+export declare function applyBuiltinSkillUpdatePlan(plan: BuiltinSkillUpdatePlan, backup?: BackupSession): void;
+export declare function runSkillUpdateBuiltin(opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];

package/dist/commands/skill.js

@@ -7,16 +7,56 @@
  * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
  * symlinkPlan.ts`'s pre-existing stale-symlink removal.
  */
-import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
+import { openBackupSession } from "../lib/backup.js";
+function builtinSkillTemplate() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
+}
+export function collectBuiltinSkillUpdatePlan(homeDir = homedir()) {
+    const path = join(homeDir, ".trellis", "skills", "trellis-runtime", "SKILL.md");
+    if (!existsSync(path))
+        return { name: "trellis-runtime", action: "create", detail: "will install the package-owned Runtime Skill", path };
+    if (readFileSync(path, "utf8") === builtinSkillTemplate())
+        return { name: "trellis-runtime", action: "already-current", detail: "package-owned Runtime Skill is already current", path };
+    return { name: "trellis-runtime", action: "update", detail: "will refresh the package-owned Runtime Skill; existing Agent symlinks will see the update", path };
+}
+export function applyBuiltinSkillUpdatePlan(plan, backup) {
+    if (plan.action === "already-current")
+        return;
+    const content = builtinSkillTemplate();
+    mkdirSync(dirname(plan.path), { recursive: true });
+    if (backup)
+        backup.writeFile(plan.path, content);
+    else
+        writeFileSync(plan.path, content);
+}
+export function runSkillUpdateBuiltin(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectBuiltinSkillUpdatePlan(homeDir);
+    if (!opts.dryRun && plan.action !== "already-current") {
+        const backup = openBackupSession(homeDir, "skill-update-builtin");
+        applyBuiltinSkillUpdatePlan(plan, backup);
+        backup.finalize();
+    }
+    if (opts.json)
+        console.log(JSON.stringify(plan, null, 2));
+    else
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill update-builtin\n  [${plan.action}] ${plan.detail}`);
+    return { exitCode: 0 };
+}
 export function collectSkillList(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
-    return canonical.skills.map((skill) => ({
+    return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
     }));
@@ -37,6 +77,9 @@ export function runSkillList(opts = {}) {
     return { exitCode: 0 };
 }
 export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    if (isBuiltinSkillName(name)) {
+        return { name, action: "conflict", detail: `"${name}" is a Trellis package-owned Skill and cannot be replaced with skill add` };
+    }
     const skillFile = findSkillFile(fromPath);
     if (!skillFile) {
         return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
@@ -77,6 +120,8 @@ export function runSkillAdd(name, fromPath, opts = {}) {
     return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
 }
 export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    if (isBuiltinSkillName(name))
+        return { name, action: "not-found" };
     const dir = join(homeDir, ".trellis", "skills", name);
     return { name, action: existsSync(dir) ? "removed" : "not-found" };
 }

package/dist/commands/sync.js

@@ -11,12 +11,14 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
+import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
+    "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — an agent present on this
  * machine but not managed gets no adapter at all, not a zero-item plan

package/dist/core/canonical.d.ts

@@ -4,7 +4,8 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef } from "./types.js";
+import type { BackupSession } from "../lib/backup.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
@@ -27,10 +28,10 @@ export type ServersYamlWriteResult = {
     ok: false;
     error: string;
 };
-export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
+export declare function removeServerYaml(path: string, name: string, backup?: BackupSession): ServersYamlWriteResult;
 /**
  * `trellis onboard --mcp-mode <value>` (trellis-onboard-mcp-mode) —
  * everything needed to select or clear the top-level `hub`/`gateway`
@@ -56,7 +57,14 @@ export type McpMode = {
  * starter file). Selecting one mode always clears the other two
  * (design.md D3) — never left for the caller to remember.
  */
-export declare function writeMcpModeYaml(path: string, mode: McpMode): ServersYamlWriteResult;
+export declare function writeMcpModeYaml(path: string, mode: McpMode, backup?: BackupSession): ServersYamlWriteResult;
+export type McpRoutesWriteResult = ServersYamlWriteResult;
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export declare function writeMcpRoutesYaml(path: string, routes: Partial<Record<AgentId, McpRoute>>, backup?: BackupSession): McpRoutesWriteResult;
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export declare function writeMcpRuntimeDeliveryYaml(path: string, delivery: Partial<Record<AgentId, CapabilityDelivery>>, backup?: BackupSession): ServersYamlWriteResult;
 export type SecretsPolicyWriteResult = {
     ok: true;
 } | {
@@ -78,7 +86,7 @@ export type SecretsPolicyWriteResult = {
 export declare function writeSecretsPolicyExtraction(path: string, extraction: {
     varName: string;
     envFilePath: string;
-}): SecretsPolicyWriteResult;
+}, backup?: BackupSession): SecretsPolicyWriteResult;
 /**
  * Ensures one exact line is present in a `.gitignore` file, creating the
  * file if it doesn't exist yet — idempotent (a no-op if the line is
@@ -89,7 +97,7 @@ export declare function writeSecretsPolicyExtraction(path: string, extraction: {
  * init`'s own bootstrap, so a machine that never extracts a secret never
  * gains this file at all.
  */
-export declare function ensureGitignoreEntry(gitignorePath: string, line: string): void;
+export declare function ensureGitignoreEntry(gitignorePath: string, line: string, backup?: BackupSession): void;
 /**
  * Ensures a shell rc file sources the local secrets env file on every new
  * shell — one generic pointer block, appended once, idempotent (detected
@@ -102,7 +110,7 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * lines `parseDotenv` already expects, so that format never needs an
  * `export` prefix of its own.
  */
-export declare function ensureShellEnvSource(rcPath: string, envFilePath: string): void;
+export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use

package/dist/core/canonical.js

@@ -89,8 +89,39 @@ function loadServersYaml(path) {
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
         gateway: fromGatewayYaml(parsed.gateway),
+        routes: fromRoutesYaml(parsed.routes),
+        runtime: fromRuntimeYaml(parsed.runtime),
     };
 }
+function fromRuntimeYaml(runtime) {
+    if (!runtime?.delivery)
+        return undefined;
+    const delivery = {};
+    for (const [rawAgent, rawDelivery] of Object.entries(runtime.delivery)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (rawDelivery !== "native" && rawDelivery !== "mcp" && rawDelivery !== "both")
+            continue;
+        delivery[rawAgent] = rawDelivery;
+    }
+    return Object.keys(delivery).length > 0 ? { delivery } : undefined;
+}
+function fromRoutesYaml(routes) {
+    if (!routes)
+        return undefined;
+    const out = {};
+    for (const [rawAgent, rawRoute] of Object.entries(routes)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (!rawRoute?.mode || !["direct", "gateway", "hub"].includes(rawRoute.mode))
+            continue;
+        out[rawAgent] = {
+            mode: rawRoute.mode,
+            ...(rawRoute.servers ? { servers: rawRoute.servers } : {}),
+        };
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 /**
  * A `gateway:` block with no `enabled` key reads as off, not as on — the
  * only safe default for a field whose whole effect is to stop writing the
@@ -137,7 +168,15 @@ function forceBlockStyle(node) {
         node.flow = false;
     }
 }
-export function upsertServerYaml(path, name, def) {
+function persistText(path, content, backup) {
+    if (existsSync(path) && readFileSync(path, "utf-8") === content)
+        return;
+    if (backup)
+        backup.writeFile(path, content);
+    else
+        writeFileSync(path, content);
+}
+export function upsertServerYaml(path, name, def, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -151,12 +190,12 @@ export function upsertServerYaml(path, name, def) {
     doc.setIn(["servers", name], toServerDefYaml(def));
     forceBlockStyle(doc.get("servers", true));
     forceBlockStyle(doc.getIn(["servers", name], true));
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export function removeServerYaml(path, name) {
+export function removeServerYaml(path, name, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -168,7 +207,7 @@ export function removeServerYaml(path, name) {
         return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
     }
     doc.deleteIn(["servers", name]);
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /**
@@ -181,7 +220,7 @@ export function removeServerYaml(path, name) {
  * starter file). Selecting one mode always clears the other two
  * (design.md D3) — never left for the caller to remember.
  */
-export function writeMcpModeYaml(path, mode) {
+export function writeMcpModeYaml(path, mode, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -214,7 +253,56 @@ export function writeMcpModeYaml(path, mode) {
             forceBlockStyle(doc.get("gateway", true));
             break;
     }
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export function writeMcpRoutesYaml(path, routes, backup) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(routes).map(([agent, route]) => [agent, { mode: route.mode, ...(route.servers ? { servers: route.servers } : {}) }]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("routes");
+    }
+    else {
+        doc.set("routes", serialized);
+        forceBlockStyle(doc.get("routes", true));
+    }
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export function writeMcpRuntimeDeliveryYaml(path, delivery, backup) {
+    if (!existsSync(path)) {
+        return { ok: false, error: path + " does not exist — run trellis init first" };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(delivery).map(([agent, mode]) => [agent, mode]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("runtime");
+    }
+    else {
+        doc.setIn(["runtime", "delivery"], serialized);
+        forceBlockStyle(doc.get("runtime", true));
+        forceBlockStyle(doc.getIn(["runtime", "delivery"], true));
+    }
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 function loadSecretsPolicyYaml(path, homeDir) {
@@ -240,7 +328,7 @@ function loadSecretsPolicyYaml(path, homeDir) {
  * `varName` to `allowed_vars` only if not already present (dedup, same
  * "already there is a no-op" rule every other Trellis writer follows).
  */
-export function writeSecretsPolicyExtraction(path, extraction) {
+export function writeSecretsPolicyExtraction(path, extraction, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -262,7 +350,7 @@ export function writeSecretsPolicyExtraction(path, extraction) {
         doc.set("allowed_vars", [...currentAllowedVars, extraction.varName]);
         forceBlockStyle(doc.get("allowed_vars", true));
     }
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /**
@@ -275,13 +363,13 @@ export function writeSecretsPolicyExtraction(path, extraction) {
  * init`'s own bootstrap, so a machine that never extracts a secret never
  * gains this file at all.
  */
-export function ensureGitignoreEntry(gitignorePath, line) {
+export function ensureGitignoreEntry(gitignorePath, line, backup) {
     const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
     const lines = existing.split("\n").map((l) => l.trim());
     if (lines.includes(line))
         return;
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    writeFileSync(gitignorePath, `${existing}${separator}${line}\n`);
+    persistText(gitignorePath, `${existing}${separator}${line}\n`, backup);
 }
 const SHELL_ENV_SOURCE_MARKER = "# >>> trellis mcp secrets >>>";
 const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
@@ -297,17 +385,17 @@ const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
  * lines `parseDotenv` already expects, so that format never needs an
  * `export` prefix of its own.
  */
-export function ensureShellEnvSource(rcPath, envFilePath) {
+export function ensureShellEnvSource(rcPath, envFilePath, backup) {
     const existing = existsSync(rcPath) ? readFileSync(rcPath, "utf-8") : "";
     if (existing.includes(SHELL_ENV_SOURCE_MARKER))
         return;
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
     const block = `${SHELL_ENV_SOURCE_MARKER}\nif [ -f "${envFilePath}" ]; then\n  set -a\n  source "${envFilePath}"\n  set +a\nfi\n${SHELL_ENV_SOURCE_END_MARKER}\n`;
     mkdirSync(dirname(rcPath), { recursive: true });
-    writeFileSync(rcPath, `${existing}${separator}${block}`);
+    persistText(rcPath, `${existing}${separator}${block}`, backup);
 }
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
- * all four agents," the default. A recognized but empty list is left as
+ * all managed agents by default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
 /** Missing file and `agents: []` both resolve to `[]` — zero managed
  * agents (D1), never "everyone." An unrecognized id is dropped with a

package/dist/core/capabilitySelection.d.ts

@@ -0,0 +1,45 @@
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRouteMode } from "./types.js";
+export type NameSelection = "all" | "none" | string[];
+export interface CapabilitySelection {
+    skills: NameSelection;
+    mcpServers: NameSelection;
+    memories: NameSelection;
+    memoryMigration: "all" | "none";
+    mcpRoutes: Partial<Record<AgentId, {
+        mode: McpRouteMode;
+        servers?: string[];
+    }>>;
+    runtimeDelivery: Partial<Record<AgentId, CapabilityDelivery>>;
+}
+export interface CapabilityItem {
+    name: string;
+    displayName: string;
+    fingerprint?: string;
+    status: "new" | "unchanged" | "changed" | "unsupported";
+    detail?: string;
+}
+export interface UnsupportedCapabilitySource {
+    name: string;
+    detail: string;
+}
+export interface CapabilityInventory {
+    skills: CapabilityItem[];
+    mcpServers: CapabilityItem[];
+    canonicalMemories: CapabilityItem[];
+    nativeMemory: UnsupportedCapabilitySource[];
+}
+export type SelectionFileResult = {
+    ok: true;
+    selection: CapabilitySelection;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseCapabilitySelectionFile(path: string): SelectionFileResult;
+export declare function defaultCapabilitySelection(): CapabilitySelection;
+export declare function resolveSelectedNames(selection: NameSelection, available: readonly string[]): string[];
+export declare function selectionContains(selection: NameSelection, name: string): boolean;
+export declare function buildCapabilityInventory(source: {
+    skillNames: readonly string[];
+    mcpServerNames: readonly string[];
+}, canonical: Pick<CanonicalSource, "skills" | "mcp" | "memories">, nativeMemory?: UnsupportedCapabilitySource[]): CapabilityInventory;

package/dist/core/capabilitySelection.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "./types.js";
+const ALL_SELECTION = {
+    skills: "all",
+    mcpServers: "all",
+    memories: "all",
+    memoryMigration: "all",
+    mcpRoutes: {},
+    runtimeDelivery: {},
+};
+function parseNameSelection(value, field) {
+    if (value === undefined)
+        return "all";
+    if (value === "all" || value === "none")
+        return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0)) {
+        return [...new Set(value)];
+    }
+    throw new Error(`${field} must be "all", "none", or a list of names`);
+}
+function parseRoutes(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("mcp_routes must be a map of agent ids to route definitions");
+    }
+    const routes = {};
+    for (const [rawAgent, rawRoute] of Object.entries(value)) {
+        if (!ALL_AGENTS.includes(rawAgent)) {
+            throw new Error(`mcp_routes contains unknown agent "${rawAgent}"`);
+        }
+        if (typeof rawRoute !== "object" || rawRoute === null || Array.isArray(rawRoute)) {
+            throw new Error(`mcp_routes.${rawAgent} must be a route object`);
+        }
+        const route = rawRoute;
+        if (route.mode !== "direct" && route.mode !== "gateway" && route.mode !== "hub") {
+            throw new Error(`mcp_routes.${rawAgent}.mode must be direct, gateway, or hub`);
+        }
+        if (route.servers !== undefined && (!Array.isArray(route.servers) || !route.servers.every((item) => typeof item === "string" && item.length > 0))) {
+            throw new Error(`mcp_routes.${rawAgent}.servers must be a list of names`);
+        }
+        routes[rawAgent] = {
+            mode: route.mode,
+            ...(route.servers ? { servers: [...new Set(route.servers)] } : {}),
+        };
+    }
+    return routes;
+}
+function parseRuntimeDelivery(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("runtime_delivery must be a map of agent ids to native, mcp, or both");
+    }
+    const delivery = {};
+    for (const [rawAgent, rawMode] of Object.entries(value)) {
+        if (!ALL_AGENTS.includes(rawAgent)) {
+            throw new Error(`runtime_delivery contains unknown agent "${rawAgent}"`);
+        }
+        if (rawMode !== "native" && rawMode !== "mcp" && rawMode !== "both") {
+            throw new Error(`runtime_delivery.${rawAgent} must be native, mcp, or both`);
+        }
+        delivery[rawAgent] = rawMode;
+    }
+    return delivery;
+}
+export function parseCapabilitySelectionFile(path) {
+    if (!existsSync(path))
+        return { ok: false, error: `selection file does not exist: ${path}` };
+    try {
+        const parsed = (parseYaml(readFileSync(path, "utf8")) ?? {});
+        return {
+            ok: true,
+            selection: {
+                skills: parseNameSelection(parsed.skills, "skills"),
+                mcpServers: parseNameSelection(parsed.mcp_servers, "mcp_servers"),
+                memories: parseNameSelection(parsed.memories, "memories"),
+                memoryMigration: parsed.memory_migration === undefined || parsed.memory_migration === "all" ? "all" : parsed.memory_migration === "none" ? "none" : (() => { throw new Error('memory_migration must be "all" or "none"'); })(),
+                mcpRoutes: parseRoutes(parsed.mcp_routes),
+                runtimeDelivery: parseRuntimeDelivery(parsed.runtime_delivery),
+            },
+        };
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse selection file ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+export function defaultCapabilitySelection() {
+    return { ...ALL_SELECTION, mcpRoutes: {}, runtimeDelivery: {} };
+}
+export function resolveSelectedNames(selection, available) {
+    if (selection === "all")
+        return [...available];
+    if (selection === "none")
+        return [];
+    const availableSet = new Set(available);
+    return [...new Set(selection.filter((name) => availableSet.has(name)))];
+}
+export function selectionContains(selection, name) {
+    return selection === "all" || (selection !== "none" && selection.includes(name));
+}
+export function buildCapabilityInventory(source, canonical, nativeMemory = []) {
+    const canonicalSkills = new Set(canonical.skills.map((skill) => skill.name));
+    const canonicalMcp = new Set(Object.keys(canonical.mcp.servers));
+    return {
+        skills: source.skillNames.map((name) => ({
+            name,
+            displayName: name,
+            status: canonicalSkills.has(name) ? "unchanged" : "new",
+        })),
+        mcpServers: source.mcpServerNames.map((name) => ({
+            name,
+            displayName: name,
+            status: canonicalMcp.has(name) ? "unchanged" : "new",
+        })),
+        canonicalMemories: canonical.memories.map((memory) => ({
+            name: memory.name,
+            displayName: memory.name,
+            status: "unchanged",
+        })),
+        nativeMemory,
+    };
+}

package/dist/core/types.d.ts

@@ -5,11 +5,12 @@
  * files on disk are its serialization, not the other way around.
  */
 export type Transport = "stdio" | "http" | "sse";
-export type AgentId = "claude-code" | "codex" | "kiro" | "pi";
+export type McpAuthMode = "oauth";
+export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code";
 export declare const ALL_AGENTS: readonly AgentId[];
 /**
  * Every scopable item (skill, subagent, memory entry, MCP server) defaults
- * to "all four agents" when `scope` is omitted — sharing everywhere is the
+ * to all managed agents when `scope` is omitted — sharing everywhere is the
  * common case Trellis exists for; restricting to specific agents is the
  * exception and must be declared explicitly. See docs/architecture.md
  * "Private / agent-specific capabilities".
@@ -26,6 +27,9 @@ export type Scope = AgentId[] | undefined;
 export declare function resolveScope(scope: Scope, managedAgents: readonly AgentId[]): readonly AgentId[];
 export interface McpServerDef {
     transport: Transport;
+    /** Explicit authorization classification. Absence means ordinary MCP;
+     * Trellis never infers OAuth from a URL or a transient 401. */
+    auth?: McpAuthMode;
     /** stdio only */
     command?: string;
     args?: string[];
@@ -109,6 +113,18 @@ export interface GatewayConfig {
      */
     agents?: AgentId[];
 }
+export type McpRouteMode = "direct" | "gateway" | "hub";
+export interface McpRoute {
+    mode: McpRouteMode;
+    /** Omit to expose every eligible canonical server for this agent. */
+    servers?: string[];
+}
+export type CapabilityDelivery = "native" | "mcp" | "both";
+export interface McpRuntimeConfig {
+    /** Per-agent delivery for Trellis-owned capabilities and upstream MCP.
+     * Omitted means native, preserving the existing adapter behavior. */
+    delivery?: Partial<Record<AgentId, CapabilityDelivery>>;
+}
 export interface McpConfig {
     servers: Record<string, McpServerDef>;
     /**
@@ -127,7 +143,14 @@ export interface McpConfig {
      * two mean different things and may both be set, in which case gateway
      * wins per agent (trellis-mcp-gateway-hosting design.md D5/D6). */
     gateway?: GatewayConfig;
+    /** Optional per-agent route overrides. Explicit routes take precedence
+     * over the legacy hub/gateway shorthand for the named agent. */
+    routes?: Partial<Record<AgentId, McpRoute>>;
+    /** Optional runtime delivery preferences. */
+    runtime?: McpRuntimeConfig;
 }
+export declare function capabilityDeliveryForAgent(agentId: AgentId, mcp: McpConfig): CapabilityDelivery;
+export declare function usesNativeCapabilityDelivery(agentId: AgentId, mcp: McpConfig): boolean;
 export interface SkillRef {
     name: string;
     /** Absolute path to the skill's directory. Must contain `SKILL.md` — the

package/dist/core/types.js

@@ -9,6 +9,7 @@ export const ALL_AGENTS = [
     "codex",
     "kiro",
     "pi",
+    "kimi-code",
 ];
 /**
  * `managedAgents` is the hard outer boundary (trellis-managed-agents
@@ -22,3 +23,9 @@ export function resolveScope(scope, managedAgents) {
     const candidates = scope ?? managedAgents;
     return candidates.filter((id) => managedAgents.includes(id));
 }
+export function capabilityDeliveryForAgent(agentId, mcp) {
+    return mcp.runtime?.delivery?.[agentId] ?? "native";
+}
+export function usesNativeCapabilityDelivery(agentId, mcp) {
+    return capabilityDeliveryForAgent(agentId, mcp) !== "mcp";
+}

package/dist/lib/backup.d.ts

@@ -39,10 +39,12 @@ export interface BackupManifest {
     operations: BackupOperation[];
 }
 export interface BackupSession {
+    readonly runId: string;
     writeFile(path: string, content: string): void;
     createSymlink(path: string, linkTarget: string): Promise<void>;
     repairSymlink(path: string, oldLinkTarget: string, newLinkTarget: string): Promise<void>;
     removeSymlink(path: string, oldLinkTarget: string): Promise<void>;
+    hasOperations(): boolean;
     /** Writes manifest.json. No-op (creates nothing) if zero operations
      * were ever recorded. */
     finalize(): void;