@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 1.20.4
+
+**Plugin marketplace sync (skip outside-pointing symlinks)**
+
+- `copyPluginToMarketplace` used `fs.cpSync(plugin.root, dest, { recursive: true, dereference: false })`, which faithfully preserved every symlink — including the ones plugin authors put at the top of their plugin source for prompt-side references (the rush plugin's `app -> ../../../rush/app`, `web -> rush/web`, `widgets -> rush/widgets`). Those targets resolve to the rush monorepo (~8.7 GB of `app/` including node_modules + .next builds, 782 MB of `web/`, plus 463 MB brand-assets). Every claude version got a full set of those symlinks in `~/.claude/plugins/marketplaces/agents-cli/plugins/rush/`. When the consumer (Claude Code, OpenClaw) discovers plugins, it walks the marketplace tree and follows those symlinks — producing multi-minute startup hangs.
+- The copy now walks the source tree and drops symlinks whose `realpath` escapes the plugin root, leaving internal symlinks intact (cpSync rewrites internal targets to absolute paths into the source tree, which the consumer still resolves correctly). One informational line per plugin lists the skipped names so plugin authors notice.
+- Existing per-version marketplace directories still hold the bloat from prior syncs; clean up with `rm` against `~/.claude/plugins/marketplaces/agents-cli/plugins/*/{app,web,widgets,*-symlinks-that-escaped}` then re-run `agents pull` or any plugin sync to re-copy with the filter.
+
+## 1.20.3
+
+**`agents run` startup latency (stale-while-revalidate the usage probe + memoize agents.yaml)**
+
+- The default `agents run` strategy is `available`, which calls `getUsageInfoForIdentity` to skip rate-limited accounts. With a 2-minute cache, every cold invocation past that window made a blocking `fetch` to `api.anthropic.com/api/oauth/usage` (5 s timeout, plus an optional 15 s OAuth token refresh) before `spawn(claude)` — so `agents run claude` regularly stalled 5–8 s with nothing on screen after the rotation banner.
+- The cache is now stale-while-revalidate: fresh (<2 min) returns instantly with no network, stale-but-recent (<24 h) returns the cached snapshot instantly and refreshes in the background, and only a fully cold / >24 h cache blocks on the live fetch. The background refresh defers its first await past `setImmediate` so the synchronous Keychain CLI call (`security find-generic-password`, invoked by `loadClaudeOauth`) cannot block the foreground caller — that's how an SWR returns "instantly" even while the refresh is technically still on its first sync step.
+- `readMeta()` had a `metaCache` module global plus `writeMetaUnlocked` cache-invalidation logic wired in years ago — but no read path ever consulted the cache. So every call did 2x `fs.readFileSync` + 2x `yaml.parse` on system + user `agents.yaml`, and hot callers (`getConfiguredRunStrategy`, `getGlobalDefault`, `getVersionResources`, `ensureVersionResourcePatterns`) fire it multiple times per `agents run`. The read path now consults the cache, keyed on the combined mtime of both source files — out-of-band edits still invalidate on the next stat, and in-process writers already clear it.
+
+## 1.20.2
+
+**Grok and Antigravity Support & Documentation**
+
+- **Grok CLI Integration**: Added support for installing Grok via `agents add grok@<version>`, which invokes the official xAI installer with the specified version. Grok MCP server configuration paths (via `config.toml`) and memory file mapping are now correctly documented.
+- **Antigravity (AGY) CLI Integration**: Added support for the Google Antigravity CLI. Since the AGY installer doesn't support version-pinned installs currently, `agents add agy` uses the `latest` version. Documented the canonical config path `~/.gemini/antigravity-cli/` and its `mcp_config.json`.
+- **Documentation**: Updated `02-resource-sync.md` to reflect accurate MCP mappings and memory file symlinks for both Grok and Antigravity.
+- **Profiles**: Hardened presets with verified 2026 model IDs and added generic proxy configuration. Show custom profiles in agents view.
+
+## 1.20.1
+
+**Agents selector (auto-install missing versions + unified `@all` everywhere)**
+
+- `--agents claude@2.1.999` used to hard-error when 2.1.999 wasn't installed. Now the CLI prompts to install it inline and continues (auto-install with `--yes`). No more breaking flow to run `agents add` first.
+- `--agents claude@all` and the bare `all` literal now work across every callsite that takes `--agents` — previously `agents install gh:...`, `mcp register`, `mcp remove`, and inline `mcp add` had diverged from the canonical syntax and threw "Version all is not installed" despite the help text advertising it. Selector is unified end-to-end.
+
+**Prompt (fail loud on non-TTY + `@all` syntax in picker)**
+
+- Scripts that called `agents <resource> add` with no `--agents` and no `--yes` used to silently auto-pick a default version. That hid scripted misuse behind unpredictable picks. The non-TTY path now throws with a clear pointer at the new syntax: `--agents claude@all` (every installed version of Claude), `--agents all` (every capable agent at all versions), or `--agents claude@2.1.141` (one specific version).
+- `--agents` parsing in `<resource> add` understands `@all` and the bare `all` literal; `promptAgentVersionSelection`'s picker surfaces version counts when there's more than one installed, mirroring what `@all` would target.
+
+**Resources / install (`gh:` form sniffs every type, `mcp add gh:`, `--names` + `@all` unified across resource add)**
+
+- `agents install gh:<owner>/<repo>` now sniffs every resource type in the source repo (commands, skills, hooks, MCP, permissions, profiles, subagents, workflows) instead of requiring one `--types` per kind. Pass `--types skills,workflows` to narrow.
+- New `agents mcp add gh:<owner>/<repo>` form — install MCP servers directly from a git source, parallel to the other `<resource> add gh:` paths.
+- `<resource> add` accepts `--names` and `@all` uniformly across commands, skills, hooks, MCP, permissions, profiles, rules, subagents, workflows — same flags, same semantics, regardless of resource kind.
+
+**Profiles (interactive `create` wizard, gateway + self-hosted presets)**
+
+- New `agents profiles create` command — interactive wizard to assemble a profile from gateway or self-hosted presets (OpenRouter, OpenAI-compatible) without hand-writing YAML.
+- `--smoke-test` exercises the resolved env block against the configured endpoint before writing the profile.
+
+**Feedback (in-CLI bug / idea / question routing)**
+
+- New `agents feedback` command — collects a short description + optional category (bug, idea, question) and routes to the project's tracker without leaving the terminal.
+
+**Routines (real exit codes for detached scheduled runs)**
+
+- `monitorRunningJobs` used to hardcode `status: 'failed'` whenever it detected that a detached child had exited — `executeJobDetached` fires-and-forgets, so the real exit code was unreachable. Every scheduler-driven routine ended up labeled `failed/exitCode: null`, even when the agent completed cleanly.
+- Fix: when finalizing a vanished child, scan the tail of its stream-json `stdout.log` for Claude's `type: result` terminator (which carries `is_error`). If found, set `status` and `exitCode` from it. Only fall back to `failed` when no result marker exists (process was killed mid-run).
+- Routines list cell rendering hardened around 7-day retention boundaries.
+- Codex/Gemini run finalization continues to fall back to `failed` until their stream tail parsers are added.
+
+**Security**
+
+- `security(cli)`: eliminated `shell: true` from manifest-driven installs — closes a command-injection vector in `install`/`add` paths that took git URLs or shell-interpolated metadata.
+- `security(logs)`: prompts and tokens are redacted before `events.jsonl` is written, and event retention is shortened from 30d to 7d. Reduces blast radius on accidental disclosure.
+- `security(exec)`: strip loader env vars (`DYLD_*`, `LD_*`, `NODE_OPTIONS`) from environments propagated to child agents — avoids passing host-process loader state into spawned binaries.
+- `security(browser)`: CDP origin allowlist replaces the previous wildcard — only `localhost` and explicitly configured browser hosts can speak CDP into a session.
+- `security(ci)`: keychain helper SHA is verified at publish time, so a tampered helper binary cannot ride a release.
+
+**Copilot (fix user-scoped MCP path)**
+
+- Copilot's user-scoped MCP path now correctly resolves to `mcp-config.json` (the path the IDE actually reads) instead of the legacy filename. Fixes user-level MCP registrations not appearing in Copilot sessions.
+
+**Docs**
+
+- Full docs site IA shipped: browser, cloud, computer, hooks, plugins, profiles, pty, secrets, subagents, teams, workflows.
+- Brand identity block: `agents-cli` is Phoenix Labs OSS, not part of the Rush brand — guards downstream agents against pulling Rush styling into this project.
+
+**Build / install**
+
+- Staged dev install tarball strips `prepack` and `prepare` hooks so side-by-side dev installs don't accidentally re-run the full publish pipeline locally.
+- `test(jobs)`: un-break 3 stale assertions on main.
+
 ## 1.20.0
 
 **Routines (overdue detection + catchup)**

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/phnx-labs/agents-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagents--cli-blue?style=flat-square" alt="github" /></a>
 </p>
 
-**The missing toolchain for CLI coding agents.** Pin versions to escape regressions. Build hooks to control agent behavior, or skills to improve them. Then share your agent environment with your team, or clone it to any machine with one command.
+**The missing toolchain for CLI coding agents.** Run any agent on your existing subscription. Spawn parallel teams in isolated terminals. Schedule routines, drive browsers and Electron apps, and store secrets behind Touch ID — all from one CLI.
 
 <p align="center">
   <a href="https://github.com/anthropics/claude-code" title="Claude Code"><img src="assets/harnesses/anthropic.svg" height="32" alt="Claude Code" /></a>
@@ -598,11 +598,11 @@ Every agent run, version install, browser launch, and secrets access is logged t
 }
 ```
 
-**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors, and secret bundle/key names with caller context. **What's NOT logged:** Full prompts, outputs, file contents, or secret values.
+**What's logged:** Operation type, agent, version, timing, prompt length + SHA-256 hash (raw text never stored), exit codes, errors, and secret bundle/key names with caller context. Argv entries that look like tokens or secret paths are redacted. **What's NOT logged:** Raw prompts, outputs, file contents, or secret values.
 
 **Permissions:** Logs directory is `0700` (owner-only), files are `0600`. Only you can read them.
 
-**Retention:** 30 days by default, then auto-pruned.
+**Retention:** 7 days by default, then auto-pruned.
 
 **Opt out:** Set `AGENTS_DISABLE_EVENT_LOG=1` in your shell to disable completely.
 
@@ -693,7 +693,7 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 **No CLI telemetry or phone-home.** API keys come from your shell environment or each agent CLI's existing auth, and remote calls only happen when you invoke a feature that requires them, such as cloud dispatch.
 
-For full transparency: `agents-cli` keeps a local event log at `~/.agents/.cache/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 30 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
+For full transparency: `agents-cli` keeps a local event log at `~/.agents/.cache/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 7 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
 
 ### Which platforms?
 

package/dist/commands/cli.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
-import { listCliManifests, listCliStatus, resolveCliManifest, installCli, describeMethod, selectInstallMethod, isCliInstalled, } from '../lib/cli-resources.js';
+import { listCliManifests, listCliStatus, resolveCliManifest, installCli, describeMethod, describeCheck, selectInstallMethod, isCliInstalled, } from '../lib/cli-resources.js';
 import { getUserAgentsDir } from '../lib/state.js';
 import { isPromptCancelled } from './utils.js';
 function userCliDir() {
@@ -163,7 +163,7 @@ When to use:
                 }
             }
             else {
-                console.log(chalk.yellow(`  install command ran but \`${m.check}\` still fails — check the output above`));
+                console.log(chalk.yellow(`  install command ran but \`${describeCheck(m.check)}\` still fails — check the output above`));
                 failures++;
             }
         }
@@ -188,7 +188,7 @@ When to use:
         console.log('  ' + chalk.gray(`file: ${manifest.path}`));
         console.log('');
         console.log(chalk.bold('  check'));
-        console.log('    ' + manifest.check);
+        console.log('    ' + describeCheck(manifest.check));
         console.log('');
         console.log(chalk.bold('  install methods'));
         for (const method of manifest.install) {

package/dist/commands/cloud.js

@@ -68,7 +68,7 @@ Examples:
   agents cloud run "add pytest fixtures for the new billing module" --provider codex --env env_a1b2c3 --agent codex --timeout 30m
 
   # Factory pod targeting a specific computer (Droid)
-  agents cloud run "QA the new onboarding flow end-to-end" --provider factory --computer mac-mini-1 --agent droid
+  agents cloud run "QA the new onboarding flow end-to-end" --provider factory --computer linux-vm-1 --agent droid
 
   # See every cloud task you've dispatched (most recent first)
   agents cloud list

package/dist/commands/commands.js

@@ -9,9 +9,9 @@ import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommandCentrally, listCentralCommands, listInstalledCommandsWithScope, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
 /** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
@@ -214,13 +214,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, ALL_AGENT_IDS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, ALL_AGENT_IDS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(ALL_AGENT_IDS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
@@ -334,11 +338,24 @@ Examples:
                 console.log(chalk.yellow(`  Command '${cmdName}' not found in any version.`));
                 continue;
             }
-            // Filter by --agents if specified
+            // Filter by --agents if specified. Routes through resolveInstalledAgentTargets
+            // so the same selector syntax used everywhere else (agent, agent@default,
+            // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = cmdInfo.targets;
             if (options?.agents) {
-                const requestedAgents = new Set(options.agents.split(','));
-                availableTargets = availableTargets.filter((t) => requestedAgents.has(t.agent));
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, ALL_AGENT_IDS);
+                const requested = new Set();
+                for (const aid of requestedTargets.directAgents) {
+                    for (const ver of listInstalledVersions(aid)) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                for (const [aid, versions] of requestedTargets.versionSelections) {
+                    for (const ver of versions) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                availableTargets = availableTargets.filter((t) => requested.has(`${t.agent}@${t.version}`));
             }
             if (availableTargets.length === 0) {
                 console.log(chalk.yellow(`  Command '${cmdName}' not found in specified agents.`));

package/dist/commands/exec.js

@@ -6,20 +6,13 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import chalk from 'chalk';
-import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
-import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
 import { setHelpSections } from '../lib/help.js';
-import { readAndResolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
-import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
-import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
-import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.js';
-import { parseWorkflowFrontmatter, resolveWorkflowRef } from '../lib/workflows.js';
+import { AGENTS } from '../lib/agents.js';
 import * as fs from 'fs';
 import * as path from 'path';
-const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
-    return VALID_AGENTS.includes(agent);
+    return agent in AGENTS;
 }
 /** Build a one-line banner describing which version the strategy picked. */
 function formatRotationBanner(result, verb = 'balanced') {
@@ -33,7 +26,7 @@ export function registerRunCommand(program) {
     const runCmd = program
         .command('run <agent> [prompt]')
         .description('Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively.')
-        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), full (writes + all permissions)', 'plan')
+        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), auto (smart classifier auto-approves safe ops, prompts for risky), skip (bypass all permission prompts). \'full\' accepted as alias for skip.', 'plan')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto (claude and codex only)', 'auto')
         .option('--model <model>', 'Override the model directly (e.g., claude-opus-4-6)')
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
@@ -73,8 +66,12 @@ export function registerRunCommand(program) {
       agents run claude "deploy the worker" --secrets prod --mode edit
     `,
         notes: `
-      Modes:
-        plan  read-only       edit  can write files       full  writes + all permissions
+      Modes (not every agent supports every mode — check agents.yaml capabilities):
+        plan  read-only investigation; no writes, no shell side-effects
+        edit  may edit files; prompts for shell / risky operations
+        auto  smart classifier auto-approves safe ops, prompts for risky (claude, copilot)
+        skip  bypass every permission prompt (dangerously-skip-permissions)
+        Legacy 'full' is silently rewritten to 'skip'.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
         pinned     use the workspace/global pinned version (default)
@@ -88,6 +85,17 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+            import('../lib/exec.js'),
+            import('../lib/agents.js'),
+            import('../lib/profiles.js'),
+            import('../lib/secrets/bundles.js'),
+            import('../lib/rotate.js'),
+            import('../lib/versions.js'),
+            import('../lib/plugins.js'),
+            import('../lib/workflows.js'),
+        ]);
+        const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
         const [rawAgent, rawVersion] = agentSpec.split('@');
         let agent;
@@ -195,7 +203,7 @@ export function registerRunCommand(program) {
         }
         else {
             console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-            console.error(chalk.gray(`Available agents: ${VALID_AGENTS.join(', ')}`));
+            console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
             console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
             process.exit(1);
         }
@@ -244,9 +252,21 @@ export function registerRunCommand(program) {
                 }
             }
         }
+        // Accept the four canonical modes plus 'full' as a permanent silent
+        // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         const mode = options.mode;
-        if (!['plan', 'edit', 'full'].includes(mode)) {
-            console.error(chalk.red(`Invalid mode: ${mode}. Use 'plan', 'edit', or 'full'`));
+        if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
+            console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
+            process.exit(1);
+        }
+        // Surface capability errors as a clean CLI message instead of a stack
+        // trace from buildExecCommand. resolveMode degrades 'auto' silently and
+        // throws on unsupported 'plan'/'skip' — we catch and pretty-print.
+        try {
+            resolveMode(agent, normalizeMode(mode));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
             process.exit(1);
         }
         const effort = options.effort;
@@ -328,7 +348,7 @@ export function registerRunCommand(program) {
                 const [fbAgent, fbVersion] = entry.split('@');
                 if (!isValidAgent(fbAgent)) {
                     console.error(chalk.red(`Unknown fallback agent: ${fbAgent}`));
-                    console.error(chalk.gray(`Available: ${VALID_AGENTS.join(', ')}`));
+                    console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
                     process.exit(1);
                 }
                 if (fbAgent === agent) {

package/dist/commands/feedback.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
+ * pre-filled with version + OS + agent inventory; falls back to printing the
+ * URL when no browser is available.
+ */
+import type { Command } from 'commander';
+export declare function registerFeedbackCommand(program: Command): void;

package/dist/commands/feedback.js

@@ -0,0 +1,89 @@
+/**
+ * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
+ * pre-filled with version + OS + agent inventory; falls back to printing the
+ * URL when no browser is available.
+ */
+import { spawnSync } from 'node:child_process';
+import { arch, platform, release } from 'node:os';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+const REPO = 'phnx-labs/agents-cli';
+const DISCUSSION_BASE = `https://github.com/${REPO}/discussions/new`;
+const ISSUE_BASE = `https://github.com/${REPO}/issues/new`;
+function readCliVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../../package.json');
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function openInBrowser(url) {
+    const openers = process.platform === 'darwin'
+        ? [['open', [url]]]
+        : process.platform === 'win32'
+            ? [['cmd', ['/c', 'start', '""', url]]]
+            : [
+                ['xdg-open', [url]],
+                ['gnome-open', [url]]
+            ];
+    for (const [cmd, args] of openers) {
+        const r = spawnSync(cmd, args, { stdio: 'ignore' });
+        if (r.status === 0)
+            return true;
+    }
+    return false;
+}
+function buildPrefill(kind, summary) {
+    const version = readCliVersion();
+    const os = `${platform()} ${release()} (${arch()})`;
+    const node = process.version;
+    const body = [
+        summary.trim() ? `${summary.trim()}\n` : '<!-- describe what you ran into / what you want -->\n',
+        '---',
+        '',
+        '**Environment**',
+        '',
+        `- agents-cli: \`${version}\``,
+        `- OS: \`${os}\``,
+        `- Node: \`${node}\``,
+        '',
+        '<!-- For bugs: include the exact command you ran and the full output. -->',
+        '<!-- For ideas: include a concrete use case. -->'
+    ].join('\n');
+    if (kind === 'bug') {
+        const url = `${ISSUE_BASE}?template=bug_report.yml&title=${encodeURIComponent(summary || 'Bug: ')}`;
+        return { url, body };
+    }
+    const category = kind === 'idea' ? 'ideas' : 'q-a';
+    const url = `${DISCUSSION_BASE}?category=${category}&title=${encodeURIComponent(summary || '')}&body=${encodeURIComponent(body)}`;
+    return { url, body };
+}
+export function registerFeedbackCommand(program) {
+    program
+        .command('feedback [summary...]')
+        .description('Open a pre-filled feedback Discussion or bug report')
+        .option('-b, --bug', 'File as a bug report (opens issue tracker)')
+        .option('-i, --idea', 'File as a feature idea (Discussions → Ideas)')
+        .option('-q, --question', 'Ask a question (Discussions → Q&A)')
+        .option('--print', 'Print the URL instead of opening it')
+        .action((summary, opts) => {
+        const kind = opts.bug ? 'bug' : opts.idea ? 'idea' : 'question';
+        const summaryText = (summary ?? []).join(' ').trim();
+        const { url } = buildPrefill(kind, summaryText);
+        if (opts.print) {
+            console.log(url);
+            return;
+        }
+        const opened = openInBrowser(url);
+        if (opened) {
+            console.log(chalk.dim(`Opened ${kind} form in your browser:\n  ${url}`));
+        }
+        else {
+            console.log(chalk.yellow('Could not auto-open a browser. Paste this URL:'));
+            console.log(`  ${url}`);
+        }
+    });
+}

package/dist/commands/helper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents helper` -- install, inspect, and reinstall the signed macOS
+ * Keychain helper at the stable user path.
+ *
+ * The signed `Agents CLI.app` ships inside the npm package, but its keychain
+ * ACLs need a stable signature-pinned location to survive `npm i -g` and
+ * version bumps. This command copies it to
+ * `~/Library/Application Support/agents-cli/` once and lets users force a
+ * reinstall when the trusted-app ACL needs to be re-established.
+ */
+import type { Command } from 'commander';
+export declare function registerHelperCommand(program: Command): void;

package/dist/commands/helper.js

@@ -0,0 +1,87 @@
+/**
+ * `agents helper` -- install, inspect, and reinstall the signed macOS
+ * Keychain helper at the stable user path.
+ *
+ * The signed `Agents CLI.app` ships inside the npm package, but its keychain
+ * ACLs need a stable signature-pinned location to survive `npm i -g` and
+ * version bumps. This command copies it to
+ * `~/Library/Application Support/agents-cli/` once and lets users force a
+ * reinstall when the trusted-app ACL needs to be re-established.
+ */
+import chalk from 'chalk';
+import { ensureKeychainHelperInstalled, getKeychainHelperPath, getKeychainHelperStatus, } from '../lib/secrets/install-helper.js';
+function requireDarwin() {
+    if (process.platform !== 'darwin') {
+        console.error(chalk.red('agents helper: macOS only.'));
+        process.exit(1);
+    }
+}
+export function registerHelperCommand(program) {
+    const cmd = program
+        .command('helper')
+        .description('Manage the signed macOS Keychain helper (.app) install');
+    cmd
+        .command('install')
+        .description('Copy the bundled .app to ~/Library/Application Support/agents-cli/')
+        .action(() => {
+        requireDarwin();
+        try {
+            ensureKeychainHelperInstalled({ forceReinstall: true });
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+        const s = getKeychainHelperStatus();
+        console.log(chalk.green('Installed:'), s.destination);
+        console.log(chalk.dim('codesign:'), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+        console.log(chalk.dim('spctl:   '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+    });
+    cmd
+        .command('update')
+        .description('Reinstall the .app, overwriting any existing copy (alias of install)')
+        .action(() => {
+        requireDarwin();
+        try {
+            ensureKeychainHelperInstalled({ forceReinstall: true });
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+        const s = getKeychainHelperStatus();
+        console.log(chalk.green('Updated: '), s.destination);
+        console.log(chalk.dim('codesign:'), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+        console.log(chalk.dim('spctl:   '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+    });
+    cmd
+        .command('status')
+        .description('Show source, destination, codesign and notarization status')
+        .action(() => {
+        requireDarwin();
+        const s = getKeychainHelperStatus();
+        console.log(chalk.bold('Source:     '), s.source ?? chalk.red('(not found)'));
+        console.log(chalk.bold('Destination:'), s.destination);
+        console.log(chalk.bold('Installed:  '), s.installed ? chalk.green('yes') : chalk.yellow('no'));
+        if (s.installed) {
+            console.log(chalk.bold('codesign:   '), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+            console.log(chalk.bold('spctl:      '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+        }
+        else {
+            console.log(chalk.dim('Run `agents helper install` to copy the bundled .app to the destination.'));
+        }
+    });
+    cmd
+        .command('where')
+        .description('Print the absolute path to the installed helper executable')
+        .action(() => {
+        requireDarwin();
+        try {
+            console.log(getKeychainHelperPath());
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+    });
+}