@phnx-labs/agents-cli 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 1.17.0
+
+**Workflows: a new first-class resource**
+
+- `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.
+
+**Browser**
+
+- 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).
+
+**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
 
 **System-repo sweep: ~/.agents-system reduced to npm-shipped defaults only**

package/dist/commands/browser.js

@@ -1,4 +1,8 @@
-import { listProfiles, getProfile, createProfile, deleteProfile, } from '../lib/browser/profiles.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, } from '../lib/browser/profiles.js';
+import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
+import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { sendIPCRequest } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
@@ -28,11 +32,23 @@ function registerProfilesCommands(browser) {
             console.log('Create one with: agents browser profiles create <name> --endpoint <url>');
             return;
         }
-        console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'ENDPOINTS');
-        console.log('-'.repeat(72));
-        for (const p of allProfiles) {
-            const endpoints = p.endpoints.join(', ');
-            console.log(p.name.padEnd(20) + (p.browser || '-').padEnd(12) + endpoints);
+        const hasDescriptions = allProfiles.some(p => p.description);
+        if (hasDescriptions) {
+            console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'DESCRIPTION'.padEnd(38) + 'ENDPOINTS');
+            console.log('-'.repeat(92));
+            for (const p of allProfiles) {
+                const endpoints = p.endpoints.join(', ');
+                const desc = (p.description ?? '').slice(0, 36).padEnd(38);
+                console.log(p.name.padEnd(20) + (p.browser || '-').padEnd(12) + desc + endpoints);
+            }
+        }
+        else {
+            console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'ENDPOINTS');
+            console.log('-'.repeat(72));
+            for (const p of allProfiles) {
+                const endpoints = p.endpoints.join(', ');
+                console.log(p.name.padEnd(20) + (p.browser || '-').padEnd(12) + endpoints);
+            }
         }
     });
     const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge'];
@@ -40,10 +56,12 @@ function registerProfilesCommands(browser) {
         .command('create <name>')
         .description('Create a new browser profile')
         .requiredOption('-b, --browser <type>', `Browser type: ${VALID_BROWSERS.join(', ')}`)
-        .requiredOption('-e, --endpoint <url>', 'CDP endpoint URL (repeatable)', collect, [])
+        .option('-e, --endpoint <url>', 'CDP endpoint URL (repeatable; auto-assigned if omitted)', collect, [])
         .option('-s, --secrets <bundle>', 'Secrets bundle to inject')
         .option('-d, --description <text>', 'Profile description')
         .option('--headless', 'Run in headless mode')
+        .option('--window <WxH>', 'Window size, e.g. 1512x982')
+        .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
         .action(async (name, opts) => {
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
             console.error('Profile name must be lowercase alphanumeric with hyphens');
@@ -53,13 +71,43 @@ function registerProfilesCommands(browser) {
             console.error(`Invalid browser type. Must be one of: ${VALID_BROWSERS.join(', ')}`);
             process.exit(1);
         }
+        // Auto-assign a free port if no endpoint was provided
+        let endpoints = opts.endpoint;
+        if (endpoints.length === 0) {
+            const freePort = await findFreeProfilePort();
+            endpoints = [`cdp://127.0.0.1:${freePort}`];
+        }
+        // Viewport is mandatory — default to 1512x982 if --window is not provided
+        let viewport = {
+            width: 1512,
+            height: 982,
+        };
+        if (opts.window) {
+            const m = String(opts.window).match(/^(\d+)x(\d+)$/);
+            if (!m) {
+                console.error('--window must be WxH, e.g. 1512x982');
+                process.exit(1);
+            }
+            viewport.width = parseInt(m[1], 10);
+            viewport.height = parseInt(m[2], 10);
+        }
+        if (opts.position) {
+            const m = String(opts.position).match(/^(-?\d+),(-?\d+)$/);
+            if (!m) {
+                console.error('--position must be X,Y, e.g. 80,80');
+                process.exit(1);
+            }
+            viewport.x = parseInt(m[1], 10);
+            viewport.y = parseInt(m[2], 10);
+        }
         const profile = {
             name,
             description: opts.description,
             browser: opts.browser,
-            endpoints: opts.endpoint,
+            endpoints,
             secrets: opts.secrets,
             chrome: opts.headless ? { headless: true } : undefined,
+            viewport,
         };
         await createProfile(profile);
         console.log(`Created profile: ${name}`);
@@ -103,6 +151,172 @@ function registerProfilesCommands(browser) {
         await deleteProfile(name);
         console.log(`Deleted profile: ${name}`);
     });
+    profiles
+        .command('launch <name>')
+        .description('Start (or attach to) the profile\'s browser without creating a task')
+        .action(async (name) => {
+        const profile = await getProfile(name);
+        if (!profile) {
+            console.error(`Profile "${name}" not found`);
+            process.exit(1);
+        }
+        const response = await sendIPCRequest({
+            action: 'launch-profile',
+            profile: name,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        const pidLabel = response.pid ? `pid ${response.pid}` : 'attached';
+        console.log(`Launched "${name}" on port ${response.port} (${pidLabel})`);
+        console.log(`Next: agents browser start --profile ${name} --url <url>`);
+    });
+    profiles
+        .command('doctor <name>')
+        .description('Diagnose a browser profile: binary, port, user-data-dir, onboarding state')
+        .action(async (name) => {
+        const profile = await getProfile(name);
+        if (!profile) {
+            console.error(`Profile "${name}" not found`);
+            process.exit(1);
+        }
+        const checks = [];
+        // 1. Binary exists for declared browser type
+        try {
+            const binPath = findBrowserPath(profile.browser, profile.binary);
+            checks.push({ label: 'binary', ok: true, detail: binPath });
+        }
+        catch (err) {
+            checks.push({
+                label: 'binary',
+                ok: false,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        // 2. Configured port: free, or already serving the expected browser?
+        const port = extractConfiguredPort(profile);
+        let attachingToExistingBrowser = false;
+        if (port === undefined) {
+            checks.push({ label: 'port', ok: true, detail: 'no port in endpoint' });
+        }
+        else {
+            const occupant = getPortOccupant(port);
+            if (!occupant) {
+                checks.push({ label: 'port', ok: true, detail: `${port} is free` });
+            }
+            else {
+                try {
+                    const { browser } = await discoverBrowserWsUrl(port);
+                    verifyBrowserIdentity(browser, profile.browser, port);
+                    checks.push({
+                        label: 'port',
+                        ok: true,
+                        detail: `${port} serving ${browser} (pid ${occupant.pid})`,
+                    });
+                    attachingToExistingBrowser = true;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    checks.push({
+                        label: 'port',
+                        ok: false,
+                        detail: `${port} taken by ${occupant.command} (pid ${occupant.pid}) — ${msg}`,
+                    });
+                }
+            }
+        }
+        // 3. User-data-dir exists and is writable
+        const userDataDir = path.join(getProfileRuntimeDir(name), 'chrome-data');
+        try {
+            if (!fs.existsSync(userDataDir)) {
+                checks.push({
+                    label: 'user-data-dir',
+                    ok: true,
+                    detail: `will be created at ${userDataDir}`,
+                });
+            }
+            else {
+                fs.accessSync(userDataDir, fs.constants.W_OK);
+                checks.push({ label: 'user-data-dir', ok: true, detail: userDataDir });
+            }
+        }
+        catch (err) {
+            checks.push({
+                label: 'user-data-dir',
+                ok: false,
+                detail: `${userDataDir} not writable: ${err instanceof Error ? err.message : err}`,
+            });
+        }
+        // 4. Onboarding heuristic — only meaningful when WE will launch the
+        // browser. When the configured port is already serving a debuggable
+        // browser, that browser owns its own user-data-dir and the priming
+        // status of our managed dir is irrelevant.
+        if (attachingToExistingBrowser) {
+            checks.push({
+                label: 'onboarding',
+                ok: true,
+                detail: 'n/a (attaching to existing browser)',
+            });
+        }
+        else {
+            const localStatePath = path.join(userDataDir, 'Local State');
+            if (fs.existsSync(localStatePath)) {
+                const size = fs.statSync(localStatePath).size;
+                if (size > 0) {
+                    checks.push({ label: 'onboarding', ok: true, detail: 'Local State present' });
+                }
+                else {
+                    checks.push({
+                        label: 'onboarding',
+                        ok: false,
+                        detail: 'Local State is empty — run `agents browser profiles prime ' + name + '`',
+                    });
+                }
+            }
+            else {
+                checks.push({
+                    label: 'onboarding',
+                    ok: false,
+                    detail: 'Not primed yet — run `agents browser profiles prime ' + name + '`',
+                });
+            }
+        }
+        const allOk = checks.every((c) => c.ok);
+        for (const c of checks) {
+            const marker = c.ok ? 'OK  ' : 'FAIL';
+            console.log(`${marker}  ${c.label.padEnd(15)} ${c.detail}`);
+        }
+        if (!allOk)
+            process.exit(1);
+    });
+    profiles
+        .command('prime <name>')
+        .description('Launch the profile so you can complete first-run onboarding interactively')
+        .action(async (name) => {
+        const profile = await getProfile(name);
+        if (!profile) {
+            console.error(`Profile "${name}" not found`);
+            process.exit(1);
+        }
+        const response = await sendIPCRequest({
+            action: 'launch-profile',
+            profile: name,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        const pidLabel = response.pid ? `pid ${response.pid}` : 'attached';
+        console.log(`Launched "${name}" on port ${response.port} (${pidLabel}).`);
+        console.log('');
+        console.log('Finish any first-run / onboarding screens in the browser window');
+        console.log('(welcome, profile setup, default-browser prompt, sign-in, etc.).');
+        console.log('Once you reach a normal browsing surface, this profile is primed');
+        console.log('— its user-data-dir persists across runs, so you only do this once.');
+        console.log('');
+        console.log(`Next: agents browser start --profile ${name} --url <url>`);
+    });
 }
 function registerTaskCommands(browser) {
     browser
@@ -370,7 +584,10 @@ function registerTaskCommands(browser) {
                 const portLabel = profile.configuredPort && profile.configuredPort !== profile.port
                     ? `port ${profile.port} (configured ${profile.configuredPort})`
                     : `port ${profile.port}`;
-                console.log(`\n${profile.name} (${portLabel}, pid ${profile.pid})`);
+                // pid 0 means the daemon attached to a browser we didn't launch — no
+                // tracked pid. Render it as "attached" rather than the literal 0.
+                const pidLabel = profile.pid ? `pid ${profile.pid}` : 'attached';
+                console.log(`\n${profile.name} (${portLabel}, ${pidLabel})`);
                 if (profile.tasks.length === 0) {
                     console.log('  No active tasks');
                 }
@@ -588,6 +805,28 @@ function registerTaskCommands(browser) {
         }
         console.log('Hovered');
     });
+    browser
+        .command('scroll <task> <deltaX> <deltaY>')
+        .description('Scroll the page by pixel amount')
+        .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('-x, --at-x <x>', 'X coordinate to dispatch scroll from (default 0)', parseInt)
+        .option('-y, --at-y <y>', 'Y coordinate to dispatch scroll from (default 0)', parseInt)
+        .action(async (task, deltaX, deltaY, opts) => {
+        const response = await sendIPCRequest({
+            action: 'scroll',
+            task,
+            tabId: opts.tab,
+            scrollX: parseInt(deltaX, 10),
+            scrollY: parseInt(deltaY, 10),
+            scrollAtX: opts.atX,
+            scrollAtY: opts.atY,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log('Scrolled');
+    });
     // ─── Viewport & Device ───────────────────────────────────────────────────────
     const setCmd = browser.command('set').description('Set browser emulation options');
     setCmd

package/dist/commands/cloud.js

@@ -106,6 +106,9 @@ Examples:
         .option('--env <id>', 'Codex Cloud environment ID')
         .option('--computer <name>', 'Factory/Droid computer target')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
+        .option('-b, --balanced', 'Shortcut for --strategy balanced. Route the factory run across all healthy accounts.')
+        .option('--strategy <strategy>', 'Account selection strategy for the factory: balanced. Sends all healthy accounts so the factory pod rotates between them on rate-limit.')
+        .option('--upload-account-tokens', 'Upload Claude OAuth credentials to Rush Cloud on first dispatch (consent recorded for future runs).')
         .option('--json', 'Structured JSON output')
         .option('--no-follow', 'Dispatch and exit without streaming output')
         .addHelpText('after', `
@@ -165,6 +168,11 @@ Examples:
             dispatchOptions.providerOptions.computer = options.computer;
         if (options.mode)
             dispatchOptions.providerOptions.mode = options.mode;
+        if (options.balanced || options.strategy === 'balanced') {
+            dispatchOptions.providerOptions.strategy = 'balanced';
+        }
+        if (options.uploadAccountTokens)
+            dispatchOptions.providerOptions.uploadAccountTokens = true;
         // Dispatch
         const spinner = ora({ text: `Dispatching to ${provider.name}...`, stream: process.stderr }).start();
         let task;

package/dist/commands/exec.js

@@ -8,9 +8,22 @@
 import chalk from 'chalk';
 import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
 import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
+import { getSystemAgentsDir, getUserAgentsDir } from '../lib/state.js';
+/** Resolve a workflow by name. User repo wins over system repo. Returns the workflow dir or null. */
+function resolveWorkflow(name) {
+    for (const base of [getUserAgentsDir(), getSystemAgentsDir()]) {
+        const dir = path.join(base, 'workflows', name);
+        if (fs.existsSync(path.join(dir, 'WORKFLOW.md')))
+            return dir;
+    }
+    return null;
+}
 import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
 import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
-import { resolveVersionAlias } from '../lib/versions.js';
+import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
+import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.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) {
@@ -122,6 +135,62 @@ Examples:
                 process.exit(1);
             }
         }
+        else if (resolveWorkflow(rawAgent)) {
+            // Workflow: ~/.agents-system/workflows/<name>/ or ~/.agents/workflows/<name>/
+            // Resolution: user repo wins over system repo (same precedence as all resources).
+            // Structure:
+            //   WORKFLOW.md        ← orchestrator instructions fed to claude as system prompt
+            //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
+            const workflowDir = resolveWorkflow(rawAgent);
+            agent = 'claude';
+            const resolvedVersion = resolveVersionAlias('claude', version);
+            const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
+            const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
+            // Copy subagents/*.md into ~/.claude/agents/ so Claude's Agent tool finds them.
+            const subagentsDir = path.join(workflowDir, 'subagents');
+            if (fs.existsSync(subagentsDir)) {
+                fs.mkdirSync(claudeAgentsDir, { recursive: true });
+                for (const file of fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md'))) {
+                    fs.copyFileSync(path.join(subagentsDir, file), path.join(claudeAgentsDir, file));
+                }
+            }
+            // Feed WORKFLOW.md body (strip frontmatter) as orchestrator system context.
+            const workflowMd = path.join(workflowDir, 'WORKFLOW.md');
+            const orchestratorBody = fs.existsSync(workflowMd)
+                ? fs.readFileSync(workflowMd, 'utf-8').replace(/^---[\s\S]*?---\n/, '').trim()
+                : '';
+            if (orchestratorBody && prompt !== undefined) {
+                prompt = `${orchestratorBody}\n\n---\n\n${prompt}`;
+            }
+            // Sync workflow-scoped skills into the version home's skills dir.
+            const workflowSkillsDir = path.join(workflowDir, 'skills');
+            if (fs.existsSync(workflowSkillsDir)) {
+                const skillsTarget = path.join(claudeAgentsDir, '..', 'skills');
+                fs.mkdirSync(skillsTarget, { recursive: true });
+                for (const entry of fs.readdirSync(workflowSkillsDir, { withFileTypes: true })) {
+                    if (!entry.isDirectory())
+                        continue;
+                    fs.cpSync(path.join(workflowSkillsDir, entry.name), path.join(skillsTarget, entry.name), { recursive: true });
+                }
+            }
+            // Sync workflow-scoped plugins into the version home.
+            const workflowPluginsDir = path.join(workflowDir, 'plugins');
+            if (fs.existsSync(workflowPluginsDir)) {
+                for (const entry of fs.readdirSync(workflowPluginsDir, { withFileTypes: true })) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const pluginRoot = path.join(workflowPluginsDir, entry.name);
+                    const manifest = loadPluginManifest(pluginRoot);
+                    if (!manifest)
+                        continue;
+                    syncPluginToVersion(buildDiscoveredPlugin(pluginRoot, manifest), 'claude', versionHome);
+                }
+            }
+            const subagentCount = fs.existsSync(subagentsDir)
+                ? fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')).length
+                : 0;
+            process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
+        }
         else {
             console.error(chalk.red(`Unknown agent: ${rawAgent}`));
             console.error(chalk.gray(`Available agents: ${VALID_AGENTS.join(', ')}`));