@phnx-labs/agents-cli 1.20.5 → 1.20.6

package/dist/lib/exec.js

@@ -118,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();
@@ -130,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,
@@ -145,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,
@@ -322,14 +341,15 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
     },
     kimi: {
-        base: ['kimi-code'],
+        base: ['kimi'],
         promptFlag: '-p',
         modeFlags: {
-            plan: [],
+            plan: ['--plan'],
             edit: [],
-            skip: [],
+            auto: ['--auto'],
+            skip: ['--yolo'],
         },
-        jsonFlags: [],
+        jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
 };

package/dist/lib/migrate.js

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { AGENTS, agentConfigDirName } from './agents.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -672,12 +673,13 @@ function repairAgentConfigSymlinks() {
     }
     let repaired = 0;
     for (const { agent, version } of defaults) {
-        const userTarget = fs.existsSync(path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`))
-            ? path.join(HISTORY_DIR, 'versions', agent, version, 'home', `.${agent}`)
-            : path.join(USER_DIR, 'versions', agent, version, 'home', `.${agent}`);
+        const configDirName = agent in AGENTS ? agentConfigDirName(agent) : `.${agent}`;
+        const userTarget = fs.existsSync(path.join(HISTORY_DIR, 'versions', agent, version, 'home', configDirName))
+            ? path.join(HISTORY_DIR, 'versions', agent, version, 'home', configDirName)
+            : path.join(USER_DIR, 'versions', agent, version, 'home', configDirName);
         if (!fs.existsSync(userTarget))
             continue;
-        const symlinkPath = path.join(HOME, `.${agent}`);
+        const symlinkPath = path.join(HOME, configDirName);
         let stat = null;
         try {
             stat = fs.lstatSync(symlinkPath);

package/dist/lib/permissions.d.ts

@@ -144,6 +144,29 @@ export type GrokRule = {
     tool: string;
     pattern?: string;
 };
+export type KimiRule = {
+    decision: 'allow' | 'deny';
+    pattern: string;
+};
+/**
+ * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
+ * Kimi (`~/.kimi-code/config.toml`) reads rules of the form
+ *   [[permission.rules]]
+ *   decision = "allow"
+ *   pattern  = "Bash(git status*)"
+ * Tool names are capitalized and the Bash arg-glob uses a trailing `*` (no
+ * Claude `:*` separator). Without this conversion the canonical strings match
+ * nothing in Kimi's engine and every tool call falls through to a prompt.
+ *
+ * Each `:*` Bash rule expands to TWO patterns (`cmd*` and `cmd*​/**`) so the
+ * command auto-approves whether or not its arguments contain a slash — see
+ * `kimiBashPatterns` for why Kimi's picomatch matcher needs both.
+ */
+export declare function convertToKimiFormat(set: PermissionSet): {
+    permission: {
+        rules: KimiRule[];
+    };
+};
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }

package/dist/lib/permissions.js

@@ -557,6 +557,94 @@ function canonicalToGrokRule(perm, action) {
     }
     return { action, tool, pattern };
 }
+/**
+ * Parse a canonical permission string preserving the tool's original casing.
+ * `parseCanonicalPattern` lowercases the tool name, which is fine for Grok
+ * (lowercase tool vocabulary) but wrong for Kimi, whose tool names are
+ * capitalized (`Bash`, `Read`, `Grep`). Bare tool names (no parens, e.g.
+ * `Read` or an MCP id like `mcp__server__tool`) return `pattern: null`.
+ */
+function parseCanonicalPreserveCase(perm) {
+    const m = perm.match(/^([\w-]+)\((.*)\)$/);
+    if (m)
+        return { tool: m[1], pattern: m[2] };
+    return { tool: perm, pattern: null };
+}
+/**
+ * Translate a canonical Bash arg-glob (`cmd:*`) into the Kimi pattern(s) that
+ * actually match that command's invocations.
+ *
+ * Kimi matches Bash arg-globs with picomatch, where `*` does NOT cross `/` and a
+ * `**` only globstars when it is its own path segment (`*​/**`, `**​/`). A plain
+ * `cmd*` therefore matches `git status -s` but NOT `git push origin feat/x` or
+ * `cat dir/file` — any argument containing a slash falls through to a prompt
+ * (verified interactively against kimi 0.12.1). We emit TWO patterns so the
+ * command auto-approves whether its args contain a slash or not:
+ *   - `cmd*`     — no-slash args (and the bare command; `*` is zero-or-more).
+ *   - `cmd*​/**` — args with a path: `*` consumes up to the first `/`, then the
+ *                 bounded globstar crosses the remaining slashes.
+ * "git push:*" -> ["git push*", "git push*​/**"].
+ */
+function kimiBashPatterns(pattern) {
+    if (pattern === '*' || pattern === '**')
+        return ['*'];
+    if (pattern.endsWith(':*')) {
+        const prefix = pattern.slice(0, -2);
+        return [`${prefix}*`, `${prefix}*/**`];
+    }
+    // Exact command (no `:*`, e.g. `env`, `pwd`, `true`) — no path args expected.
+    return [pattern];
+}
+function canonicalToKimiRules(perm, decision) {
+    if (BLANKET_BASH_FORMS.has(perm)) {
+        return [{ decision, pattern: 'Bash' }];
+    }
+    const { tool, pattern } = parseCanonicalPreserveCase(perm);
+    // Bare tool name (no parens) — name-only match. Covers `Read`, `Grep`, and
+    // MCP tool ids, which Kimi can only match by name anyway.
+    if (pattern === null) {
+        return [{ decision, pattern: tool }];
+    }
+    if (tool.toLowerCase() === 'bash') {
+        return kimiBashPatterns(pattern).map((p) => ({
+            decision,
+            pattern: p === '*' ? 'Bash' : `Bash(${p})`,
+        }));
+    }
+    // Non-Bash built-ins (Read/Write/Edit/Grep/Glob/WebFetch...) share Kimi's
+    // capitalized tool vocabulary, so pass the tool+pattern through. A `**`/`*`
+    // glob means "any" — collapse to a name-only rule.
+    if (pattern === '*' || pattern === '**') {
+        return [{ decision, pattern: tool }];
+    }
+    return [{ decision, pattern: `${tool}(${pattern})` }];
+}
+/**
+ * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
+ * Kimi (`~/.kimi-code/config.toml`) reads rules of the form
+ *   [[permission.rules]]
+ *   decision = "allow"
+ *   pattern  = "Bash(git status*)"
+ * Tool names are capitalized and the Bash arg-glob uses a trailing `*` (no
+ * Claude `:*` separator). Without this conversion the canonical strings match
+ * nothing in Kimi's engine and every tool call falls through to a prompt.
+ *
+ * Each `:*` Bash rule expands to TWO patterns (`cmd*` and `cmd*​/**`) so the
+ * command auto-approves whether or not its arguments contain a slash — see
+ * `kimiBashPatterns` for why Kimi's picomatch matcher needs both.
+ */
+export function convertToKimiFormat(set) {
+    const rules = [];
+    for (const perm of set.allow) {
+        rules.push(...canonicalToKimiRules(perm, 'allow'));
+    }
+    if (set.deny) {
+        for (const perm of set.deny) {
+            rules.push(...canonicalToKimiRules(perm, 'deny'));
+        }
+    }
+    return { permission: { rules } };
+}
 /**
  * Convert canonical permission set to OpenCode format.
  * OpenCode uses: { permission: { bash: { "git *": "allow", "rm *": "deny" } } }
@@ -1107,13 +1195,7 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             if (fs.existsSync(configPath)) {
                 config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
             }
-            const newRules = [];
-            for (const allow of set.allow) {
-                newRules.push({ decision: 'allow', pattern: allow });
-            }
-            for (const deny of set.deny || []) {
-                newRules.push({ decision: 'deny', pattern: deny });
-            }
+            const newRules = convertToKimiFormat(set).permission.rules;
             if (merge) {
                 const existingPermission = (typeof config.permission === 'object' && config.permission !== null && !Array.isArray(config.permission))
                     ? config.permission

package/dist/lib/plugin-marketplace.js

@@ -26,9 +26,9 @@
  * the catalog name and on-disk layout are derived, never hard-coded per call.
  */
 import * as fs from 'fs';
+import { agentConfigDirName } from './agents.js';
 import * as path from 'path';
 import { getPluginsDir, getEnabledExtraRepos, getProjectPluginsDir } from './state.js';
-import { agentConfigDirName } from './agents.js';
 /**
  * Canonical name for the user-repo marketplace (~/.agents/plugins/). Kept as an
  * exported constant for callers that operate on the user repo directly and for

package/dist/lib/project-launch.d.ts

@@ -60,6 +60,11 @@ export interface LaunchSyncResult {
 /**
  * Run the launch-time project compile. Safe to call on every agent launch:
  * each step is idempotent and skips when its inputs are missing.
+ *
+ * After a successful run, touches the shim-side skip-fast sentinel at
+ * `~/.agents/.cache/launch-sync/<agent>@<version>@<projectslug>` so the next
+ * shim invocation can skip the node spawn entirely when no source dir is
+ * newer than the sentinel (shim schema v17+).
  */
 export declare function runLaunchSync(opts: LaunchSyncOptions): LaunchSyncResult;
 export { pluginInstallDir };

package/dist/lib/project-launch.js

@@ -42,6 +42,7 @@
  */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
@@ -52,6 +53,11 @@ import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, ad
 /**
  * Run the launch-time project compile. Safe to call on every agent launch:
  * each step is idempotent and skips when its inputs are missing.
+ *
+ * After a successful run, touches the shim-side skip-fast sentinel at
+ * `~/.agents/.cache/launch-sync/<agent>@<version>@<projectslug>` so the next
+ * shim invocation can skip the node spawn entirely when no source dir is
+ * newer than the sentinel (shim schema v17+).
  */
 export function runLaunchSync(opts) {
     const result = {
@@ -74,8 +80,39 @@ export function runLaunchSync(opts) {
     result.workspaceSkipped = mirror.skipped;
     // Step 3: scoped plugin marketplaces
     result.marketplaces = synthesizeScopedMarketplaces(opts.agent, opts.version, opts.cwd);
+    // Touch the shim's skip-fast sentinel. Best-effort — if this fails the
+    // shim just won't skip on the next launch, which is correct fallback.
+    touchLaunchSentinel(opts.agent, opts.version, opts.cwd);
     return result;
 }
+/**
+ * Path of the shim's skip-fast sentinel for this (agent, version, cwd) tuple.
+ * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation):
+ *   slug = PWD with `/` → `_` and ` ` → `_`
+ *
+ * Cache leak note: this dir accumulates one zero-byte file per
+ * (agent, version, project) tuple ever launched. Disk impact is negligible
+ * (inodes only). A periodic GC belongs in `agents prune` — follow-up.
+ */
+function launchSentinelPath(agent, version, cwd) {
+    const slug = cwd.replace(/\//g, '_').replace(/ /g, '_');
+    // Prefer $HOME (respects test overrides + matches bash's $HOME expansion in
+    // the shim), fall back to os.homedir() so the lookup never resolves to '/'
+    // if HOME is somehow unset.
+    const home = process.env.HOME || os.homedir();
+    return path.join(home, '.agents', '.cache', 'launch-sync', `${agent}@${version}@${slug}`);
+}
+function touchLaunchSentinel(agent, version, cwd) {
+    try {
+        const sentinel = launchSentinelPath(agent, version, cwd);
+        fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+        // Empty content — purely an mtime carrier for the shim's `[ -nt ]` compare.
+        fs.writeFileSync(sentinel, '');
+    }
+    catch {
+        // best-effort
+    }
+}
 const CLAUDE_MIRROR_PLANS = [
     { srcSubdir: 'subagents', destSubdir: 'agents', entriesAreDirs: false },
     { srcSubdir: 'commands', destSubdir: 'commands', entriesAreDirs: false },

package/dist/lib/pty-server.js

@@ -155,14 +155,17 @@ export async function runPtyServer() {
     let nodePty;
     let XtermTerminal;
     try {
-        nodePty = await import('node-pty');
+        // The Homebridge multiarch fork of node-pty: API-identical (same 1.x N-API
+        // codebase) but ships prebuilt binaries for Linux glibc + musl, x64 + arm64
+        // (plus macOS/Windows), so no compiler is needed on Linux/Alpine/arm64.
+        nodePty = await import('@homebridge/node-pty-prebuilt-multiarch');
         // Handle ESM default export
         if (nodePty.default?.spawn)
             nodePty = nodePty.default;
         // Ensure spawn-helper is executable (bun install doesn't set +x on prebuilds)
         try {
             const __dirname = path.dirname(fileURLToPath(import.meta.url));
-            const ptyBase = path.resolve(__dirname, '..', '..', 'node_modules', 'node-pty');
+            const ptyBase = path.resolve(__dirname, '..', '..', 'node_modules', '@homebridge', 'node-pty-prebuilt-multiarch');
             const helpers = [
                 path.join(ptyBase, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
                 path.join(ptyBase, 'build', 'Release', 'spawn-helper'),
@@ -176,8 +179,8 @@ export async function runPtyServer() {
         catch { }
     }
     catch (err) {
-        console.error('node-pty is required for PTY support.');
-        console.error('Install: cd ' + '~/agents-cli && bun add node-pty');
+        console.error('node-pty (@homebridge/node-pty-prebuilt-multiarch) is required for PTY support.');
+        console.error('Install: bun add @homebridge/node-pty-prebuilt-multiarch');
         process.exit(1);
     }
     try {

package/dist/lib/resources/rules.js

@@ -9,9 +9,9 @@
  * - All unique subrules across layers are unioned
  */
 import * as fs from 'fs';
+import { agentConfigDirName } from '../agents.js';
 import * as path from 'path';
 import { getSystemRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { agentConfigDirName } from '../agents.js';
 const SUBRULES_DIR = 'subrules';
 const SUBRULES_README = 'README.md';
 /**

package/dist/lib/resources/skills.js

@@ -5,10 +5,10 @@
  * Format is the same for all agents. Resolution order: project > user > system.
  */
 import * as fs from 'fs';
+import { agentConfigDirName } from '../agents.js';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getSystemSkillsDir, getUserSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { agentConfigDirName } from '../agents.js';
 /** Default provider uses the real state module. */
 const defaultProvider = {
     getSystemSkillsDir,

package/dist/lib/resources.d.ts

@@ -36,6 +36,8 @@ export interface ResourceEntry {
     name: string;
     path: string;
     scope: 'user' | 'project';
+    /** One-line description pulled from frontmatter; not all resource kinds have one. */
+    description?: string;
 }
 /** A skill resource entry with optional rule count. */
 export interface SkillResourceEntry extends ResourceEntry {

package/dist/lib/resources.js

@@ -106,7 +106,7 @@ export function getAgentResources(agentId, options = {}) {
     const commands = [];
     for (const cmd of listInstalledCommandsWithScope(agentId, cwd, { home })) {
         if (shouldInclude(cmd.scope)) {
-            commands.push({ name: cmd.name, path: cmd.path, scope: cmd.scope });
+            commands.push({ name: cmd.name, path: cmd.path, scope: cmd.scope, description: cmd.description });
         }
     }
     // Skills
@@ -119,6 +119,7 @@ export function getAgentResources(agentId, options = {}) {
                 path: skill.path,
                 scope: skill.scope,
                 ruleCount: skill.ruleCount,
+                description: skill.metadata.description || undefined,
             });
         }
     }

package/dist/lib/rotate.js

@@ -6,10 +6,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'yaml';
 import { getAccountInfo } from './agents.js';
-import { readMeta, writeMeta, getHelpersDir, getUserAgentsDir } from './state.js';
+import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
+import { getProjectRunConfigs } from './run-config.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
@@ -33,22 +33,10 @@ export function normalizeRunStrategy(value) {
 }
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export function getProjectRunStrategy(agent, startPath) {
-    let dir = path.resolve(startPath);
-    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
-    while (dir !== path.dirname(dir)) {
-        const manifestPath = path.join(dir, 'agents.yaml');
-        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
-            try {
-                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                const strategy = normalizeRunStrategy(parsed?.run?.[agent]?.strategy);
-                if (strategy)
-                    return strategy;
-            }
-            catch {
-                // Ignore malformed project config and keep walking, matching version resolution.
-            }
-        }
-        dir = path.dirname(dir);
+    for (const runConfig of getProjectRunConfigs(startPath)) {
+        const strategy = normalizeRunStrategy(runConfig[agent]?.strategy);
+        if (strategy)
+            return strategy;
     }
     return null;
 }

package/dist/lib/run-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import type { RunConfig } from './types.js';
+/** Return project-local run configs from nearest directory upward. */
+export declare function getProjectRunConfigs(startPath?: string): RunConfig[];

package/dist/lib/run-config.js

@@ -0,0 +1,35 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Return project-local run configs from nearest directory upward. */
+export function getProjectRunConfigs(startPath = process.cwd()) {
+    const configs = [];
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (isRecord(parsed?.run)) {
+                    configs.push(parsed.run);
+                }
+            }
+            catch {
+                // Ignore malformed project config and keep walking.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return configs;
+}

package/dist/lib/run-defaults.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Selector-based defaults for `agents run`.
+ *
+ * Stored under agents.yaml:
+ *
+ *   run:
+ *     defaults:
+ *       "claude:*":
+ *         mode: auto
+ *         model: opus
+ *       "claude:2.1.45":
+ *         mode: plan
+ */
+import type { AgentId, Mode, RunConfig, RunDefaults } from './types.js';
+export interface ParsedRunDefaultSelector {
+    agent: AgentId;
+    version: string;
+    selector: string;
+}
+export interface ResolvedRunDefaults extends RunDefaults {
+    sources: {
+        mode?: string;
+        model?: string;
+    };
+}
+export interface RunDefaultEntry {
+    selector: string;
+    defaults: RunDefaults;
+}
+type RunDefaultsInput = {
+    mode?: unknown;
+    model?: unknown;
+};
+export declare function normalizeRunDefaultMode(input: string): Mode;
+export declare function parseRunDefaultSelector(input: string): ParsedRunDefaultSelector;
+export declare function resolveRunDefaultsFromConfig(runConfig: RunConfig | undefined, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaultsFromConfigs(runConfigs: Array<RunConfig | undefined>, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaults(agent: AgentId, version?: string | null, startPath?: string): ResolvedRunDefaults;
+export declare function listRunDefaults(): RunDefaultEntry[];
+export declare function setRunDefault(selectorInput: string, defaultsInput: RunDefaultsInput): RunDefaultEntry;
+export declare function unsetRunDefault(selectorInput: string): boolean;
+export {};