@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/exec.js

@@ -6,6 +6,7 @@
  */
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
+import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
@@ -14,6 +15,7 @@ import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versio
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
+import { getShimsDir } from './state.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -53,6 +55,22 @@ export function resolveMode(agent, requested) {
     }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
 }
+/**
+ * The mode an agent should run in when the caller has no preference.
+ *
+ * Returns the first entry in the agent's `capabilities.modes` table — the
+ * declaration order is the source of truth for "the safest mode this agent
+ * supports." Agents that include `plan` list it first; agents like
+ * antigravity that have no read-only mode list `edit` first.
+ *
+ * Use this when the user did not pass `--mode` explicitly. When the user
+ * *did* pass `--mode plan` and the agent doesn't support it, call
+ * `resolveMode` instead so the user sees a loud error rather than a silent
+ * elevation from read-only to writable.
+ */
+export function defaultModeFor(agent) {
+    return AGENTS[agent].capabilities.modes[0];
+}
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -100,6 +118,7 @@ export function buildExecEnv(options) {
         }
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     else if (options.agent === 'codex') {
         const cwd = options.cwd || process.cwd();
@@ -112,6 +131,7 @@ export function buildExecEnv(options) {
         }
         delete result.CLAUDE_CONFIG_DIR;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     else if (options.agent === 'copilot') {
         // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
@@ -127,11 +147,28 @@ export function buildExecEnv(options) {
         }
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
+        delete result.KIMI_CODE_HOME;
+    }
+    else if (options.agent === 'kimi') {
+        // Kimi honors KIMI_CODE_HOME (relocates ~/.kimi-code, including config,
+        // skills, hooks, sessions). Pin it at the per-version home.
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('kimi', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('kimi', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.KIMI_CODE_HOME = path.join(getVersionHomePath('kimi', version), '.kimi-code');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
     }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
     }
     return {
         ...result,
@@ -167,9 +204,9 @@ export const AGENT_COMMANDS = {
             // "workspace-write but no auto-approval" — closer to plan-as-restraint.
             // True read-only requires --sandbox read-only which we haven't wired.
             plan: ['--sandbox', 'workspace-write'],
-            edit: ['--sandbox', 'workspace-write', '--full-auto'],
-            // skip drops the sandbox entirely; --full-auto then approves anything.
-            skip: ['--full-auto'],
+            edit: ['--sandbox', 'workspace-write', '--dangerously-bypass-approvals-and-sandbox'],
+            // skip drops the sandbox entirely; --dangerously-bypass-approvals-and-sandbox then approves anything.
+            skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
         jsonFlags: ['--json'],
         modelFlag: '--model',
@@ -303,6 +340,18 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',
     },
+    kimi: {
+        base: ['kimi'],
+        promptFlag: '-p',
+        modeFlags: {
+            plan: ['--plan'],
+            edit: [],
+            auto: ['--auto'],
+            skip: ['--yolo'],
+        },
+        jsonFlags: ['--output-format', 'stream-json'],
+        modelFlag: '--model',
+    },
 };
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
@@ -314,9 +363,14 @@ export function buildExecCommand(options) {
     if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
         cmd.splice(1, 1);
     }
-    // Use versioned alias if a specific version was requested (e.g., claude@2.1.98)
+    // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
+    // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
+    // on Linux installs where the shims dir isn't on PATH, spawning the bare
+    // versioned name fails with ENOENT even though `agents view` shows the agent.
     if (options.version && cmd.length > 0) {
-        cmd[0] = `${cmd[0]}@${options.version}`;
+        const versionedName = `${cmd[0]}@${options.version}`;
+        const absPath = path.join(getShimsDir(), versionedName);
+        cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
     // For codex, -c must come before 'exec' subcommand, so we insert at position 1

package/dist/lib/fuzzy.d.ts

@@ -4,11 +4,20 @@
  */
 /** Levenshtein edit distance between two strings. */
 export declare function levenshtein(a: string, b: string): number;
+/**
+ * Damerau-Levenshtein (optimal string alignment) distance.
+ * Counts a transposition of two adjacent characters as a single edit,
+ * so `cladue` -> `claude` is distance 1, matching the user's notion of
+ * "one misspelling."
+ */
+export declare function damerauLevenshtein(a: string, b: string): number;
 export interface FuzzyOptions {
     /** Absolute max edit distance allowed. */
     maxDistance?: number;
     /** Max ratio of distance to input length. If set, effective threshold = min(maxDistance, floor(len * maxRatio)). */
     maxRatio?: number;
+    /** Use Damerau-Levenshtein (transposition = 1 edit) instead of plain Levenshtein. */
+    damerau?: boolean;
 }
 /**
  * Fuzzy match an input string against a list of candidates.
@@ -20,9 +29,10 @@ export declare function fuzzyMatch<T extends string>(input: string, candidates:
  * Based on pairwise distance analysis of candidate pools.
  */
 export declare const FUZZY_PRESETS: {
-    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
+    /** Agents: 1 mistype (insertion/deletion/substitution/transposition). Damerau so `cladue`->`claude` is 1. */
     readonly agents: {
-        readonly maxDistance: 2;
+        readonly maxDistance: 1;
+        readonly damerau: true;
     };
     /** Modes: plan/edit/full all at dist=4, lenient */
     readonly modes: {

package/dist/lib/fuzzy.js

@@ -19,12 +19,36 @@ export function levenshtein(a, b) {
     }
     return dp[m][n];
 }
+/**
+ * Damerau-Levenshtein (optimal string alignment) distance.
+ * Counts a transposition of two adjacent characters as a single edit,
+ * so `cladue` -> `claude` is distance 1, matching the user's notion of
+ * "one misspelling."
+ */
+export function damerauLevenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[m][n];
+}
 /**
  * Fuzzy match an input string against a list of candidates.
  * Returns the single best match within tolerance, or null if no match or ambiguous.
  */
 export function fuzzyMatch(input, candidates, options = {}) {
-    const { maxDistance = 2, maxRatio } = options;
+    const { maxDistance = 2, maxRatio, damerau = false } = options;
     const lower = input.toLowerCase();
     // Reject inputs that are too short - they're too ambiguous
     if (lower.length < 3)
@@ -33,10 +57,11 @@ export function fuzzyMatch(input, candidates, options = {}) {
     const threshold = maxRatio
         ? Math.min(maxDistance, Math.floor(lower.length * maxRatio))
         : maxDistance;
+    const distance = damerau ? damerauLevenshtein : levenshtein;
     // Find all candidates within threshold (excluding exact matches)
     const matches = [];
     for (const candidate of candidates) {
-        const dist = levenshtein(lower, candidate.toLowerCase());
+        const dist = distance(lower, candidate.toLowerCase());
         if (dist > 0 && dist <= threshold) {
             matches.push({ candidate, dist });
         }
@@ -55,8 +80,8 @@ export function fuzzyMatch(input, candidates, options = {}) {
  * Based on pairwise distance analysis of candidate pools.
  */
 export const FUZZY_PRESETS = {
-    /** Agents: min pairwise dist=3 (opencode/openclaw), safe tolerance=2 */
-    agents: { maxDistance: 2 },
+    /** Agents: 1 mistype (insertion/deletion/substitution/transposition). Damerau so `cladue`->`claude` is 1. */
+    agents: { maxDistance: 1, damerau: true },
     /** Modes: plan/edit/full all at dist=4, lenient */
     modes: { maxDistance: 2 },
     /** Efforts: high/xhigh at dist=1, must be strict */

package/dist/lib/git.js

@@ -32,7 +32,14 @@ function installGithooksSymlinks(repoDir) {
         if (fs.lstatSync(dest, { throwIfNoEntry: false })) {
             fs.rmSync(dest);
         }
-        fs.symlinkSync(target, dest);
+        try {
+            fs.symlinkSync(target, dest);
+        }
+        catch (err) {
+            // Windows requires Developer Mode or elevated privileges for symlinks; skip gracefully.
+            if (err.code !== 'EPERM')
+                throw err;
+        }
     }
 }
 /**

package/dist/lib/hooks.d.ts

@@ -110,12 +110,12 @@ export declare function installHooksCentrally(source: string): Promise<{
     errors: string[];
 }>;
 /**
- * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents/.system/hooks/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse hook manifests. Reads system hooks from ~/.agents-system/hooks.yaml
+ * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
  * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
  * A user entry with `enabled: false` disables the system-shipped hook of

package/dist/lib/hooks.js

@@ -11,8 +11,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
-import { supports, explainSkip } from './capabilities.js';
+import { AGENTS, agentConfigDirName } from './agents.js';
+import { supports, explainSkip, capableAgents } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
@@ -117,7 +117,7 @@ function isExecutable(mode) {
 function getHooksDir(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    return path.join(home, `.${agentId}`, agent.hooksDir);
+    return path.join(home, agentConfigDirName(agentId), agent.hooksDir);
 }
 function getProjectHooksDirs(agentId, cwd) {
     const agent = AGENTS[agentId];
@@ -324,7 +324,7 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
     }
     // User-scoped hooks (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userDir = path.join(home, `.${agentId}`, agent.hooksDir);
+    const userDir = path.join(home, agentConfigDirName(agentId), agent.hooksDir);
     const userHooks = listHookEntriesFromDir(userDir);
     for (const hook of userHooks) {
         addHook(hook, 'user', agentId);
@@ -363,7 +363,7 @@ export async function installHooks(source, agents, options = {}) {
  */
 export function getVersionHooksDir(agent, version) {
     const home = getVersionHomePath(agent, version);
-    return path.join(home, `.${agent}`, AGENTS[agent].hooksDir);
+    return path.join(home, agentConfigDirName(agent), AGENTS[agent].hooksDir);
 }
 /**
  * List hook entries in a specific version home.
@@ -489,7 +489,7 @@ export function removeHookFromVersion(agent, version, hookName) {
  */
 export function iterHooksCapableVersions(filter) {
     const pairs = [];
-    const hookAgents = HOOKS_CAPABLE_AGENTS;
+    const hookAgents = capableAgents('hooks');
     const agents = filter?.agent ? [filter.agent] : hookAgents;
     for (const agent of agents) {
         if (!hookAgents.includes(agent))
@@ -592,7 +592,7 @@ export async function installHooksCentrally(source) {
     return { installed, errors };
 }
 /**
- * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents/.system/hooks/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralHooks() {
@@ -609,7 +609,7 @@ export function listCentralHooks() {
     return results;
 }
 /**
- * Parse hook manifests. Reads system hooks from ~/.agents-system/hooks.yaml
+ * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
  * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
  * A user entry with `enabled: false` disables the system-shipped hook of
@@ -663,7 +663,7 @@ const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart
  * Register hooks as lifecycle events in an agent's config.
  * Reads hooks.yaml manifest, merges into the agent's config file(s).
  * Only manages hooks whose command paths are under ~/.agents/hooks/ or
- * ~/.agents-system/hooks/. Does not remove user-added hooks.
+ * ~/.agents/.system/hooks/. Does not remove user-added hooks.
  *
  * @param agentsDirOverride - When provided, treats this single dir as the
  *   only managed hook root. Used by tests to inject a temp path. In normal
@@ -702,7 +702,7 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
     const localHooksDir = !overrideRoots
-        ? path.join(versionHome, `.${agentId}`, AGENTS[agentId].hooksDir)
+        ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
         : null;
     const resolveScript = (script) => {
         if (overrideRoots) {
@@ -740,6 +740,9 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'grok') {
         return registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'kimi') {
+        return registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes);
+    }
     return { registered: [], errors: [] };
 }
 /**
@@ -1217,3 +1220,87 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
     }
     return { registered, errors };
 }
+function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes) {
+    const registered = [];
+    const errors = [];
+    const configPath = path.join(versionHome, '.kimi-code', 'config.toml');
+    // Read existing config.toml
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            errors.push('Failed to parse config.toml');
+            return { registered, errors };
+        }
+    }
+    // Build set of current manifest command paths for GC
+    const currentManifestPaths = new Set();
+    for (const [hookName, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
+        if (resolved)
+            currentManifestPaths.add(resolved);
+    }
+    // Remove stale managed hooks from existing hooks array
+    let hooksArray = [];
+    if (Array.isArray(config.hooks)) {
+        hooksArray = config.hooks;
+    }
+    const filteredHooks = hooksArray.filter((h) => {
+        const cmd = typeof h.command === 'string' ? h.command : '';
+        if (!cmd)
+            return true;
+        const isManaged = managedPrefixes.some((p) => cmd.startsWith(p));
+        if (!isManaged)
+            return true;
+        return currentManifestPaths.has(cmd);
+    });
+    // Add/update hooks from manifest
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        const timeout = hookDef.timeout ?? 30;
+        for (const event of hookDef.events) {
+            const matcher = hookDef.matcher;
+            // Find existing hook with same event, command, and matcher
+            const existingIdx = filteredHooks.findIndex((h) => {
+                const sameEvent = h.event === event;
+                const sameCmd = h.command === commandPath;
+                const sameMatcher = (h.matcher ?? '') === (matcher ?? '');
+                return sameEvent && sameCmd && sameMatcher;
+            });
+            const hookEntry = {
+                event,
+                command: commandPath,
+                timeout,
+            };
+            if (matcher) {
+                hookEntry.matcher = matcher;
+            }
+            if (existingIdx >= 0) {
+                filteredHooks[existingIdx] = hookEntry;
+            }
+            else {
+                filteredHooks.push(hookEntry);
+            }
+            registered.push(`${name} -> ${event}`);
+        }
+    }
+    config.hooks = filteredHooks;
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Failed to write config.toml: ${err.message}`);
+    }
+    return { registered, errors };
+}

package/dist/lib/mcp.js

@@ -13,7 +13,8 @@ import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
-import { MCP_CAPABLE_AGENTS, AGENTS } from './agents.js';
+import { AGENTS } from './agents.js';
+import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 /**
  * Parse an MCP server config from a YAML file.
@@ -312,6 +313,31 @@ function installMcpToCursorConfig(server, versionHome) {
 /**
  * Install MCP server to OpenCode config file.
  */
+function installMcpToKimiConfig(server, versionHome) {
+    const configPath = path.join(versionHome, '.kimi-code', 'mcp.json');
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        config.mcpServers = {};
+    }
+    const mcpServers = config.mcpServers;
+    if (server.config.transport === 'stdio') {
+        mcpServers[server.name] = {
+            command: server.config.command,
+            args: server.config.args || [],
+            env: server.config.env || {},
+        };
+    }
+    else {
+        mcpServers[server.name] = {
+            url: server.config.url,
+        };
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
 function installMcpToOpenCodeConfig(server, versionHome) {
     const configPath = path.join(versionHome, '.opencode', 'opencode.jsonc');
     let config = {};
@@ -354,7 +380,7 @@ function installMcpToOpenCodeConfig(server, versionHome) {
  * For others: edits config files directly
  */
 export function installMcpServers(agentId, version, versionHome, mcpNames, options = {}) {
-    if (!MCP_CAPABLE_AGENTS.includes(agentId)) {
+    if (!isCapable(agentId, 'mcp')) {
         return { success: true, applied: [], errors: [] };
     }
     const servers = getMcpServersByName(mcpNames, { cwd: options.cwd });
@@ -394,6 +420,10 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 // For now the general sync + toml editing via agents mcp works via the path helpers.
                 applied.push(server.name);
             }
+            else if (agentId === 'kimi') {
+                installMcpToKimiConfig(server, versionHome);
+                applied.push(server.name);
+            }
         }
         catch (err) {
             const message = err.message;

package/dist/lib/migrate.d.ts

@@ -4,5 +4,56 @@
  * Called from postinstall and as a command-time fallback from agents view/use/pull.
  * Each migration is guarded by an existence check so re-running is safe.
  */
+/**
+ * Fold ~/.agents-system/ into ~/.agents/.system/.
+ *
+ * MUST run first in runMigration() — every other migrator reads SYSTEM_DIR
+ * (the new path), so the contents have to be there before they execute.
+ *
+ * Strategy:
+ *   1. If legacy dir doesn't exist or is already a symlink, no-op.
+ *   2. If new path doesn't exist yet, rename in one shot (fast path).
+ *   3. If both exist (mid-migration / re-run on partially-migrated state),
+ *      merge legacy → new with new winning on collision, then drop legacy.
+ *
+ * After the contents move, the legacy path becomes a symlink → SYSTEM_DIR
+ * so external tooling that still references ~/.agents-system/ keeps
+ * resolving correctly. The symlink is harmless on its own and can be
+ * removed with `rm ~/.agents-system` once everything has updated.
+ *
+ * Idempotent: re-running converges to "contents at SYSTEM_DIR, symlink at
+ * LEGACY_SYSTEM_DIR" without duplicating data.
+ */
+export declare function foldLegacySystemRepo(): void;
+/**
+ * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
+ * inside every installed agent version-home, and rewrite cross-references in
+ * `known_marketplaces.json` and the agent's `settings.json`.
+ *
+ * A previous dev build of `agents-cli` named the extras-aliased repo's
+ * synthesized marketplace dir `extras-extras` (double "extras" because the alias
+ * itself was `extras`). The new naming convention is `agents-<alias>`, so the
+ * directory should be `agents-extras`. Without this migration the orphan dir
+ * stays on disk and Claude Code loads two parallel marketplaces (the legacy
+ * `extras-extras` entry from `known_marketplaces.json` plus the freshly
+ * synthesized `agents-extras` from the new code path).
+ *
+ * Strategy per `<historyDir>/versions/<agent>/<ver>/home/.<agent>/plugins/`:
+ *   1. `marketplaces/extras-extras/` → `marketplaces/agents-extras/`
+ *      (drops `extras-extras/` outright when `agents-extras/` already exists —
+ *      previous incomplete migration ran)
+ *   2. Inside the renamed dir's `.claude-plugin/marketplace.json`, set
+ *      `"name": "agents-extras"`.
+ *   3. In `<configDir>/plugins/known_marketplaces.json`, rename the
+ *      `extras-extras` key to `agents-extras` and rewrite `source.path` /
+ *      `installLocation`.
+ *   4. In `<configDir>/settings.json`'s `enabledPlugins`, rename every
+ *      `<plugin>@extras-extras` key to `<plugin>@agents-extras` (preserving
+ *      its boolean value, skipping if the new key already exists).
+ *
+ * Idempotent: re-running converges without further writes once everything is on
+ * the new name.
+ */
+export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;