agent-trellis 0.7.0 → 0.8.2

package/dist/commands/migrate.d.ts

@@ -5,13 +5,15 @@
  * plan-then-apply split every adapter already uses.
  */
 import type { AgentId, McpServerDef } from "../core/types.js";
+import type { BackupSession } from "../lib/backup.js";
+import { type NativeMemoryCandidate, type NativeMemoryDiscovery } from "../lib/nativeMemory.js";
 export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "reclassify" | "conflict" | "extract-secret";
 /** Internal kind naming, unchanged since before `--only` existed
  * (trellis-migrate-category-selection design.md D2) — the CLI-facing
  * flag value is the plural `"skills"`, mapped to this singular `"skill"`
  * in `runMigrate`, not renamed here to avoid touching every existing
  * `MigratePlanItem.kind` comparison for no functional reason. */
-export type MigrateKind = "skill" | "instructions" | "mcp";
+export type MigrateKind = "skill" | "instructions" | "mcp" | "memory";
 export interface MigratePlanItem {
     kind: MigrateKind;
     name: string;
@@ -45,11 +47,19 @@ export interface MigratePlanItem {
      * already-migrated server extracted before this naming scheme existed,
      * which never reaches this action at all (already-migrated instead). */
     extractSourceKey?: string;
+    /** Memory migration only: source is re-read at apply time and the target
+     * path is canonical, so the plan never serializes the real body. */
+    memorySourcePath?: string;
+    memorySourceId?: string;
+    memoryTargetPath?: string;
 }
 export interface MigratePlan {
     agent: AgentId;
     present: boolean;
     items: MigratePlanItem[];
+    memoryDiscovery?: Omit<NativeMemoryDiscovery, "candidates"> & {
+        candidates: Array<Omit<NativeMemoryCandidate, "content">>;
+    };
 }
 /**
  * True when `existing` and `def` differ ONLY in which of `env`/
@@ -72,14 +82,15 @@ export declare function isSafeReclassification(existing: McpServerDef, def: McpS
  * conflict. Omitting `only` (or passing both kinds) is exactly today's
  * behavior.
  */
-export declare function collectMigratePlan(agent: AgentId, homeDir?: string, only?: readonly MigrateKind[]): Promise<MigratePlan>;
-export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string): void;
+export declare function collectMigratePlan(agent: AgentId, homeDir?: string, only?: readonly MigrateKind[], workspaceDir?: string): Promise<MigratePlan>;
+export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string, backup?: BackupSession): void;
 /** CLI-facing spelling: `"skills"` (plural — a run usually touches more
- * than one), `"instructions"` (already singular-shaped), or `"mcp"`
+ * than one), `"instructions"` (already singular-shaped), `"mcp"`, or
+ * `"memory"`
  * (already the CLI's own convention, matching `trellis mcp`'s own
  * command name). Mapped to `MigrateKind` in `runMigrate`, the one place
  * this translation lives. */
-export type MigrateOnlyValue = "skills" | "instructions" | "mcp";
+export type MigrateOnlyValue = "skills" | "instructions" | "mcp" | "memory";
 export interface RunMigrateOptions {
     from?: string;
     /** Restricts the run to one category (`"skills"`, `"instructions"`, or

package/dist/commands/migrate.js

@@ -4,21 +4,24 @@
  * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
  * plan-then-apply split every adapter already uses.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
+import * as zcodeProbe from "../probes/zcode.js";
 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 { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, readKimiCodeMcpDefs, readZcodeMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { findLiteralSecret } from "../adapters/mcpPlan.js";
 import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
+import { discoverNativeMemory, MAX_NATIVE_MEMORY_BYTES, renderNativeMemory } from "../lib/nativeMemory.js";
 /** Where a `staticEnv` literal secret's real value goes when
  * `secrets.policy.yaml` doesn't already have its own `env_file`
  * (trellis-migrate-extract-static-env-secrets design.md D3) — a sibling
@@ -48,6 +51,8 @@ const PROBES = {
     codex: (homeDir) => codexProbe.probe(homeDir),
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
+    "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
+    zcode: (homeDir) => zcodeProbe.probe(homeDir),
 };
 /** pi has no static MCP config to read at all (roadmap.md P14/
  * trellis-migrate-mcp-servers) — deliberately absent, not an oversight;
@@ -56,6 +61,8 @@ const MCP_READERS = {
     "claude-code": readClaudeCodeMcpDefs,
     kiro: readKiroMcpDefs,
     codex: readCodexMcpDefs,
+    "kimi-code": readKimiCodeMcpDefs,
+    zcode: readZcodeMcpDefs,
 };
 function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (isSymlink) {
@@ -116,6 +123,32 @@ function planInstructions(snapshot, canonicalAgentsMd) {
         remediation: `compare \`~/.trellis/agents.md\` against ${snapshot.instructionsFile.path} and either merge by hand or delete whichever copy you don't want to keep`,
     };
 }
+function planNativeMemoryCandidate(candidate, homeDir) {
+    const targetPath = join(homeDir, ".trellis", "memories", `${candidate.targetName}.md`);
+    const rendered = renderNativeMemory(candidate);
+    if (!existsSync(targetPath)) {
+        return {
+            kind: "memory",
+            name: candidate.targetName,
+            action: "create",
+            detail: `will import ${candidate.displayName} from ${candidate.sourceAgent} native memory`,
+            memorySourcePath: candidate.sourcePath,
+            memorySourceId: candidate.sourceId,
+            memoryTargetPath: targetPath,
+        };
+    }
+    const current = readFileSync(targetPath, "utf8");
+    if (current === rendered) {
+        return { kind: "memory", name: candidate.targetName, action: "already-migrated", detail: "canonical memory is byte-identical" };
+    }
+    return {
+        kind: "memory",
+        name: candidate.targetName,
+        action: "conflict",
+        detail: `canonical memories/${candidate.targetName}.md already has different content — resolve by hand`,
+        remediation: `compare the canonical file with ${candidate.sourcePath} and decide which memory to keep before re-running migration`,
+    };
+}
 /**
  * True when `existing` and `def` differ ONLY in which of `env`/
  * `envAliases`/`staticEnv` an env value is filed under, while every
@@ -273,13 +306,14 @@ function planMcpServer(name, def, existing, homeDir, policy) {
  * conflict. Omitting `only` (or passing both kinds) is exactly today's
  * behavior.
  */
-export async function collectMigratePlan(agent, homeDir = homedir(), only) {
+export async function collectMigratePlan(agent, homeDir = homedir(), only, workspaceDir = process.cwd()) {
     const snapshot = await PROBES[agent](homeDir);
     if (!snapshot.present) {
         return { agent, present: false, items: [] };
     }
     const canonicalRoot = join(homeDir, ".trellis");
     const items = [];
+    let memoryDiscovery;
     const wants = (kind) => !only || only.includes(kind);
     if (wants("skill")) {
         for (const root of snapshot.skillRoots) {
@@ -306,7 +340,14 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
             }
         }
     }
-    return { agent, present: true, items };
+    if (wants("memory")) {
+        const discovery = discoverNativeMemory(agent, homeDir, workspaceDir);
+        memoryDiscovery = { ...discovery, candidates: discovery.candidates.map(({ content: _content, ...safe }) => safe) };
+        for (const candidate of discovery.candidates) {
+            items.push(planNativeMemoryCandidate(candidate, homeDir));
+        }
+    }
+    return { agent, present: true, items, ...(memoryDiscovery ? { memoryDiscovery } : {}) };
 }
 /**
  * Re-reads the source agent's real MCP entries at apply time to recover
@@ -319,18 +360,31 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
  * written under, design.md D11) are looked up and written under
  * separately — they are not, in general, the same string.
  */
-function applyStaticEnvExtraction(agent, serverName, sourceKey, varName, targetPath, homeDir) {
+function applyStaticEnvExtraction(agent, serverName, sourceKey, varName, targetPath, homeDir, backup) {
     const reader = MCP_READERS[agent];
     const realValue = reader?.(homeDir).entries.find((e) => e.name === serverName)?.def.staticEnv?.[sourceKey];
     if (realValue === undefined)
         return; // source changed between plan and apply; nothing left to extract
     if (targetPath === defaultLocalSecretsEnvFilePath(homeDir)) {
-        ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env");
+        ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env", backup);
+    }
+    writeLocalSecretValue(targetPath, varName, realValue, backup);
+    writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE }, backup);
+}
+function copyDirectoryThroughBackup(sourceDir, destDir, backup) {
+    for (const entry of readdirSync(sourceDir)) {
+        const source = join(sourceDir, entry);
+        const dest = join(destDir, entry);
+        if (statSync(source).isDirectory()) {
+            mkdirSync(dest, { recursive: true });
+            copyDirectoryThroughBackup(source, dest, backup);
+        }
+        else {
+            backup.writeFile(dest, readFileSync(source, "utf-8"));
+        }
     }
-    writeLocalSecretValue(targetPath, varName, realValue);
-    writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE });
 }
-export function applyMigratePlan(plan, homeDir = homedir()) {
+export function applyMigratePlan(plan, homeDir = homedir(), backup) {
     const canonicalRoot = join(homeDir, ".trellis");
     for (const item of plan.items) {
         if (item.action !== "create" && item.action !== "reclassify" && item.action !== "extract-secret")
@@ -338,18 +392,35 @@ export function applyMigratePlan(plan, homeDir = homedir()) {
         if (item.kind === "skill" && item.sourceDir) {
             const dest = join(canonicalRoot, "skills", item.name);
             mkdirSync(dest, { recursive: true });
-            cpSync(item.sourceDir, dest, { recursive: true });
+            if (backup)
+                copyDirectoryThroughBackup(item.sourceDir, dest, backup);
+            else
+                cpSync(item.sourceDir, dest, { recursive: true });
         }
         else if (item.kind === "instructions" && item.sourceContent !== undefined) {
             mkdirSync(canonicalRoot, { recursive: true });
-            writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
+            if (backup)
+                backup.writeFile(join(canonicalRoot, "agents.md"), item.sourceContent);
+            else
+                writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
         }
         else if (item.kind === "mcp" && item.mcpDef) {
-            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef);
+            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef, backup);
             if (item.action === "extract-secret" && item.extractVarName && item.extractTargetPath && item.extractSourceKey) {
-                applyStaticEnvExtraction(plan.agent, item.name, item.extractSourceKey, item.extractVarName, item.extractTargetPath, homeDir);
+                applyStaticEnvExtraction(plan.agent, item.name, item.extractSourceKey, item.extractVarName, item.extractTargetPath, homeDir, backup);
             }
         }
+        else if (item.kind === "memory" && item.memorySourcePath && item.memorySourceId && item.memoryTargetPath) {
+            if (statSync(item.memorySourcePath).size > MAX_NATIVE_MEMORY_BYTES)
+                throw new Error(`native memory source exceeds the ${MAX_NATIVE_MEMORY_BYTES}-byte limit: ${item.memorySourcePath}`);
+            const content = readFileSync(item.memorySourcePath, "utf8");
+            const imported = renderNativeMemory({ sourceAgent: plan.agent, sourceId: item.memorySourceId, content });
+            mkdirSync(dirname(item.memoryTargetPath), { recursive: true });
+            if (backup)
+                backup.writeFile(item.memoryTargetPath, imported);
+            else
+                writeFileSync(item.memoryTargetPath, imported);
+        }
     }
     // Runs every real (non-dry-run) migrate invocation, not just the one that
     // performed a fresh extraction — a machine that already extracted a
@@ -357,10 +428,10 @@ export function applyMigratePlan(plan, homeDir = homedir()) {
     // migrate runs at all, not only on its next brand-new extraction.
     const envFile = loadCanonicalSource(homeDir).secretsPolicy.envFile;
     if (envFile) {
-        ensureShellEnvSource(defaultShellRcPath(homeDir), envFile);
+        ensureShellEnvSource(defaultShellRcPath(homeDir), envFile, backup);
     }
 }
-const ONLY_VALUES = ["skills", "instructions", "mcp"];
+const ONLY_VALUES = ["skills", "instructions", "mcp", "memory"];
 function isMigrateOnlyValue(value) {
     return ONLY_VALUES.includes(value);
 }
@@ -369,6 +440,8 @@ function toMigrateKinds(only) {
         return ["skill"];
     if (only === "instructions")
         return ["instructions"];
+    if (only === "memory")
+        return ["memory"];
     return ["mcp"];
 }
 export async function runMigrate(opts = {}) {
@@ -405,12 +478,15 @@ export async function runMigrate(opts = {}) {
  * this formatting (including the empty-plan "nothing to migrate" case). */
 export function printPlan(plan, dryRun) {
     console.log(`${dryRun ? "[dry run] " : ""}migrate --from ${plan.agent}`);
+    if (plan.memoryDiscovery && plan.memoryDiscovery.status !== "supported") {
+        console.log(`  memory source — [${plan.memoryDiscovery.status}] ${plan.memoryDiscovery.detail}`);
+    }
     if (plan.items.length === 0) {
         console.log("  nothing to migrate");
         return;
     }
     for (const item of plan.items) {
-        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions";
+        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : item.kind === "memory" ? `memory "${item.name}"` : "instructions";
         console.log(`  [${item.action}] ${label} — ${item.detail}`);
     }
 }

package/dist/commands/onboard.d.ts

@@ -12,15 +12,39 @@
  * new skill-copy, symlink, conflict-detection, or secrets-scanning
  * judgment is made here.
  */
-import type { AgentId } from "../core/types.js";
+import type { AgentId, McpConfig, McpRouteMode } from "../core/types.js";
+import { type CapabilityInventory } from "../core/capabilitySelection.js";
+import { type NativeMemoryStatus } from "../lib/nativeMemory.js";
 import type { MigrateKind, MigratePlan } from "./migrate.js";
 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 { RollbackReport } from "./rollback.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
 import type { VerdictItem } from "./onboardVerdict.js";
+/**
+ * Scores only real source-side content. The recommendation is a hint for a
+ * first-time user, never a filter: every candidate remains selectable.
+ */
+export declare function migrationSourceScore(summary: Pick<OnboardAgentSummary, "skillCount" | "mcpServerCount" | "hasRealInstructions">): number;
+export declare function recommendedMigrationSource(summaries: readonly (Pick<OnboardAgentSummary, "agent" | "skillCount" | "mcpServerCount" | "hasRealInstructions">)[]): AgentId | undefined;
+export declare const MCP_ROUTE_OPTIONS: ({
+    mode: "gateway";
+    label: string;
+} | {
+    mode: "direct";
+    label: string;
+} | {
+    mode: "hub";
+    label: string;
+})[];
+export declare function interactiveMcpRouteOptions(hubConfigured: boolean): Array<{
+    mode: McpRouteMode;
+    label: string;
+    disabled?: boolean;
+}>;
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -37,8 +61,13 @@ export interface OnboardAgentSummary {
      * memory). 0 for pi, which has no MCP reader at all — not a gap here,
      * the same fact `migrate.ts` already establishes. */
     mcpServerCount: number;
+    mcpServerNames: string[];
+    nativeMemoryStatus: NativeMemoryStatus;
+    nativeMemoryCount: number;
+    nativeMemoryNames: string[];
+    nativeMemoryDetail: string;
 }
-export declare function collectOnboardSummary(homeDir?: string): Promise<OnboardAgentSummary[]>;
+export declare function collectOnboardSummary(homeDir?: string, workspaceDir?: string): Promise<OnboardAgentSummary[]>;
 export interface RunOnboardOptions {
     /** Non-interactive migration-source choice. */
     agent?: string;
@@ -60,10 +89,19 @@ export interface RunOnboardOptions {
      * Omitted leaves whatever's already configured untouched — same
      * no-prompt posture as `mcpMode` (design.md D12). */
     memory?: string;
+    /** Non-interactive native-source memory migration toggle: `"on"` or
+     * `"off"`. Omitted preserves the current state and prompts only when
+     * supported source candidates are available in a real terminal. */
+    memoryMigrate?: string;
+    /** Optional YAML/JSON item-level capability selection for automation. */
+    selectionFile?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */
     homeDir?: string;
+    /** Defaults to the current working directory; controls project-scoped
+     * native-memory discovery and is overridable for tests. */
+    workspaceDir?: string;
     /** Test-only: overrides the real `process.stdin.isTTY` check so the
      * interactive-vs-refuse branch is exercisable without a real terminal. */
     isTTY?: boolean;
@@ -84,6 +122,13 @@ export interface RunOnboardOptions {
      * (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: replaces the real mode-transition confirmation. */
+    promptForModeChange?: (previous: "direct" | "hub" | "gateway", next: "direct" | "hub" | "gateway", agents: readonly AgentId[]) => Promise<boolean>;
+    /** Test-only: replaces the interactive shared-Memory choice. `keep` leaves
+     * the existing state untouched; the real picker puts that choice first. */
+    promptForMemory?: (current: "on" | "off") => Promise<"keep" | "on" | "off">;
+    /** Test-only: replaces the interactive native-memory migration choice. */
+    promptForMemoryMigration?: (source: AgentId, count: number) => Promise<"keep" | "on" | "off">;
     /** 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. */
@@ -96,6 +141,23 @@ export interface OnboardInstallResult {
 }
 export interface OnboardResult {
     summary: OnboardAgentSummary[];
+    inventory?: CapabilityInventory;
+    capabilitySummary?: {
+        awarenessSkill: boolean;
+        globalInstructions: {
+            available: boolean;
+            native: boolean;
+            runtimeReadable: boolean;
+        };
+        skills: number;
+        memories: number;
+        mcpServers: number;
+    };
+    managedAgentRuntime?: Array<{
+        agent: AgentId;
+        delivery: "native" | "mcp" | "both";
+        route: "direct" | "gateway" | "hub";
+    }>;
     source?: AgentId;
     sourceReason?: "auto-selected" | "flag" | "prompt";
     /** The full managed set this run acted against — the union of whatever
@@ -131,6 +193,8 @@ export interface OnboardResult {
      * inconsistent across agents independent of this run.
      */
     doctorReport?: DoctorReport;
+    /** Present when a blocking real run was automatically restored. */
+    rollback?: RollbackReport;
     /**
      * The resolved MCP mode after this run (trellis-onboard-mcp-mode
      * design.md D7) — `current` reflects canonical's state whether or not
@@ -165,6 +229,14 @@ export interface OnboardResult {
      */
     verdict: VerdictItem[];
 }
+/** Converges explicit per-Agent route lists with the shared Memory toggle.
+ * Legacy/top-level routes without a `servers` list already expose every
+ * eligible server and need no rewrite. Hub routes are intentionally opaque:
+ * the external hub owns its upstream set. */
+export declare function mergeMemoryIntoExplicitRoutes(mcp: McpConfig, managedAgents: readonly AgentId[], memoryEnabled: boolean): {
+    mcp: McpConfig;
+    changed: boolean;
+};
 export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
 export declare function runOnboard(opts?: RunOnboardOptions): Promise<{
     exitCode: number;