@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/mailbox.js

@@ -0,0 +1,194 @@
+/**
+ * Agent mailbox — a file-spool that lets a message reach an already-running
+ * agent mid-flight. One box per logical agent, keyed by a unique-per-launch id
+ * (session UUID / teams agentId / loop runId), so boxes are disjoint and a
+ * message can never reach the wrong agent (see docs / plan velvety-conjuring-popcorn).
+ *
+ * Layout: <root>/<mailboxId>/{inbox,processing,consumed}/<msgId>.json
+ *   inbox/      pending, written by `agents message`
+ *   processing/ claimed by a drain (claim-first = crash-safe)
+ *   consumed/   archived after delivery (and dropped mismatches)
+ *
+ * A box has a SINGLE consumer — the owning agent, whose tool calls (and thus
+ * hook-driven drains) are sequential. Writers may be concurrent; each enqueue
+ * is atomic (temp-write + rename), so a drain never observes a partial file.
+ * Delivery is at-least-once: an interrupted drain leaves the message in
+ * processing/, and the next drain recovers it. Consumers dedup by `msgId`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { getMailboxRootDir } from './state.js';
+/**
+ * A mailboxId must be a single, separator-free path segment. Real ids (session
+ * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
+ * else fails loud instead of silently misrouting — a message whose id contained
+ * a `/` would nest under a different dir than the `to` stamp it is matched
+ * against, and would be dropped with no error. Also blocks `.`/`..` traversal
+ * once `agents message` starts accepting external target ids.
+ */
+export function isValidMailboxId(mailboxId) {
+    return /^[A-Za-z0-9._-]+$/.test(mailboxId) && mailboxId !== '.' && mailboxId !== '..';
+}
+export function assertValidMailboxId(mailboxId) {
+    if (!isValidMailboxId(mailboxId)) {
+        throw new Error(`Invalid mailboxId ${JSON.stringify(mailboxId)}: must be a single path segment ` +
+            `matching [A-Za-z0-9._-] (no separators, not '.'/'..').`);
+    }
+}
+/** Absolute path to a box. `root` override is for tests. */
+export function mailboxDir(mailboxId, root = getMailboxRootDir()) {
+    assertValidMailboxId(mailboxId);
+    return path.join(root, mailboxId);
+}
+function inboxDir(boxDir) { return path.join(boxDir, 'inbox'); }
+function processingDir(boxDir) { return path.join(boxDir, 'processing'); }
+function consumedDir(boxDir) { return path.join(boxDir, 'consumed'); }
+/** Create the three sub-buckets. Idempotent. */
+function ensureDirs(boxDir) {
+    fs.mkdirSync(inboxDir(boxDir), { recursive: true });
+    fs.mkdirSync(processingDir(boxDir), { recursive: true });
+    fs.mkdirSync(consumedDir(boxDir), { recursive: true });
+}
+let seq = 0;
+/**
+ * `<epochMs>-<seq>-<rand>` — sorts by filename in FIFO order. The per-process
+ * monotonic `seq` breaks ties within the same millisecond (so a single writer's
+ * order is preserved); `rand` keeps it unique across processes/hosts.
+ */
+function newMsgId() {
+    const s = String(seq++).padStart(6, '0');
+    return `${Date.now()}-${s}-${randomUUID().slice(0, 8)}`;
+}
+/**
+ * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
+ * is stamped so a drain can refuse a message that lands in the wrong box.
+ */
+export function enqueue(boxDir, msg) {
+    assertValidMailboxId(msg.to);
+    ensureDirs(boxDir);
+    const msgId = newMsgId();
+    const record = {
+        msgId,
+        to: msg.to,
+        from: msg.from,
+        ts: new Date().toISOString(),
+        text: msg.text,
+    };
+    const target = path.join(inboxDir(boxDir), `${msgId}.json`);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf-8');
+    fs.renameSync(tmp, target); // atomic on a single filesystem
+    return msgId;
+}
+/** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
+function readMessage(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const m = parsed;
+    if (typeof m?.msgId !== 'string' || typeof m?.to !== 'string' || typeof m?.text !== 'string') {
+        return null;
+    }
+    return { msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text };
+}
+function jsonFiles(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => n.endsWith('.json')).sort();
+}
+/**
+ * Consume a file already sitting in `processing/`: read, verify it is addressed
+ * to this box, then archive to `consumed/`. Returns the message iff valid AND
+ * addressed here; a mismatched/corrupt file is archived (dropped) so it never
+ * loops. Returns null when the file vanished (a racing drain took it).
+ */
+function consumeClaimed(boxDir, name, expectedTo) {
+    const src = path.join(processingDir(boxDir), name);
+    const dest = path.join(consumedDir(boxDir), name);
+    const msg = readMessage(src);
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch {
+        return null; // already archived/claimed elsewhere
+    }
+    if (!msg || msg.to !== expectedTo)
+        return null; // dropped (corrupt or wrong box)
+    return msg;
+}
+/**
+ * Drain the box: return every pending message addressed to it, in FIFO order,
+ * removing them from the queue. Claim-first (inbox → processing → consumed) so
+ * an interrupted drain is recovered on the next call (at-least-once). Corrupt
+ * files and messages addressed to a different box are dropped, not returned.
+ *
+ * `boxId` defaults to the box's directory name — the id it was created under.
+ */
+export function drain(boxDir, boxId = path.basename(boxDir)) {
+    ensureDirs(boxDir);
+    const out = [];
+    // 1. Recover orphans left in processing/ by a prior interrupted drain.
+    for (const name of jsonFiles(processingDir(boxDir))) {
+        const msg = consumeClaimed(boxDir, name, boxId);
+        if (msg)
+            out.push(msg);
+    }
+    // 2. Claim and consume pending inbox messages.
+    for (const name of jsonFiles(inboxDir(boxDir))) {
+        const from = path.join(inboxDir(boxDir), name);
+        const to = path.join(processingDir(boxDir), name);
+        try {
+            fs.renameSync(from, to); // atomic claim
+        }
+        catch {
+            continue; // vanished — a racing drain took it
+        }
+        const msg = consumeClaimed(boxDir, name, boxId);
+        if (msg)
+            out.push(msg);
+    }
+    return out;
+}
+/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
+export function peek(boxDir, boxId = path.basename(boxDir)) {
+    const out = [];
+    for (const dir of [processingDir(boxDir), inboxDir(boxDir)]) {
+        for (const name of jsonFiles(dir)) {
+            const msg = readMessage(path.join(dir, name));
+            if (msg && msg.to === boxId)
+                out.push(msg);
+        }
+    }
+    return out;
+}
+/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
+export function clear(boxDir) {
+    let n = 0;
+    for (const name of jsonFiles(inboxDir(boxDir))) {
+        try {
+            fs.unlinkSync(path.join(inboxDir(boxDir), name));
+            n++;
+        }
+        catch {
+            // already gone — ignore
+        }
+    }
+    return n;
+}

package/dist/lib/mcp.d.ts

@@ -39,6 +39,11 @@ export interface McpTargetOperationResult {
  * Parse an MCP server config from a YAML file.
  */
 export declare function parseMcpServerConfig(filePath: string): McpYamlConfig | null;
+/**
+ * Validate an MCP server name. Rejects names that could be misinterpreted as
+ * command-line options or that contain characters unsafe for argv/identifier use.
+ */
+export declare function validateMcpServerName(name: string): void;
 /**
  * List all MCP server configs from ~/.agents/mcp/.
  */

package/dist/lib/mcp.js

@@ -34,6 +34,18 @@ export function parseMcpServerConfig(filePath) {
     }
     return validateMcpYamlConfig(parsed);
 }
+/**
+ * Validate an MCP server name. Rejects names that could be misinterpreted as
+ * command-line options or that contain characters unsafe for argv/identifier use.
+ */
+export function validateMcpServerName(name) {
+    if (name.startsWith('-')) {
+        throw new Error(`Invalid MCP server name '${name}': names cannot start with '-'`);
+    }
+    if (/[\s\0-\x1f\x7f]/.test(name)) {
+        throw new Error(`Invalid MCP server name '${name}': names cannot contain whitespace or control characters`);
+    }
+}
 function validateMcpYamlConfig(parsed) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return null;
@@ -41,6 +53,7 @@ function validateMcpYamlConfig(parsed) {
     const config = parsed;
     if (typeof config.name !== 'string' || config.name.length === 0)
         return null;
+    validateMcpServerName(config.name);
     if (config.transport !== 'stdio' && config.transport !== 'http')
         return null;
     const result = {
@@ -205,12 +218,12 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
                 envArgs.push('--env', `${key}=${value}`);
             }
         }
-        // claude mcp add --scope user --transport stdio <name> [--env K=V]... -- <cmd> [args...]
+        // claude mcp add --scope user --transport stdio [--env K=V]... -- <name> <cmd> [args...]
         const args = [
             'mcp', 'add', '--scope', 'user', '--transport', 'stdio',
-            server.name,
             ...envArgs,
             '--',
+            server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
@@ -222,8 +235,8 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
         });
     }
     else {
-        // claude mcp add --scope user --transport http <name> <url>
-        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', server.name, server.config.url], {
+        // claude mcp add --scope user --transport http -- <name> <url>
+        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--', server.name, server.config.url], {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
@@ -237,10 +250,11 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
  */
 function installMcpViaCodex(binaryPath, server, versionHome) {
     if (server.config.transport === 'stdio') {
-        // codex mcp add <name> -- <cmd> [args...]
+        // codex mcp add -- <name> <cmd> [args...]
         const args = [
-            'mcp', 'add', server.name,
+            'mcp', 'add',
             '--',
+            server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
@@ -272,11 +286,12 @@ export async function registerMcpCommandToTargets(targets, name, commandSpec, sc
 }
 function registerMcpCommand(agentId, name, commandSpec, scope, transport, options = {}) {
     try {
+        validateMcpServerName(name);
         const bin = options.binary || AGENTS[agentId].cliCommand;
         const commandArgs = [commandSpec.command, ...commandSpec.args];
         const args = agentId === 'claude'
-            ? ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs]
-            : ['mcp', 'add', name, '--', ...commandArgs];
+            ? ['mcp', 'add', '--transport', transport, '--scope', scope, '--', name, ...commandArgs]
+            : ['mcp', 'add', '--', name, ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
         execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env, shell: needsWindowsShell(bin) });
         return { success: true };
@@ -508,6 +523,7 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
  * Write an MCP server config to ~/.agents/mcp/.
  */
 export function writeMcpServerConfig(config) {
+    validateMcpServerName(config.name);
     const mcpDir = getUserMcpDir();
     fs.mkdirSync(mcpDir, { recursive: true });
     const fileName = `${config.name.toLowerCase().replace(/[^a-z0-9]/g, '-')}.yaml`;

package/dist/lib/migrate.d.ts

@@ -25,6 +25,25 @@
  * LEGACY_SYSTEM_DIR" without duplicating data.
  */
 export declare function foldLegacySystemRepo(): void;
+/**
+ * Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml.
+ *
+ * The post-fold system dir (~/.agents/.system) is a pull-only mirror of the
+ * npm-shipped defaults. Its agents.yaml is a TRACKED file that readMeta() reads
+ * in place as the defaults base (see SYSTEM_META_FILE in state.ts). Deleting or
+ * moving a tracked file out of the mirror dirties its working tree, which
+ * permanently wedges `agents setup`, `agents sync`, and background auto-pull
+ * ("Working tree has uncommitted changes.") because the mirror sync refuses a
+ * dirty tree. So when agents.yaml is tracked there, treat the mirror as strictly
+ * read-only and leave the file alone.
+ *
+ * Only an UNTRACKED agents.yaml is residue from the pre-split single-repo layout
+ * (or a legacy ~/.agents-system fold) and is safe to move/drop.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests can
+ * drive a fixture tree without touching the user's ~/.agents.
+ */
+export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
 /**
  * Repair self-referential agent binary symlinks.
  *

package/dist/lib/migrate.js

@@ -8,6 +8,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { execSync } from 'child_process';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
 const HOME = process.env.HOME ?? os.homedir();
@@ -79,21 +82,46 @@ export function foldLegacySystemRepo() {
     }
     catch { /* best-effort */ }
 }
+/** True when `relPath` is a file tracked by a git repo rooted at `repoDir`. */
+function isTrackedInGitRepo(repoDir, relPath) {
+    try {
+        execSync(`git ls-files --error-unmatch -- ${relPath}`, { cwd: repoDir, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        // Not a git repo, or the file is untracked — either way, not tracked.
+        return false;
+    }
+}
 /**
- * Move ~/.agents-system/agents.yaml -> ~/.agents/agents.yaml.
- * No-op if user file already exists or system file absent.
- * (This is also handled inline in state.ts readMeta, but is exposed here
- *  for explicit migration calls from postinstall / CLI entry points.)
+ * Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml.
+ *
+ * The post-fold system dir (~/.agents/.system) is a pull-only mirror of the
+ * npm-shipped defaults. Its agents.yaml is a TRACKED file that readMeta() reads
+ * in place as the defaults base (see SYSTEM_META_FILE in state.ts). Deleting or
+ * moving a tracked file out of the mirror dirties its working tree, which
+ * permanently wedges `agents setup`, `agents sync`, and background auto-pull
+ * ("Working tree has uncommitted changes.") because the mirror sync refuses a
+ * dirty tree. So when agents.yaml is tracked there, treat the mirror as strictly
+ * read-only and leave the file alone.
+ *
+ * Only an UNTRACKED agents.yaml is residue from the pre-split single-repo layout
+ * (or a legacy ~/.agents-system fold) and is safe to move/drop.
+ *
+ * Params default to the real on-disk locations; they are injectable so tests can
+ * drive a fixture tree without touching the user's ~/.agents.
  */
-function migrateAgentsYaml() {
-    const src = path.join(SYSTEM_DIR, 'agents.yaml');
-    const dest = path.join(USER_DIR, 'agents.yaml');
+export function migrateAgentsYaml(systemDir = SYSTEM_DIR, userDir = USER_DIR) {
+    const src = path.join(systemDir, 'agents.yaml');
+    const dest = path.join(userDir, 'agents.yaml');
     if (!fs.existsSync(src))
         return;
+    // Tracked in the system mirror → npm-shipped defaults; never mutate. readMeta()
+    // already surfaces it in place, so no user-dir copy is needed either.
+    if (isTrackedInGitRepo(systemDir, 'agents.yaml'))
+        return;
     if (fs.existsSync(dest)) {
-        // User copy is authoritative — drop the stale system leftover. The system
-        // repo (npm-shipped) does not track agents.yaml; any copy here is residue
-        // from the pre-split layout.
+        // User copy is authoritative — drop the untracked stale system leftover.
         try {
             fs.unlinkSync(src);
         }
@@ -101,7 +129,7 @@ function migrateAgentsYaml() {
         return;
     }
     try {
-        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.mkdirSync(userDir, { recursive: true, mode: 0o700 });
         fs.renameSync(src, dest);
         console.error('Migrated agents.yaml to ~/.agents/');
     }
@@ -656,22 +684,31 @@ function migratePermissionSetsToPresets() {
  * switching is owned by `agents use`, not the migrator.
  */
 function repairAgentConfigSymlinks() {
-    let yaml;
-    try {
-        yaml = fs.readFileSync(path.join(USER_DIR, 'agents.yaml'), 'utf-8');
-    }
-    catch {
-        return;
-    }
-    const agentsBlock = yaml.match(/^agents:\s*\n((?:  [^\n]*\n)+)/m);
-    if (!agentsBlock)
-        return;
+    // Version pins live in the per-device file post-split (~/.agents/devices/<machine>/
+    // agents.yaml); central agents.yaml may still carry them mid-transition. Read
+    // device first (authoritative), then central, first-seen-agent wins.
     const defaults = [];
-    for (const line of agentsBlock[1].split('\n')) {
-        const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
-        if (m)
-            defaults.push({ agent: m[1], version: m[2] });
-    }
+    const collectPins = (file) => {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        const block = text.match(/^agents:\s*\n((?:  [^\n]*\n)+)/m);
+        if (!block)
+            return;
+        for (const line of block[1].split('\n')) {
+            const m = line.match(/^\s+([a-z][a-z0-9_-]*):\s*([^\s#]+)/);
+            if (m && !defaults.some((d) => d.agent === m[1]))
+                defaults.push({ agent: m[1], version: m[2] });
+        }
+    };
+    collectPins(path.join(USER_DIR, 'devices', machineId(), 'agents.yaml'));
+    collectPins(path.join(USER_DIR, 'agents.yaml'));
+    if (defaults.length === 0)
+        return;
     let repaired = 0;
     for (const { agent, version } of defaults) {
         const configDirName = agent in AGENTS ? agentConfigDirName(agent) : `.${agent}`;
@@ -1625,6 +1662,73 @@ function migrateVersionResourcesToPatterns() {
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
 }
+/**
+ * Split the machine-local fields out of the committed central agents.yaml so it
+ * becomes portable and syncs cleanly (no more skip-worktree band-aid):
+ *   agents:   -> ~/.agents/devices/<machineId>/agents.yaml  (committed, per-device)
+ *   versions: -> ~/.agents/.history/version-resources.json   (gitignored, machine-local)
+ * Then clear any externally-set skip-worktree bit. Idempotent: no-op once central
+ * carries neither field. Operates on raw YAML (never through state.ts).
+ */
+function migrateSplitDeviceLocalMeta() {
+    const metaFile = path.join(USER_DIR, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let meta;
+    try {
+        meta = yaml.parse(fs.readFileSync(metaFile, 'utf-8')) || {};
+    }
+    catch {
+        return;
+    }
+    const agents = meta.agents;
+    const versions = meta.versions;
+    const hasLocal = (!!agents && Object.keys(agents).length > 0) || (!!versions && Object.keys(versions).length > 0);
+    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+    // Only rewrite central when it actually carries machine-local fields — a
+    // machine whose agents.yaml is already portable-only is left untouched.
+    if (hasLocal) {
+        // agents: -> per-device file (merge, existing device entries win).
+        if (agents && Object.keys(agents).length > 0) {
+            const devicePath = path.join(USER_DIR, 'devices', machineId(), 'agents.yaml');
+            let existing = {};
+            try {
+                const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+                if (dm?.agents)
+                    existing = dm.agents;
+            }
+            catch { /* absent */ }
+            fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+            atomicWriteFileSync(devicePath, HEADER + yaml.stringify({ agents: { ...agents, ...existing } }));
+        }
+        // versions: -> machine-local history JSON (merge, existing wins).
+        if (versions && Object.keys(versions).length > 0) {
+            const vrPath = path.join(USER_DIR, '.history', 'version-resources.json');
+            let existing = {};
+            try {
+                existing = JSON.parse(fs.readFileSync(vrPath, 'utf-8')) || {};
+            }
+            catch { /* absent */ }
+            fs.mkdirSync(path.dirname(vrPath), { recursive: true });
+            atomicWriteFileSync(vrPath, JSON.stringify({ ...versions, ...existing }, null, 2) + '\n');
+        }
+        // Strip machine-local fields from central and rewrite (portable only) — after
+        // the device/history writes above, so a crash never loses data.
+        delete meta.agents;
+        delete meta.versions;
+        atomicWriteFileSync(metaFile, HEADER + yaml.stringify(meta));
+    }
+    // Always clear any skip-worktree bit (idempotent, best-effort) so agents.yaml
+    // syncs cleanly on every machine — even one that had nothing to split. Runs
+    // after any rewrite so the tracked content already matches the split shape.
+    try {
+        execSync('git update-index --no-skip-worktree agents.yaml', { cwd: USER_DIR, stdio: 'ignore' });
+    }
+    catch { /* not a git repo / bit not set */ }
+    if (hasLocal) {
+        console.error('Split agents.yaml: agents: -> devices/, versions: -> .history/version-resources.json');
+    }
+}
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in
@@ -1805,6 +1909,10 @@ export async function runMigration() {
     foldUserHooksYamlIntoAgentsYaml();
     foldBrowserProfilesIntoAgentsYaml();
     migrateVersionResourcesToPatterns();
+    // Split machine-local fields (agents:/versions:) out of the committed central
+    // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
+    // in pattern form when it moves to the history file.
+    migrateSplitDeviceLocalMeta();
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateRuntimeToCache();

package/dist/lib/overdue.js

@@ -44,6 +44,9 @@ export function detectOverdueJobs(now = new Date()) {
     for (const job of listJobs()) {
         if (!job.enabled || job.runOnce)
             continue;
+        // Trigger-only jobs (no cron schedule) never have an expected fire time.
+        if (!job.schedule)
+            continue;
         let expected = null;
         try {
             const cronOptions = { paused: true };

package/dist/lib/permissions.d.ts

@@ -2,6 +2,10 @@ import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, Op
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 export type ParsedRules = PermissionSet;
+export declare const COMPUTER_PERMISSION_RULE_PREFIX = "Computer";
+export declare const COMPUTER_APP_GATED_VERBS: readonly ["screenshot", "describe", "get-text", "launch", "raise", "click", "right-click", "type", "type-text", "key", "drag", "scroll", "ax-action", "focus", "wait"];
+export declare const COMPUTER_INPUT_GATED_VERBS: readonly ["raise", "click", "right-click", "type", "type-text", "key", "drag", "scroll", "ax-action", "focus"];
+export declare function formatComputerPermissionGrantHint(bundleId?: string): string;
 export declare function containsBroadGrants(rules: ParsedRules): {
     broad: string[];
     reason: string;

package/dist/lib/permissions.js

@@ -25,6 +25,41 @@ const HOME = os.homedir();
 // the writer in `applyPermissionsToVersion` handles the format dispatch.)
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
+export const COMPUTER_PERMISSION_RULE_PREFIX = 'Computer';
+export const COMPUTER_APP_GATED_VERBS = [
+    'screenshot',
+    'describe',
+    'get-text',
+    'launch',
+    'raise',
+    'click',
+    'right-click',
+    'type',
+    'type-text',
+    'key',
+    'drag',
+    'scroll',
+    'ax-action',
+    'focus',
+    'wait',
+];
+export const COMPUTER_INPUT_GATED_VERBS = [
+    'raise',
+    'click',
+    'right-click',
+    'type',
+    'type-text',
+    'key',
+    'drag',
+    'scroll',
+    'ax-action',
+    'focus',
+];
+export function formatComputerPermissionGrantHint(bundleId) {
+    const target = bundleId && bundleId.length > 0 ? bundleId : '<bundle-id>';
+    return `add Computer(${target}) to a permissions group, then \`agents computer reload\`\n` +
+        `app-targeted computer verbs are gated by Computer(<bundle-id>): ${COMPUTER_APP_GATED_VERBS.join(', ')}`;
+}
 export function containsBroadGrants(rules) {
     const broad = [];
     const reasons = new Set();

package/dist/lib/picker.d.ts

@@ -8,6 +8,8 @@
 /** Configuration for the interactive picker prompt. */
 export interface PickerConfig<T> {
     message: string;
+    /** Optional dim hint line rendered directly under the header (above the rows). */
+    subtitle?: string;
     items: T[];
     filter: (query: string) => T[];
     labelFor: (item: T, query: string) => string;
@@ -22,7 +24,31 @@ export interface PickerConfig<T> {
 export interface PickedItem<T> {
     item: T;
 }
+/** Configuration for the multi-select picker prompt. */
+export interface MultiPickerConfig<T> {
+    message: string;
+    items: T[];
+    filter: (query: string) => T[];
+    labelFor: (item: T, query: string) => string;
+    /** Stable identity for an item — drives the selected set. */
+    keyFor: (item: T) => string;
+    buildPreview?: (item: T) => string;
+    pageSize?: number;
+    initialSearch?: string;
+    emptyMessage?: string;
+    enterHint?: string;
+}
 /** Clip a picker preview so the full prompt can fit in the terminal viewport. */
 export declare function limitPreviewHeight(preview: string, maxRows: number, width: number): string;
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;
+/**
+ * Multi-select variant of {@link itemPicker}. Same searchable, paginated list
+ * and preview pane, but `space` toggles a checkbox on the active row instead of
+ * the preview (preview moves to `tab`), and `enter` confirms every checked row.
+ *
+ * Returns the selected items (in the config's `items` order) or `null` on
+ * cancel. Pressing `enter` with nothing checked confirms just the highlighted
+ * row, so a quick single-pick still works.
+ */
+export declare function multiItemPicker<T>(config: MultiPickerConfig<T>): Promise<T[] | null>;