@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -1,62 +1,166 @@
 # Changelog
 
-## 1.14.6
+## 1.17.0
 
-**Fix: OAuth token refresh now persists to Keychain**
+**Workflows: a new first-class resource**
 
-- 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
+- `agents workflows list / add / remove / view` — WORKFLOW.md bundles (with optional `subagents/`, `skills/`, `plugins/`) install from GitHub or a local path and resolve through the same system → user → project layer model as every other resource.
+- `agents run <name>` resolves a workflow or named subagent as an orchestrator: prepends WORKFLOW.md / AGENT.md body to the prompt, copies `subagents/*` into `~/.claude/agents/` for Agent-tool discovery, and syncs workflow-scoped `skills/` and `plugins/` at run time.
+- `agents view` now has a workflows section.
 
-## 1.14.5
+**Browser**
 
-**Browser: custom binary and Electron app support**
+- Port-per-profile with auto-allocation and viewport enforcement — concurrent browser profiles no longer collide on CDP ports.
+- `agents browser scroll` plus new `profiles launch`, `profiles doctor`, `profiles prime`, viewport position, and port diagnostics commands.
+- `agents browser profiles list` now shows a description column when any profile has one.
+- `isProcessRunning` treats EPERM as process-alive (fixes false-negative on sandboxed processes).
 
-- 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`
+**Cloud dispatch**
+
+- `--balanced` strategy and `--upload-account-tokens` flag on cloud dispatch.
+- Remote account API client; `--balanced` skips the client manifest path.
+
+**Plugin system extension**
+
+- Plugins now ship with `commands/`, `agents/`, `bin/`, MCP configs, settings, and `install` / `update` hooks. Discovery and sync extended end-to-end.
+
+**Secrets**
+
+- `agents secrets import <bundle> --from-1password` / `export <bundle> --to-1password` with vault picker, skip-empty-fields on import, overwrite-only-with-`--force` on export. Wires the existing 1Password library into the CLI.
+
+**Sandbox**
+
+- `scripts/sandbox.sh --pr` — author real PRs from a Crabbox-isolated box via a bare-mirror clone off main.
+- `sandbox.sh --linear` and `--post-file` post run output to Linear tickets.
+- Dynamic GitHub App token, `gh` CLI installed, stale git credentials cleaned.
+
+**Sessions / SQLite concurrency**
+
+- Scan coordinator prevents concurrent session indexing.
+- SQLite concurrency hardened with `BEGIN IMMEDIATE` and ledger recheck on contention.
+- Session discovery uses `getHistoryDir` for version roots and backup paths.
+
+**Run / shims / hooks**
+
+- Versioned alias shims regenerate on startup if missing.
+- Hooks prefer version-home scripts to prevent path breakage when the source dir moves.
+- Linux: claude shim sources `CLAUDE_CODE_OAUTH_TOKEN` from the per-version `.oauth_token` file when unset.
+
+**Resource UI**
+
+- `agents view` replaces path columns with OSC 8 hyperlinks for commands, skills, and rules.
+- Flat version resource lists replaced with source-pattern selection.
+
+**CI / security**
+
+- Gitleaks secret-scanning workflow on every push (switched to the free CLI, no org license needed).
+
+**Postinstall**
+
+- Correct shims dir, expanded aliases, prints changelog on install.
+
+**Dev**
+
+- Test isolation via vitest `pool: 'forks'`; mock state paths instead of hitting real `~/.agents/`.
+- Concurrent-writes benchmark for the session indexer.
+- Dead code + phantom deps removed: `src/commands/fork.ts`, `@aws-sdk/client-s3`, `@modelcontextprotocol/sdk`, `semver`.
+
+## 1.16.0
 
-## Unreleased
+**System-repo sweep: ~/.agents-system reduced to npm-shipped defaults only**
 
-**System repo moved to `~/.agents-system`; `~/.agents` is now free for user-owned repos**
+- 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.
 
-- 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.
+**~/.agents split into .history/ and .cache/ buckets**
 
-**Scheduler merged into `routines`; top-level help simplified**
+- 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.
 
-- `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: profiles fold into agents.yaml + many new automation commands**
 
-**Dev: sqlite auto-rebuild on `bun run test`**
+- 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`.
 
-- 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.
+**Hooks: hooks.yaml folded into agents.yaml `hooks:` section**
 
-**Default upstream moved to `phnx-labs/.agents`**
+- ~/.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.
 
-- `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.
+**Sessions & secrets**
 
-**Consolidate sessions command**
+- `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.
 
-- 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
+**Renames**
 
-**Session view flags: filters + formats split cleanly**
+- `agents init` → `agents setup`.
+- `permissions/sets/` → `permissions/presets/` (resource directory + on-disk migration to match rules/presets convention).
 
-- 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)
+**Dev**
+
+- 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.
+
+## 1.15.0
+
+**Secrets: Linux support via libsecret/GNOME Keyring**
+
+- `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.
+
+**Browser**
+
+- 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.
+
+**First-run UX**
+
+- Improved new-user experience: clearer CLI help, better defaults, audit-log opt-out, better run-timing display.
+
+**Prune**
+
+- `agents prune` learned `trash`, `sessions`, and `runs` cleanup targets.
+
+**Fixes**
+
+- 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.
+
+**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

@@ -253,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
@@ -294,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
 ```
 

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/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' };
+}