@phnx-labs/agents-cli 1.20.5 → 1.20.7

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/platform/exec.d.ts

@@ -0,0 +1,9 @@
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;

package/dist/lib/platform/exec.js

@@ -0,0 +1,24 @@
+/**
+ * Executable resolution, platform-aware.
+ */
+import { execFileSync } from 'child_process';
+/** PATH-search command for the platform: `where` on Windows, else `which`. */
+export function whichCommand(platform = process.platform) {
+    return platform === 'win32' ? 'where' : 'which';
+}
+/**
+ * Resolve an executable name to its absolute path via the OS PATH search, or
+ * `null` if not found. On Windows `where` can return several lines (one per
+ * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
+ * shell would actually run, matching `which` semantics on POSIX.
+ */
+export function findExecutable(name, platform = process.platform) {
+    try {
+        const out = execFileSync(whichCommand(platform), [name], { encoding: 'utf-8' });
+        const first = out.trim().split(/\r?\n/)[0]?.trim();
+        return first || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/platform/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export declare const IS_WINDOWS: boolean;
+export declare const IS_MACOS: boolean;
+export declare const IS_LINUX: boolean;
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

package/dist/lib/platform/index.js

@@ -0,0 +1,20 @@
+/**
+ * Platform abstraction — the ONE place OS-divergent behavior is decided.
+ *
+ * Consumers express intent (`looksLikePath`, `findExecutable`, `isAlive`) instead
+ * of scattering `process.platform === 'win32'` checks. Each helper that has an
+ * observable branch accepts an explicit `platform` argument (defaulting to
+ * `process.platform`), so all three OSes are unit-testable on any host.
+ *
+ * Modules grow per concern as features land:
+ *   paths   — path classification + normalization
+ *   exec    — executable resolution
+ *   process — process liveness / control
+ * (ipc + shell follow when their consumers migrate off inline branches.)
+ */
+export const IS_WINDOWS = process.platform === 'win32';
+export const IS_MACOS = process.platform === 'darwin';
+export const IS_LINUX = process.platform === 'linux';
+export * from './paths.js';
+export * from './exec.js';
+export * from './process.js';

package/dist/lib/platform/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export declare function looksLikePath(query: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export declare function toComparablePath(p: string, platform?: NodeJS.Platform): string;
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export declare function homeDir(): string;

package/dist/lib/platform/paths.js

@@ -0,0 +1,49 @@
+/**
+ * Path classification + normalization, platform-aware.
+ */
+import * as os from 'os';
+/** Windows drive-letter absolute path: `C:\` or `C:/`. */
+const WIN_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+/**
+ * Does this positional argument look like a filesystem path (vs a search term)?
+ *
+ * POSIX markers (`.`, `./`, `../`, `/`, `~`) are recognized on every platform —
+ * identical to the long-standing behavior. Windows-only shapes (drive-letter
+ * `C:\…`, UNC `\\…`, backslash-relative `.\` / `..\`) are recognized ONLY on
+ * win32, so a literal `C:\repo` typed on macOS/Linux still resolves as a search
+ * term — i.e. no behavior change off Windows.
+ */
+export function looksLikePath(query, platform = process.platform) {
+    if (query === '.' ||
+        query.startsWith('./') ||
+        query.startsWith('../') ||
+        query.startsWith('/') ||
+        query.startsWith('~')) {
+        return true;
+    }
+    if (platform === 'win32') {
+        return (WIN_DRIVE_RE.test(query) ||
+            query.startsWith('\\\\') ||
+            query.startsWith('.\\') ||
+            query.startsWith('..\\'));
+    }
+    return false;
+}
+/**
+ * Normalize a path for comparison/prefix-matching: backslashes folded to forward
+ * slashes and lowercased on Windows (its filesystem is case-insensitive). On
+ * POSIX the input is returned unchanged, so callers behave exactly as before.
+ */
+export function toComparablePath(p, platform = process.platform) {
+    if (platform === 'win32')
+        return p.replace(/\\/g, '/').toLowerCase();
+    return p;
+}
+/**
+ * Canonical home directory. Use this instead of `process.env.HOME`, which is
+ * unset on Windows (where the home is `USERPROFILE`); `os.homedir()` resolves
+ * correctly on all three platforms.
+ */
+export function homeDir() {
+    return os.homedir();
+}

package/dist/lib/platform/process.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export declare function isAlive(pid: number): boolean;

package/dist/lib/platform/process.js

@@ -0,0 +1,22 @@
+/**
+ * Process liveness / control, platform-aware.
+ */
+/**
+ * Is a process with this PID currently alive?
+ *
+ * Uses the signal-0 probe, which is cross-platform in Node (Windows included —
+ * it maps to OpenProcess). Returns false on any error (no such process, or no
+ * permission to signal it), matching the long-standing call sites that treat a
+ * throw from `process.kill(pid, 0)` as "not running".
+ */
+export function isAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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-client.js

@@ -12,6 +12,7 @@ import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
+const IS_WINDOWS = process.platform === 'win32';
 /**
  * Send a request to the PTY server and return the response.
  * Auto-starts the server if not running.
@@ -41,11 +42,13 @@ async function ensureServer() {
     });
     child.unref();
     fs.closeSync(logFd);
-    // Wait for socket to appear
+    // Wait for the server to become reachable. On Unix the socket file appearing is
+    // a cheap readiness signal; on Windows the named pipe is not a filesystem object
+    // (fs.existsSync always returns false), so we just attempt the ping directly.
     const socketPath = getSocketPath();
     const deadline = Date.now() + 5000;
     while (Date.now() < deadline) {
-        if (fs.existsSync(socketPath)) {
+        if (IS_WINDOWS || fs.existsSync(socketPath)) {
             // Verify we can connect
             try {
                 await sendRequest({ action: 'ping' });
@@ -70,9 +73,11 @@ function getServerSpawnArgs() {
         }
     }
     catch { }
-    // Fallback: use the globally installed agents command
+    // Fallback: use the globally installed agents command. `which` is Unix-only;
+    // Windows uses `where`, which can return multiple lines — take the first.
     try {
-        const agentsBin = execSync('which agents', { encoding: 'utf-8' }).trim();
+        const lookup = IS_WINDOWS ? 'where agents' : 'which agents';
+        const agentsBin = execSync(lookup, { encoding: 'utf-8' }).split(/\r?\n/)[0].trim();
         if (agentsBin) {
             return { bin: agentsBin, args: ['pty', '_server'] };
         }
@@ -86,7 +91,10 @@ function getServerSpawnArgs() {
 function sendRequest(req) {
     return new Promise((resolve, reject) => {
         const socketPath = getSocketPath();
-        if (!fs.existsSync(socketPath)) {
+        // On Unix a missing socket file means the server isn't up — fail fast with a
+        // clear message. On Windows the named pipe isn't a filesystem object, so we
+        // skip the probe and let createConnection surface ENOENT/connection errors.
+        if (!IS_WINDOWS && !fs.existsSync(socketPath)) {
             reject(new Error('PTY server socket not found. Is the server running?'));
             return;
         }

package/dist/lib/pty-server.d.ts

@@ -18,7 +18,30 @@
  * Returns null on any error so callers can skip the guard rather than crash.
  */
 export declare function captureProcessStartTime(pid: number): string | null;
-/** Get the unix socket path for the PTY server. */
+/**
+ * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
+ * finishes — that line drives completion detection in the exec/read flow.
+ * The separator and exit-code variable are shell-family specific:
+ *   POSIX sh/zsh/bash : `cmd; echo "S:$?"`
+ *   PowerShell        : `cmd; echo "S:$LASTEXITCODE"`
+ *   cmd.exe           : `cmd & echo S:%errorlevel%`  (`&` always runs the echo)
+ * Only the completion marker matters; the numeric exit code is informational
+ * (the authoritative code comes from node-pty's onExit).
+ */
+export declare function buildSentinelCommand(shell: string, command: string): string;
+/**
+ * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
+ * branches are testable without stubbing process.platform.
+ *
+ * Unix: an AF_UNIX socket file inside the scratch dir.
+ * Windows: a named pipe (`\\.\pipe\…`). Named pipes are NOT filesystem objects,
+ * so the name is derived from a hash of the (per-user) scratch dir to keep it
+ * stable across invocations and isolated per user — and callers must never probe
+ * it with fs.existsSync (it always reports false). Both forms are accepted by
+ * net.createServer/createConnection.
+ */
+export declare function derivePtyEndpoint(platform: NodeJS.Platform, ptyDir: string): string;
+/** Get the IPC endpoint the PTY server listens on / clients connect to. */
 export declare function getSocketPath(): string;
 /** Get the path to the PTY server PID file. */
 export declare function getPtyPidPath(): string;