@phnx-labs/agents-cli 1.14.7 → 1.16.0

package/CHANGELOG.md

@@ -1,62 +1,101 @@
 # Changelog
 
-## 1.14.6
+## 1.16.0
 
-**Fix: OAuth token refresh now persists to Keychain**
+**System-repo sweep: ~/.agents-system reduced to npm-shipped defaults only**
 
-- Fixed bug where refreshed Claude OAuth tokens were used but never saved back to macOS Keychain
-- Previously, agents-cli would refresh expired tokens on each run but discard them, eventually exhausting the refresh token
-- Now refreshed `accessToken`, `refreshToken`, and `expiresAt` are written back to Keychain after successful refresh
-- Accounts will stay healthy across runs without requiring re-login
+- New migrators move every form of operational state out of ~/.agents-system into user-side buckets: sessions, teams (live + per-run), trash, repos (→ ~/.agents-<alias>/ peer dirs), legacy swarm/, cache/, cloud/.
+- SQLite DBs merge row-level (INSERT OR IGNORE) into the user-side DB; filesystem dirs merge dir-by-dir with user-side winning on collision.
+- Dead artifacts dropped automatically: bin/agents-keychain-*, empty shims/, .DS_Store-only versions/ skeletons.
+- Unrecognized leftover dirs print a one-line stderr warning so future drift surfaces immediately.
+- Migration diagnostics moved to stderr — `eval "$(agents secrets export …)"` stops being polluted by log lines.
+- DB merge now skips FTS5 virtual + shadow tables (previously corrupted the session_text index). Indexer re-populates FTS on the next scan.
+- Stale ~/.agents-system/agents.yaml is now dropped when a user copy exists.
 
-## 1.14.5
+**~/.agents split into .history/ and .cache/ buckets**
 
-**Browser: custom binary and Electron app support**
+- Durable runtime state (sessions, versions, runs, teams/agents, trash, backups) moves to ~/.agents/.history/.
+- Regenerable runtime state (shims, packages, cloud, logs, swarmify, helpers, browser runtime, fetch cache, dot-files) moves to ~/.agents/.cache/.
+- Single-line gitignore for backing up ~/.agents/ — no more per-subdir cherry-picking.
 
-- Added `binary` field to browser profiles for specifying custom executable paths (e.g., Electron apps like Rush)
-- Added `electron` field to browser profiles — when true, uses existing windows instead of creating new ones (Electron doesn't support `Target.createTarget`)
-- New `custom` browser type that requires a binary path
-- Works with both local and SSH-based browser connections
-- Example profile for Rush: `agents browser profiles edit rush --browser custom --binary "/Applications/Rush.app/Contents/MacOS/Rush" --electron`
+**Browser: profiles fold into agents.yaml + many new automation commands**
+
+- Profile YAMLs at ~/.agents/browser/profiles/*.yaml now live as a `browser:` section in agents.yaml. Single user-facing file, single sync.
+- Single window per profile; `start` renamed to `open`; new tab subcommands; session history with profile picker; viewport piped through to the launched browser.
+- New commands: `agents browser set viewport`, `set device`, `devices`, `console`, `errors`, `requests`, `responsebody`, `wait`, `download`, `waitdownload`.
+
+**Hooks: hooks.yaml folded into agents.yaml `hooks:` section**
+
+- ~/.agents/hooks.yaml is migrated into agents.yaml on first run; the standalone file is removed.
+- System repo ships the same shape — one config file, layered project > user > system.
+
+**Sessions & secrets**
+
+- `agents secrets exec <bundle> -- <command>` injects a bundle's env vars into a one-shot subprocess (no shell-state leakage).
+- `agents sessions` now groups active sessions by workspace and surfaces session topics in the picker.
+- Session discovery scans both version repos; migrator merges overlapping versions instead of leaving duplicates.
+
+**Renames**
+
+- `agents init` → `agents setup`.
+- `permissions/sets/` → `permissions/presets/` (resource directory + on-disk migration to match rules/presets convention).
+
+**Dev**
 
-## Unreleased
+- Crabbox remote-test profile (~$0.14/hr) + `scripts/sandbox.sh` documented in README and CLAUDE.md. Tests run remotely to avoid freezing the local machine.
 
-**System repo moved to `~/.agents-system`; `~/.agents` is now free for user-owned repos**
+## 1.15.0
 
-- The CLI-managed global root now lives under `~/.agents-system/` instead of `~/.agents/`. This includes `agents.yaml`, commands, skills, hooks, rules, versions, shims, routines, runs, plugins, secrets, and managed extra-repo clones.
-- `agents init` and `agents pull` now bootstrap and sync the fixed system repo in `~/.agents-system/`.
-- `agents repo init` now supports `--from <source>` and no longer pushes users toward generated names like `~/.agents-mine`; `~/.agents` is now the recommended clean path for a personal repo.
+**Secrets: Linux support via libsecret/GNOME Keyring**
 
-**Scheduler merged into `routines`; top-level help simplified**
+- `agents secrets` now works on Linux backed by libsecret/GNOME Keyring with the same UX as macOS Keychain. Headless workarounds documented.
+- New `agents password generate` subcommand.
+- Lifecycle events emitted for secrets and other subsystems; richer metadata (timing helpers) on the events system.
 
-- `agents routines add` now auto-starts the background scheduler when it is not already running. First-time users no longer need a separate `daemon start` step — the common path is just `routines add`.
-- New subcommands mirror the old daemon controls under `routines`: `agents routines start`, `stop`, `status`, `scheduler-logs`. The word "daemon" is no longer exposed in user-facing help.
-- `agents daemon <start|stop|status|logs>` is **deprecated**. It still works but prints a migration warning and is hidden from top-level help. Will be removed in v2.0.
-- Top-level help restructured: the old "Automation" grab-bag is gone. Commands are now grouped as **Run agents** (`run`, `teams`, `sessions`), **Schedule** (`routines`), and **Helpers** (`pty`).
+**Browser**
 
-**Dev: sqlite auto-rebuild on `bun run test`**
+- HTTP and WebSocket endpoint support for remote browsers.
+- Concurrent Electron profile forks no longer step on each other; cleanup hardened.
+- Remote browser restart works; SSH port handling improved; page target created when none exists for Electron apps.
+- Events emitted for navigation and screenshots.
 
-- Added `scripts/rebuild-sqlite.sh` and a `pretest` hook. The script probes `better-sqlite3` by opening an in-memory database and only rebuilds (plain `node-gyp rebuild --release`, no Electron flags) when the probe fails. Fixes the napi ABI mismatch that `bun install` sometimes leaves behind.
+**First-run UX**
 
-**Default upstream moved to `phnx-labs/.agents`**
+- Improved new-user experience: clearer CLI help, better defaults, audit-log opt-out, better run-timing display.
 
-- `DEFAULT_SYSTEM_REPO` now resolves to `gh:phnx-labs/.agents` — a curated, org-owned upstream. `agents pull` (no args) and `agents fork` target the new repo on fresh machines.
-- Existing users whose upstream still points at the old default see a one-time nudge on `agents pull --upstream` with the command to switch. Nothing else breaks; legacy remotes continue to work.
+**Prune**
 
-**Consolidate sessions command**
+- `agents prune` learned `trash`, `sessions`, and `runs` cleanup targets.
 
-- Removed `agents sessions list` and `agents sessions view` subcommands; `agents sessions` is now a single smart command
-- Positional query resolves to a session ID (renders directly), a path (`.`, `../`, `/path`) to filter by project, or free text for search
-- Claude `/resume` history fallback (previously only in `view`) now fires from the top-level command too
-- Picker shows the selected-session preview by default; space hides it
+**Fixes**
 
-**Session view flags: filters + formats split cleanly**
+- Command-injection hole in daemon + secrets closed.
+- Layered permission resolution corrected; daemon tests isolated from real user state.
+- `.tmp-bun` gitignore pattern fixed.
+- `codex` interactive mode no longer routes through `exec` subcommand.
 
-- Formats: default is the activity summary; `--markdown` renders the full conversation (user + assistant + thinking + tool calls) as markdown; `--json` emits normalized events
-- Filters compose orthogonally: `--include <roles>` / `--exclude <roles>` (values: `user`, `assistant`, `thinking`, `tools`), plus `--first N` / `--last N` to slice by turn (a turn starts at each user message)
-- Any filter flag without `--markdown`/`--json` defaults to markdown output — summary is an aggregate view so filters would be meaningless there
-- Mutual exclusion: `--include` vs `--exclude`, `--first` vs `--last`
-- Removed `--transcript`, `--trace`, `--timeline`, and `--role` (replaced by the above)
+**Docs**
+
+- Security/privacy section in README, browser skill + automation guide, FAQ updated with audit-log transparency.
+
+## 1.14.6
+
+**Fix: OAuth token refresh now persists to Keychain**
+
+- Fixed bug where refreshed Claude OAuth tokens were used but never saved back to macOS Keychain
+- Previously, agents-cli would refresh expired tokens on each run but discard them, eventually exhausting the refresh token
+- Now refreshed `accessToken`, `refreshToken`, and `expiresAt` are written back to Keychain after successful refresh
+- Accounts will stay healthy across runs without requiring re-login
+
+## 1.14.5
+
+**Browser: custom binary and Electron app support**
+
+- Added `binary` field to browser profiles for specifying custom executable paths (e.g., Electron apps like Rush)
+- Added `electron` field to browser profiles — when true, uses existing windows instead of creating new ones (Electron doesn't support `Target.createTarget`)
+- New `custom` browser type that requires a binary path
+- Works with both local and SSH-based browser connections
+- Example profile for Rush: `agents browser profiles edit rush --browser custom --binary "/Applications/Rush.app/Contents/MacOS/Rush" --electron`
 
 ## 1.12.0
 

package/README.md

@@ -53,6 +53,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [PTY](#pty)
 - [Portable setup](#portable-setup)
 - [Private skills](#private-skills)
+- [Security & Privacy](#security--privacy)
 - [Compatibility](#compatibility)
 - [FAQ](#faq)
 
@@ -252,12 +253,12 @@ Give agents access to a real browser — no relay extension, no cloud service, n
 agents browser profiles create work --browser chrome
 
 # Start a task, navigate, interact
-agents browser start login-flow --profile work
-agents browser navigate login-flow https://app.example.com
+agents browser start --profile work --task login-flow --url https://app.example.com
 agents browser refs login-flow              # Get interactive element refs
-agents browser click login-flow <tab> 42    # Click element ref 42
-agents browser type login-flow <tab> 15 "hello"
+agents browser click login-flow 42          # Click element ref 42
+agents browser type login-flow 15 "hello"   # Type into element ref 15
 agents browser screenshot login-flow        # Smart resizing, token-efficient
+agents browser done login-flow              # Close task's tabs when finished
 ```
 
 ### Why this works where Playwright fails
@@ -293,9 +294,9 @@ agents browser profiles create bank --browser chrome --secrets bank-creds
 Control Electron apps (Slack, Discord, VS Code, your own app) with custom binaries:
 
 ```bash
-agents browser profiles create rush \
+agents browser profiles create slack \
   --browser custom \
-  --binary "/Applications/Rush.app/Contents/MacOS/Rush" \
+  --binary "/Applications/Slack.app/Contents/MacOS/Slack" \
   --electron
 ```
 
@@ -453,6 +454,70 @@ Extras clone into `~/.agents-system/.repos/<alias>/` and ship the same layout as
 
 ---
 
+## Security & Privacy
+
+**Everything stays on your machine.** No telemetry, no cloud sync (unless you opt into iCloud Keychain for secrets), no phone-home. Here's exactly what `agents-cli` stores locally and why.
+
+### Event log
+
+Every agent run, version install, browser launch, and secrets access is logged to `~/.agents/logs/events-YYYY-MM-DD.jsonl`. This gives you a complete record of what agents did on your machine.
+
+```bash
+# What gets logged (example event):
+{
+  "ts": "2026-05-09T10:23:45Z",
+  "event": "agent.run.end",
+  "agent": "claude",
+  "version": "2.1.121",
+  "prompt": "Fix the auth bug in...",  # truncated to 200 chars
+  "durationMs": 45230,
+  "exitCode": 0,
+  "hostname": "your-mac",
+  "platform": "darwin"
+}
+```
+
+**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors. **What's NOT logged:** Full prompts, outputs, file contents, secret values (only bundle names).
+
+**Permissions:** Logs directory is `0700` (owner-only), files are `0600`. Only you can read them.
+
+**Retention:** 30 days by default, then auto-pruned.
+
+**Opt out:** Set `AGENTS_DISABLE_EVENT_LOG=1` in your shell to disable completely.
+
+### Session search
+
+Conversations with Claude, Codex, Gemini, and other agents scatter across their native storage. Session search indexes them locally so you can find any conversation:
+
+```bash
+agents sessions "auth middleware"     # Full-text search across all agents
+agents sessions --agent claude --since 7d
+```
+
+The index lives at `~/.agents/sessions/sessions.db` (SQLite + FTS5). Nothing leaves your machine. See [Sessions](#sessions-across-agents) for full usage.
+
+### Secrets
+
+API keys and credentials are stored in macOS Keychain, never in plaintext files. Bundle definitions also live in Keychain.
+
+```bash
+agents secrets create my-keys
+agents secrets add my-keys API_KEY    # Prompts for value, stores in Keychain
+```
+
+With `--icloud-sync`, secrets sync via iCloud Keychain to your other Macs. Without it, they stay device-local. See [Secrets](#secrets) for full usage.
+
+### Summary
+
+| Data | Location | Who can read | Opt out |
+|------|----------|--------------|---------|
+| Event log | `~/.agents/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` |
+| Session index | `~/.agents/sessions/` | You only | Delete the directory |
+| Secrets | macOS Keychain | You + apps you authorize | Don't use `agents secrets` |
+| Config | `~/.agents/` | You only | N/A |
+
+---
+
 ## Compatibility
 
 | Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
@@ -505,7 +570,9 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 ### Does it store my API keys or send telemetry?
 
-No. API keys come from your shell environment or each agent CLI's existing auth. No telemetry, no phone-home. User content lives in `~/.agents/`; operational state (versions, shims, sessions, caches) lives in `~/.agents-system/`.
+**No telemetry, no phone-home.** Everything stays local. API keys come from your shell environment or each agent CLI's existing auth.
+
+For full transparency: `agents-cli` keeps a local event log at `~/.agents/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.
 
 ### Which platforms?
 

package/dist/commands/alias.js

@@ -1,10 +1,10 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
-import { getAgentsDir } from '../lib/state.js';
+import { getUserAgentsDir } from '../lib/state.js';
 import { getShimsDir } from '../lib/shims.js';
 import { ALL_AGENT_IDS, AGENTS } from '../lib/agents.js';
-const ALIASES_FILE = path.join(getAgentsDir(), 'aliases.json');
+const ALIASES_FILE = path.join(getUserAgentsDir(), 'aliases.json');
 /** Names that would clobber an agent CLI shim or the `agents` binary itself. */
 function reservedNames() {
     const reserved = new Set(['agents']);

package/dist/commands/beta.js

@@ -1,5 +1,9 @@
 import chalk from 'chalk';
 import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBetaEnabled, } from '../lib/beta.js';
+const BETA_DESCRIPTIONS = {
+    drive: 'Google Drive integration for reading and writing files',
+    factory: 'Cloud-based agent dispatch via Rush Factory',
+};
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);
     const invalid = values.filter((value) => !valid.has(value));
@@ -29,7 +33,8 @@ Examples:
         console.log(chalk.bold('Beta Features'));
         for (const feature of ALL_BETA_FEATURES) {
             const state = enabled.has(feature) ? chalk.green('enabled') : chalk.gray('disabled');
-            console.log(`  ${feature.padEnd(8)} ${state}`);
+            const desc = BETA_DESCRIPTIONS[feature] || '';
+            console.log(`  ${feature.padEnd(10)} ${state.padEnd(18)} ${chalk.dim(desc)}`);
         }
         console.log('');
         console.log(chalk.gray(`Config: ${location.path}`));

package/dist/commands/browser-picker.d.ts

@@ -0,0 +1,21 @@
+import type { ProfileStatus, TaskStatus } from '../lib/browser/types.js';
+export interface BrowserTask {
+    task: TaskStatus;
+    profile: ProfileStatus;
+}
+export interface PickedBrowserTask {
+    task: BrowserTask;
+    action: 'view' | 'stop';
+}
+/** Build the preview pane for a browser task. */
+export declare function buildBrowserPreview(item: BrowserTask): string;
+/** Build the list label for a browser task. */
+export declare function buildBrowserLabel(item: BrowserTask, query: string): string;
+export interface BrowserPickerConfig {
+    message: string;
+    tasks: BrowserTask[];
+    pageSize?: number;
+    initialSearch?: string;
+}
+/** Show an interactive browser task picker. */
+export declare function browserTaskPicker(config: BrowserPickerConfig): Promise<PickedBrowserTask | null>;

package/dist/commands/browser-picker.js

@@ -0,0 +1,114 @@
+/**
+ * Interactive browser task picker with preview.
+ *
+ * Powers the fuzzy-searchable task list shown by `agents browser status` in a TTY.
+ * Shows task name, profile, domains, and tab count; preview pane shows full tab list.
+ */
+import chalk from 'chalk';
+import { itemPicker } from '../lib/picker.js';
+const DOT = chalk.gray(' · ');
+function humanDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    const mm = m % 60;
+    if (h < 24)
+        return mm ? `${h}h ${mm}m` : `${h}h`;
+    const d = Math.floor(h / 24);
+    const hh = h % 24;
+    return hh ? `${d}d ${hh}h` : `${d}d`;
+}
+function formatAge(ms) {
+    return humanDuration(Date.now() - ms) + ' ago';
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+/** Build the preview pane for a browser task. */
+export function buildBrowserPreview(item) {
+    const { task, profile } = item;
+    const lines = [];
+    // Line 1: Task name (ID: xxx)
+    lines.push(chalk.bold.white(`Task: ${task.name}`) + chalk.gray(` (${task.id})`));
+    // Line 2: Profile info
+    const profileParts = [chalk.cyan(profile.name)];
+    if (profile.port)
+        profileParts.push(`port ${profile.port}`);
+    if (profile.pid)
+        profileParts.push(`pid ${profile.pid}`);
+    lines.push(chalk.gray('Profile: ') + profileParts.join(DOT));
+    // Line 3: Timing
+    const started = formatAge(task.createdAt);
+    const duration = humanDuration(Date.now() - task.createdAt);
+    lines.push(chalk.gray('Started: ') + chalk.white(started) + DOT + chalk.gray('Duration: ') + chalk.white(duration));
+    // Blank line
+    lines.push('');
+    // Tabs section
+    if (task.tabs && task.tabs.length > 0) {
+        lines.push(chalk.gray('Tabs:'));
+        const termWidth = process.stdout.columns || 80;
+        const urlMax = Math.max(30, termWidth - 16);
+        for (const tab of task.tabs) {
+            const marker = tab.current ? chalk.yellow('*') : ' ';
+            const id = chalk.gray(tab.id);
+            const url = truncate(tab.url, urlMax);
+            lines.push(`  ${id} ${marker} ${chalk.white(url)}`);
+        }
+    }
+    else {
+        lines.push(chalk.gray('No tabs open'));
+    }
+    return lines.join('\n');
+}
+/** Build the list label for a browser task. */
+export function buildBrowserLabel(item, query) {
+    const { task, profile } = item;
+    const termWidth = process.stdout.columns || 80;
+    // Format: name profile tabs domains age
+    const name = task.name.padEnd(20);
+    const profileName = profile.name.padEnd(12);
+    const tabs = `${task.tabCount} tab${task.tabCount === 1 ? '' : 's'}`.padEnd(8);
+    const age = formatAge(task.createdAt);
+    // Domains - fill remaining space
+    const fixedWidth = 20 + 12 + 8 + 10; // name + profile + tabs + age
+    const domainsWidth = Math.max(10, termWidth - fixedWidth - 4);
+    const domains = task.domains?.length
+        ? truncate(task.domains.join(', '), domainsWidth)
+        : chalk.gray('no sites');
+    // Highlight query matches
+    let label = `${name}${chalk.cyan(profileName)}${tabs}${domains.padEnd(domainsWidth)}${chalk.gray(age)}`;
+    if (query) {
+        const re = new RegExp(`(${query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi');
+        label = label.replace(re, chalk.yellow.bold('$1'));
+    }
+    return label;
+}
+/** Show an interactive browser task picker. */
+export async function browserTaskPicker(config) {
+    const picked = await itemPicker({
+        message: config.message,
+        items: config.tasks,
+        filter: (query) => {
+            if (!query)
+                return config.tasks;
+            const q = query.toLowerCase();
+            return config.tasks.filter((t) => t.task.name.toLowerCase().includes(q) ||
+                t.profile.name.toLowerCase().includes(q) ||
+                t.task.domains?.some((d) => d.toLowerCase().includes(q)));
+        },
+        labelFor: buildBrowserLabel,
+        buildPreview: buildBrowserPreview,
+        shortIdFor: (t) => t.task.name,
+        pageSize: config.pageSize ?? 10,
+        initialSearch: config.initialSearch,
+        emptyMessage: 'No browser tasks running.',
+        enterHint: 'view tabs',
+    });
+    if (!picked)
+        return null;
+    return { task: picked.item, action: 'view' };
+}