@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/dist/lib/staleness/writers/subagents.js

@@ -1,123 +1,32 @@
-/**
- * Subagents writer. Claude/Gemini/Grok flatten each subagent into a single
- * .md file under their native agents directory. Codex writes TOML under
- * `.codex/agents/`.
- * Droid (Factory AI) flattens each into a custom droid .md under
- * `<versionHome>/.factory/droids/`. Cursor flattens each into a custom
- * subagent .md under `<versionHome>/.cursor/agents/`. OpenClaw copies the
- * full subagent directory (with AGENT.md renamed to AGENTS.md) into
- * `<versionHome>/.openclaw/<name>/`.
- *
- * Source-side discovery is `listInstalledSubagents` from lib/subagents.ts —
- * it reads user + system layers only (project layer excluded for the same
- * defense as commands/skills/hooks).
- */
-import * as fs from 'fs';
-import * as path from 'path';
 import { capableAgents } from '../../capabilities.js';
-import { listInstalledSubagents, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, writeKimiSubagentFiles, buildKimiSubagentsParentYaml, KIMI_SUBAGENTS_PARENT_FILE, transformSubagentForOpenCode, transformSubagentForAntigravity, transformSubagentForDroid, transformSubagentForForge, transformSubagentForKiro, transformSubagentForCursor, transformSubagentForGoose, syncSubagentToOpenclaw, parseSubagentFrontmatter, } from '../../subagents.js';
-import { safeJoin } from '../../paths.js';
+import { listInstalledSubagents } from '../../subagents.js';
+import { subagentTarget } from '../../subagents-registry.js';
 import { lazyAgentMap } from './lazy-map.js';
 function buildSubagentsWriter(agent) {
     return {
         kind: 'subagents',
         agent,
         write({ versionHome, selection }) {
+            const target = subagentTarget(agent);
+            if (!target)
+                return { synced: [] };
             const all = listInstalledSubagents();
             const map = new Map(all.map(s => [s.name, s]));
+            const dir = target.dir(versionHome);
             const synced = [];
             for (const name of selection) {
                 const sub = map.get(name);
                 if (!sub)
                     continue;
                 try {
-                    if (agent === 'claude' || agent === 'gemini' || agent === 'grok') {
-                        const agentsRoot = agent === 'grok' ? '.grok' : agent === 'gemini' ? '.gemini' : '.claude';
-                        const agentsDir = path.join(versionHome, agentsRoot, 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForClaude(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'codex') {
-                        const agentsDir = path.join(versionHome, '.codex', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.toml`), transformSubagentForCodex(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'kimi') {
-                        writeKimiSubagentFiles(path.join(versionHome, '.kimi-code', 'agents'), sub.path, sub.name);
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'opencode') {
-                        const agentsDir = path.join(versionHome, '.config', 'opencode', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForOpenCode(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'antigravity') {
-                        const agentDir = safeJoin(path.join(versionHome, '.gemini', 'config', 'agents'), sub.name);
-                        fs.mkdirSync(agentDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentDir, 'agent.md'), transformSubagentForAntigravity(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'droid') {
-                        const droidsDir = path.join(versionHome, '.factory', 'droids');
-                        fs.mkdirSync(droidsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(droidsDir, `${sub.name}.md`), transformSubagentForDroid(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'copilot') {
-                        const agentsDir = path.join(versionHome, '.copilot', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.agent.md`), transformSubagentForCopilot(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'openclaw') {
-                        const target = safeJoin(path.join(versionHome, '.openclaw'), sub.name);
-                        const r = syncSubagentToOpenclaw(sub.path, target);
-                        if (r.success)
-                            synced.push(sub.name);
-                    }
-                    else if (agent === 'kiro') {
-                        const agentsDir = path.join(versionHome, '.kiro', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.json`), transformSubagentForKiro(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'cursor') {
-                        const agentsDir = path.join(versionHome, '.cursor', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForCursor(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'forge') {
-                        const agentsDir = path.join(versionHome, '.forge', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.md`), transformSubagentForForge(sub.path));
-                        synced.push(sub.name);
-                    }
-                    else if (agent === 'goose') {
-                        const agentsDir = path.join(versionHome, '.config', 'goose', 'agents');
-                        fs.mkdirSync(agentsDir, { recursive: true });
-                        fs.writeFileSync(safeJoin(agentsDir, `${sub.name}.yaml`), transformSubagentForGoose(sub.path));
-                        synced.push(sub.name);
-                    }
+                    target.write(dir, sub);
+                    synced.push(sub.name);
                 }
                 catch { /* per-item sync failure: skip */ }
             }
-            // Kimi parent agent file listing all synced subagents for --agent-file.
-            if (agent === 'kimi' && synced.length > 0) {
-                const agentsDir = path.join(versionHome, '.kimi-code', 'agents');
-                const entries = synced.map((name) => {
-                    const sub = map.get(name);
-                    const fm = parseSubagentFrontmatter(path.join(sub.path, 'AGENT.md'));
-                    return {
-                        name,
-                        description: fm?.description ?? name,
-                        relativePath: `./${name}.yaml`,
-                    };
-                });
-                fs.writeFileSync(safeJoin(agentsDir, KIMI_SUBAGENTS_PARENT_FILE), buildKimiSubagentsParentYaml(entries));
+            // Optional cross-item pass (e.g. Kimi's `_agents-cli.yaml` parent index).
+            if (target.finalize && synced.length > 0) {
+                target.finalize(dir, synced.map((name) => map.get(name)));
             }
             return { synced };
         },

package/dist/lib/startup/command-registry.d.ts

@@ -74,6 +74,7 @@ export declare const loadWatchdog: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
 export declare const loadHosts: ModuleLoader;
+export declare const loadLease: ModuleLoader;
 export declare const loadLogs: ModuleLoader;
 export declare const loadEvents: ModuleLoader;
 export declare const loadSsh: ModuleLoader;
@@ -86,6 +87,7 @@ export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
+export declare const loadMailboxes: ModuleLoader;
 export declare const loadServe: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
 export declare const loadWebhook: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -52,6 +52,7 @@ export const loadWatchdog = async () => (await import('../../commands/watchdog.j
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
 export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
+export const loadLease = async () => (await import('../../commands/lease.js')).registerLeaseCommand;
 export const loadLogs = async () => (await import('../../commands/logs.js')).registerLogsCommand;
 export const loadEvents = async () => (await import('../../commands/events.js')).registerEventsCommand;
 export const loadSsh = async () => (await import('../../commands/ssh.js')).registerSshCommands;
@@ -64,6 +65,7 @@ export const loadTeams = async () => (await import('../../commands/teams.js')).r
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
 export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
 export const loadFeed = async () => (await import('../../commands/feed.js')).registerFeedCommand;
+export const loadMailboxes = async () => (await import('../../commands/mailboxes.js')).registerMailboxesCommand;
 export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
 export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
 export const loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
@@ -149,6 +151,7 @@ export const COMMAND_LOADERS = {
     browser: [loadBrowser],
     computer: [loadComputer],
     hosts: [loadHosts],
+    lease: [loadLease],
     logs: [loadLogs],
     events: [loadEvents],
     ssh: [loadSsh],
@@ -169,6 +172,8 @@ export const COMMAND_LOADERS = {
     cloud: [loadCloud],
     message: [loadMessage],
     feed: [loadFeed],
+    mailboxes: [loadMailboxes],
+    mailbox: [loadMailboxes],
     serve: [loadServe],
     audit: [loadAudit],
     webhook: [loadWebhook],

package/dist/lib/subagents-registry.d.ts

@@ -0,0 +1,85 @@
+import type { AgentId, InstalledSubagent, SubagentFrontmatter } from './types.js';
+/** A path an installed subagent occupies, tagged for removal/trash handling. */
+export interface OccupiedEntry {
+    path: string;
+    kind: 'file' | 'dir';
+}
+/** Parsed metadata for one installed subagent (drives the rich listing). */
+export interface SubagentMeta {
+    frontmatter: SubagentFrontmatter;
+    files: string[];
+    /** Primary on-disk path for the listing's `path` field (a file or a dir, per layout). */
+    path: string;
+}
+/**
+ * The complete on-disk contract for one agent's subagents. Every operation is
+ * expressed here so the engine below never branches on the agent id.
+ */
+export interface SubagentTarget {
+    /** Absolute container dir under a home root (a version home or an agent home). */
+    dir(home: string): string;
+    /** Materialize central subagent `sub` into container `dir`. Throws on fs error. */
+    write(dir: string, sub: {
+        name: string;
+        path: string;
+    }): void;
+    /** Installed subagent names in `dir` (detector + orphan diff). */
+    names(dir: string): string[];
+    /** On-disk paths subagent `name` occupies (for removal / soft-delete). */
+    occupied(dir: string, name: string): OccupiedEntry[];
+    /** Rich metadata for `name`; `null` skips it from the listing. */
+    read(dir: string, name: string): SubagentMeta | null;
+    /** Optional post-sync pass over the just-synced subagents (Kimi's parent index). */
+    finalize?(dir: string, synced: Array<{
+        name: string;
+        path: string;
+    }>): void;
+}
+/**
+ * Copy every file in `src` into `dest` (created if missing), applying
+ * `rename` (source filename -> target filename) on the way. Directories in
+ * `src` are skipped -- subagents are flat file sets. Throws on fs error.
+ */
+export declare function copyDirWithRename(src: string, dest: string, rename?: Record<string, string>): void;
+/**
+ * Single source of truth for how each subagents-capable agent stores subagents.
+ * The keys MUST match `capableAgents('subagents')` (the `subagents` flag in
+ * `agents.ts`): the capability flag is the version gate, this table is the shape.
+ */
+export declare const SUBAGENT_TARGETS: Partial<Record<AgentId, SubagentTarget>>;
+/** The registry entry for `agent`, or undefined if it stores no subagents. */
+export declare function subagentTarget(agent: AgentId): SubagentTarget | undefined;
+/**
+ * Materialize central subagent `sub` into `home` for `agent`. Returns whether a
+ * write happened (false when the agent has no registry entry). Throws only on
+ * unexpected fs errors -- bulk callers wrap per-item.
+ */
+export declare function writeSubagentToHome(agent: AgentId, home: string, sub: {
+    name: string;
+    path: string;
+}): boolean;
+/** Installed subagent names for `agent` under `home` (detector + orphan diff). */
+export declare function listInstalledSubagentNames(agent: AgentId, home: string): string[];
+/**
+ * Rich listing of subagents installed for `agent` under `home`, with parsed
+ * metadata. Enumerates names, then reads each -- entries whose metadata is
+ * unreadable (per the target's reader) are dropped.
+ */
+export declare function listInstalledSubagentsRich(agent: AgentId, home: string): InstalledSubagent[];
+/**
+ * Remove subagent `name` for `agent` from `home` (hard delete). No-op success
+ * when the agent has no registry entry or nothing is installed.
+ */
+export declare function removeSubagentFromHome(agent: AgentId, home: string, name: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Soft-delete subagent `name` for `agent` from `home` into `trashDir`, stamping
+ * each moved entry. Files land as `<basename>.<stamp>`, directories as
+ * `<stamp>/`. No-op success when nothing is installed.
+ */
+export declare function trashSubagentFromHome(agent: AgentId, home: string, name: string, trashDir: string, stamp: string): {
+    success: boolean;
+    error?: string;
+};

package/dist/lib/subagents-registry.js

@@ -0,0 +1,393 @@
+/**
+ * Declarative subagent-target registry.
+ *
+ * Each subagents-capable agent gets ONE table entry (`SUBAGENT_TARGETS`)
+ * describing how a central subagent (`~/.agents/subagents/<name>/`) is
+ * materialized into that agent's home, how it is enumerated, and where it lives
+ * on disk. Generic install / list / detect / orphan / remove logic iterates the
+ * table instead of the near-identical `else if (agent === '...')` chains that
+ * used to be copy-pasted across `subagents.ts`, the staleness writer, and the
+ * staleness detector -- roughly O(agents x operations) arms.
+ *
+ * Adding a *standard* integration is now one line here (plus the `subagents`
+ * capability flag in `agents.ts`, the version gate). Three layout builders cover
+ * every current agent, so most entries are a single call:
+ *
+ *   - `flatFile`  one `<name><ext>` file, body from a `transform` fn.
+ *                 (claude, gemini, grok, droid, codex, opencode, copilot,
+ *                  cursor, forge, kiro, goose)
+ *   - `dirFile`   a `<name>/` directory holding one generated `<file>`.
+ *                 (antigravity: `<name>/agent.md`)
+ *   - `dirCopy`   copy the whole source directory to `<name>/`, applying
+ *                 renames, detected by a `marker` file. (openclaw)
+ *
+ * Genuinely-bespoke agents keep an explicit handler in the same table -- Kimi
+ * writes two files per subagent plus a managed parent index, so it is a hand
+ * -written `SubagentTarget` rather than a builder call.
+ *
+ * The per-agent `transform`/metadata parsers are the escape hatch: they live in
+ * `subagents.ts` and are referenced by the table, so the generic engine has zero
+ * per-agent branches. See the integration tiers in `docs/subagents.md`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { safeJoin } from './paths.js';
+import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForForge, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, writeKimiSubagentFiles, buildKimiSubagentsParentYaml, KIMI_SUBAGENTS_PARENT_FILE, } from './subagents.js';
+// ── metadata readers (the per-format escape hatch) ───────────────────────────
+/** Frontmatter, skipping files that lack a valid block (claude/gemini/grok/droid/codex). */
+function metaFrontmatterSkip(filePath) {
+    return parseSubagentFrontmatter(filePath);
+}
+/** Frontmatter, falling back to an empty description (opencode/copilot/cursor/forge). */
+function metaFrontmatterFallback(filePath, name) {
+    return parseSubagentFrontmatter(filePath) ?? { name, description: '' };
+}
+/** Kiro custom-agent JSON: read name/description/model; skip on parse error. */
+function metaJson(filePath, name) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        return { name: cfg.name || name, description: cfg.description || '', model: cfg.model };
+    }
+    catch {
+        return null;
+    }
+}
+/** Goose recipe YAML: title -> name, description; skip on parse error. */
+function metaGooseYaml(filePath, name) {
+    try {
+        const recipe = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+        return { name: recipe?.title || name, description: recipe?.description || '' };
+    }
+    catch {
+        return null;
+    }
+}
+// ── shared fs primitive ──────────────────────────────────────────────────────
+/**
+ * Copy every file in `src` into `dest` (created if missing), applying
+ * `rename` (source filename -> target filename) on the way. Directories in
+ * `src` are skipped -- subagents are flat file sets. Throws on fs error.
+ */
+export function copyDirWithRename(src, dest, rename) {
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    for (const file of fs.readdirSync(src)) {
+        const sourcePath = path.join(src, file);
+        if (!fs.statSync(sourcePath).isFile())
+            continue;
+        const targetName = rename?.[file] ?? file;
+        fs.copyFileSync(sourcePath, path.join(dest, targetName));
+    }
+}
+// ── layout builders ──────────────────────────────────────────────────────────
+/** One flattened `<name><ext>` file per subagent under `subdir`. */
+function flatFile(opts) {
+    const readMeta = opts.readMeta ?? metaFrontmatterSkip;
+    return {
+        dir: (home) => path.join(home, ...opts.subdir),
+        write(dir, sub) {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(safeJoin(dir, `${sub.name}${opts.ext}`), opts.transform(sub.path));
+        },
+        names(dir) {
+            if (!fs.existsSync(dir))
+                return [];
+            return fs
+                .readdirSync(dir)
+                .filter((f) => f.endsWith(opts.ext))
+                .map((f) => f.slice(0, -opts.ext.length));
+        },
+        occupied(dir, name) {
+            return [{ path: safeJoin(dir, `${name}${opts.ext}`), kind: 'file' }];
+        },
+        read(dir, name) {
+            const filePath = path.join(dir, `${name}${opts.ext}`);
+            if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+                return null;
+            const frontmatter = readMeta(filePath, name);
+            if (!frontmatter)
+                return null;
+            return { frontmatter, files: [`${name}${opts.ext}`], path: filePath };
+        },
+    };
+}
+/** A `<name>/` directory holding one generated `<file>` per subagent. */
+function dirFile(opts) {
+    const readMeta = opts.readMeta ?? ((p, name) => metaFrontmatterFallback(p, name));
+    return {
+        dir: (home) => path.join(home, ...opts.subdir),
+        write(dir, sub) {
+            const target = safeJoin(dir, sub.name);
+            fs.mkdirSync(target, { recursive: true });
+            fs.writeFileSync(safeJoin(target, opts.file), opts.transform(sub.path));
+        },
+        names(dir) {
+            if (!fs.existsSync(dir))
+                return [];
+            return fs
+                .readdirSync(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, opts.file)))
+                .map((e) => e.name);
+        },
+        occupied(dir, name) {
+            return [{ path: safeJoin(dir, name), kind: 'dir' }];
+        },
+        read(dir, name) {
+            const filePath = path.join(dir, name, opts.file);
+            if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+                return null;
+            const frontmatter = readMeta(filePath, name);
+            if (!frontmatter)
+                return null;
+            return { frontmatter, files: [opts.file], path: filePath };
+        },
+    };
+}
+/** Copy the whole source directory to `<name>/`, detected by `marker`. */
+function dirCopy(opts) {
+    return {
+        dir: (home) => path.join(home, ...opts.subdir),
+        write(dir, sub) {
+            copyDirWithRename(sub.path, safeJoin(dir, sub.name), opts.rename);
+        },
+        names(dir) {
+            if (!fs.existsSync(dir))
+                return [];
+            return fs
+                .readdirSync(dir, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && fs.existsSync(path.join(dir, d.name, opts.marker)))
+                .map((d) => d.name);
+        },
+        occupied(dir, name) {
+            return [{ path: safeJoin(dir, name), kind: 'dir' }];
+        },
+        read(dir, name) {
+            const markerPath = path.join(dir, name, opts.marker);
+            if (!fs.existsSync(markerPath))
+                return null;
+            // The marker may lack frontmatter; fall back to the first content line.
+            let frontmatter = { name, description: '' };
+            const parsed = parseSubagentFrontmatter(markerPath);
+            if (parsed) {
+                frontmatter = parsed;
+            }
+            else {
+                const content = fs.readFileSync(markerPath, 'utf-8');
+                const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('#'));
+                frontmatter.description = firstLine?.slice(0, 80) || `${name}`;
+            }
+            const subagentDir = path.join(dir, name);
+            const files = fs
+                .readdirSync(subagentDir)
+                .filter((f) => f.endsWith('.md'))
+                .sort();
+            return { frontmatter, files, path: subagentDir };
+        },
+    };
+}
+/**
+ * Kimi (genuinely bespoke): each subagent is a `<name>.yaml` + sibling
+ * `<name>.system.md`, and a managed `_agents-cli.yaml` parent lists them all for
+ * `kimi --agent-file`. The parent index is a cross-item concern, so it is built
+ * in `finalize`, not per-item.
+ */
+const kimiTarget = {
+    dir: (home) => path.join(home, '.kimi-code', 'agents'),
+    write(dir, sub) {
+        writeKimiSubagentFiles(dir, sub.path, sub.name);
+    },
+    names(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        // The parent is `_agents-cli.yaml` (underscore-prefixed, reserved).
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml') && !f.startsWith('_'))
+            .map((f) => f.slice(0, -'.yaml'.length));
+    },
+    occupied(dir, name) {
+        return [
+            { path: safeJoin(dir, `${name}.yaml`), kind: 'file' },
+            { path: safeJoin(dir, `${name}.system.md`), kind: 'file' },
+        ];
+    },
+    read(dir, name) {
+        const yamlPath = path.join(dir, `${name}.yaml`);
+        if (!fs.existsSync(yamlPath) || !fs.statSync(yamlPath).isFile())
+            return null;
+        let description = '';
+        try {
+            const parsed = yaml.parse(fs.readFileSync(yamlPath, 'utf-8'));
+            description = parsed?.agent?.description ?? '';
+        }
+        catch {
+            /* leave description empty */
+        }
+        const files = [`${name}.yaml`];
+        const promptFile = `${name}.system.md`;
+        if (fs.existsSync(path.join(dir, promptFile)))
+            files.push(promptFile);
+        return { frontmatter: { name, description }, files, path: yamlPath };
+    },
+    finalize(dir, synced) {
+        const entries = synced.map((sub) => {
+            const fm = parseSubagentFrontmatter(path.join(sub.path, 'AGENT.md'));
+            return { name: sub.name, description: fm?.description ?? sub.name, relativePath: `./${sub.name}.yaml` };
+        });
+        fs.writeFileSync(safeJoin(dir, KIMI_SUBAGENTS_PARENT_FILE), buildKimiSubagentsParentYaml(entries));
+    },
+};
+// ── the registry ─────────────────────────────────────────────────────────────
+/**
+ * Single source of truth for how each subagents-capable agent stores subagents.
+ * The keys MUST match `capableAgents('subagents')` (the `subagents` flag in
+ * `agents.ts`): the capability flag is the version gate, this table is the shape.
+ */
+export const SUBAGENT_TARGETS = {
+    // Tier 1 -- flat markdown, Claude-compatible flatten.
+    claude: flatFile({ subdir: ['.claude', 'agents'], ext: '.md', transform: transformSubagentForClaude }),
+    gemini: flatFile({ subdir: ['.gemini', 'agents'], ext: '.md', transform: transformSubagentForClaude }),
+    grok: flatFile({ subdir: ['.grok', 'agents'], ext: '.md', transform: transformSubagentForClaude }),
+    droid: flatFile({ subdir: ['.factory', 'droids'], ext: '.md', transform: transformSubagentForDroid }),
+    // Bespoke frontmatter/format, still one flat file.
+    codex: flatFile({ subdir: ['.codex', 'agents'], ext: '.toml', transform: transformSubagentForCodex }),
+    opencode: flatFile({
+        subdir: ['.config', 'opencode', 'agents'],
+        ext: '.md',
+        transform: transformSubagentForOpenCode,
+        readMeta: metaFrontmatterFallback,
+    }),
+    copilot: flatFile({
+        subdir: ['.copilot', 'agents'],
+        ext: '.agent.md',
+        transform: transformSubagentForCopilot,
+        readMeta: metaFrontmatterFallback,
+    }),
+    cursor: flatFile({
+        subdir: ['.cursor', 'agents'],
+        ext: '.md',
+        transform: transformSubagentForCursor,
+        readMeta: metaFrontmatterFallback,
+    }),
+    forge: flatFile({
+        subdir: ['.forge', 'agents'],
+        ext: '.md',
+        transform: transformSubagentForForge,
+        readMeta: metaFrontmatterFallback,
+    }),
+    kiro: flatFile({
+        subdir: ['.kiro', 'agents'],
+        ext: '.json',
+        transform: transformSubagentForKiro,
+        readMeta: metaJson,
+    }),
+    goose: flatFile({
+        subdir: ['.config', 'goose', 'agents'],
+        ext: '.yaml',
+        transform: transformSubagentForGoose,
+        readMeta: metaGooseYaml,
+    }),
+    // Directory layouts.
+    antigravity: dirFile({
+        subdir: ['.gemini', 'config', 'agents'],
+        file: 'agent.md',
+        transform: transformSubagentForAntigravity,
+    }),
+    openclaw: dirCopy({ subdir: ['.openclaw'], marker: 'AGENTS.md', rename: { 'AGENT.md': 'AGENTS.md' } }),
+    // Bespoke multi-file + parent index.
+    kimi: kimiTarget,
+};
+/** The registry entry for `agent`, or undefined if it stores no subagents. */
+export function subagentTarget(agent) {
+    return SUBAGENT_TARGETS[agent];
+}
+// ── generic engine (zero per-agent branches) ─────────────────────────────────
+/**
+ * Materialize central subagent `sub` into `home` for `agent`. Returns whether a
+ * write happened (false when the agent has no registry entry). Throws only on
+ * unexpected fs errors -- bulk callers wrap per-item.
+ */
+export function writeSubagentToHome(agent, home, sub) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return false;
+    target.write(target.dir(home), sub);
+    return true;
+}
+/** Installed subagent names for `agent` under `home` (detector + orphan diff). */
+export function listInstalledSubagentNames(agent, home) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return [];
+    return target.names(target.dir(home));
+}
+/**
+ * Rich listing of subagents installed for `agent` under `home`, with parsed
+ * metadata. Enumerates names, then reads each -- entries whose metadata is
+ * unreadable (per the target's reader) are dropped.
+ */
+export function listInstalledSubagentsRich(agent, home) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return [];
+    const dir = target.dir(home);
+    const out = [];
+    for (const name of target.names(dir)) {
+        const meta = target.read(dir, name);
+        if (!meta)
+            continue;
+        out.push({ name, path: meta.path, files: meta.files, frontmatter: meta.frontmatter });
+    }
+    return out;
+}
+/**
+ * Remove subagent `name` for `agent` from `home` (hard delete). No-op success
+ * when the agent has no registry entry or nothing is installed.
+ */
+export function removeSubagentFromHome(agent, home, name) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return { success: true };
+    try {
+        for (const entry of target.occupied(target.dir(home), name)) {
+            if (!fs.existsSync(entry.path))
+                continue;
+            if (entry.kind === 'dir')
+                fs.rmSync(entry.path, { recursive: true, force: true });
+            else
+                fs.unlinkSync(entry.path);
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: String(err) };
+    }
+}
+/**
+ * Soft-delete subagent `name` for `agent` from `home` into `trashDir`, stamping
+ * each moved entry. Files land as `<basename>.<stamp>`, directories as
+ * `<stamp>/`. No-op success when nothing is installed.
+ */
+export function trashSubagentFromHome(agent, home, name, trashDir, stamp) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return { success: true };
+    try {
+        const present = target.occupied(target.dir(home), name).filter((e) => fs.existsSync(e.path));
+        if (present.length > 0) {
+            fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+            for (const entry of present) {
+                const dest = entry.kind === 'dir'
+                    ? path.join(trashDir, stamp)
+                    : path.join(trashDir, `${path.basename(entry.path)}.${stamp}`);
+                fs.renameSync(entry.path, dest);
+            }
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}