@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/README.md

@@ -250,16 +250,44 @@ agents secrets create prod-stripe
 agents secrets add prod-stripe STRIPE_SECRET_KEY     # Prompts, stores in Keychain
 agents secrets add prod-stripe TEST_CARD --value "4242..."
 
-# Injected at run time. The YAML on disk has only refs.
+# Injected at run time. Bundle definitions live in the Keychain, not on disk.
 agents run claude "charge a test card" --secrets prod-stripe
 ```
 
 <p align="center">
-  <img src="assets/secrets.svg" alt="How agents-cli secrets work: stripe.yml holds a pointer, the macOS Keychain holds the value, agents-cli resolves at runtime and injects the env into the child process" width="100%" />
+  <img src="assets/secrets.svg" alt="How agents-cli secrets work: bundle definitions live in the macOS Keychain alongside their values, agents-cli resolves at runtime and injects the env into the child process" width="100%" />
 </p>
 
 Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
 
+### Cross-machine sync via iCloud Keychain
+
+Pass `--icloud-sync` when creating a bundle and both the bundle definition and its values are written to the iCloud-synced keychain. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the bundle appears there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores.
+
+```bash
+# On laptop:
+agents secrets create npm-tokens --icloud-sync
+agents secrets add npm-tokens NPM_TOKEN          # value lives in iCloud Keychain
+
+# On another Mac (same iCloud account):
+agents secrets list                              # npm-tokens is already there;
+agents run claude "..." --secrets npm-tokens     # injects NPM_TOKEN automatically
+```
+
+Under the hood, `--icloud-sync` routes writes through a notarized helper app (`AgentsKeychain.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles without `--icloud-sync` stay device-local.
+
+Bundle definitions sync via iCloud Keychain too — no `agents repo push` needed for secrets, no recreate step on each Mac. Nothing about secrets ever lives in plaintext on disk.
+
+### Per-secret metadata and rotation
+
+Tag each secret with `--type`, `--expires`, and `--note` so the bundle is self-documenting. `--expires` is always future-dated (`YYYY-MM-DD`); past or same-day values are rejected. Use `agents secrets rotate <bundle> <key>` to refresh a credential — `add` only creates new keys, `rotate` replaces the value and preserves metadata unless overridden.
+
+```bash
+agents secrets add prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "Live key, owner: payments-team"
+agents secrets rotate prod STRIPE_API_KEY --note "rotated after suspected leak"
+agents secrets list   # EXPIRING column flags secrets due in the next 30 days
+```
+
 ---
 
 ## Routines
@@ -403,7 +431,7 @@ No. API keys come from your shell environment or each agent CLI's existing auth.
 
 macOS and Linux. Windows via WSL works but isn't first-class yet.
 
-**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. The `--icloud-sync` flag on bundles requires macOS + iCloud Keychain enabled. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
 ### Do I need Node.js?
 

package/dist/commands/browser.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerBrowserCommand(program: Command): void;

package/dist/commands/browser.js

@@ -0,0 +1,388 @@
+import { listProfiles, getProfile, createProfile, deleteProfile, } from '../lib/browser/profiles.js';
+import { sendIPCRequest } from '../lib/browser/ipc.js';
+import { isValidTaskId } from '../lib/browser/types.js';
+export function registerBrowserCommand(program) {
+    const browser = program
+        .command('browser')
+        .description('Browser automation via CDP');
+    registerProfilesCommands(browser);
+    registerTaskCommands(browser);
+}
+function registerProfilesCommands(browser) {
+    const profiles = browser
+        .command('profiles')
+        .description('Manage browser profiles');
+    profiles
+        .command('list')
+        .alias('ls')
+        .description('List all browser profiles')
+        .action(async () => {
+        const allProfiles = await listProfiles();
+        if (allProfiles.length === 0) {
+            console.log('No browser profiles configured.');
+            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 VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge'];
+    profiles
+        .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('-s, --secrets <bundle>', 'Secrets bundle to inject')
+        .option('-d, --description <text>', 'Profile description')
+        .option('--headless', 'Run in headless mode')
+        .action(async (name, opts) => {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            console.error('Profile name must be lowercase alphanumeric with hyphens');
+            process.exit(1);
+        }
+        if (!VALID_BROWSERS.includes(opts.browser)) {
+            console.error(`Invalid browser type. Must be one of: ${VALID_BROWSERS.join(', ')}`);
+            process.exit(1);
+        }
+        const profile = {
+            name,
+            description: opts.description,
+            browser: opts.browser,
+            endpoints: opts.endpoint,
+            secrets: opts.secrets,
+            chrome: opts.headless ? { headless: true } : undefined,
+        };
+        await createProfile(profile);
+        console.log(`Created profile: ${name}`);
+    });
+    profiles
+        .command('show <name>')
+        .description('Show profile details')
+        .action(async (name) => {
+        const profile = await getProfile(name);
+        if (!profile) {
+            console.error(`Profile "${name}" not found`);
+            process.exit(1);
+        }
+        console.log(`Name: ${profile.name}`);
+        console.log(`Browser: ${profile.browser}`);
+        if (profile.description)
+            console.log(`Description: ${profile.description}`);
+        console.log(`Endpoints:`);
+        for (const e of profile.endpoints) {
+            console.log(`  - ${e}`);
+        }
+        if (profile.secrets)
+            console.log(`Secrets: ${profile.secrets}`);
+        if (profile.chrome?.headless)
+            console.log(`Headless: true`);
+    });
+    profiles
+        .command('delete <name>')
+        .description('Delete a browser profile')
+        .action(async (name) => {
+        await deleteProfile(name);
+        console.log(`Deleted profile: ${name}`);
+    });
+}
+function registerTaskCommands(browser) {
+    browser
+        .command('start [task]')
+        .description('Start a browser task')
+        .requiredOption('-p, --profile <name>', 'Browser profile to use')
+        .action(async (task, opts) => {
+        if (task && !isValidTaskId(task)) {
+            console.error('Task ID must be lowercase alphanumeric with hyphens');
+            process.exit(1);
+        }
+        const response = await sendIPCRequest({
+            action: 'start',
+            profile: opts.profile,
+            task,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(response.task);
+    });
+    browser
+        .command('stop <task>')
+        .description('Stop a browser task and close its tabs')
+        .action(async (task) => {
+        const response = await sendIPCRequest({
+            action: 'stop',
+            task,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(`Stopped task: ${task}`);
+    });
+    browser
+        .command('navigate <task> <url>')
+        .description('Open a URL in the task window')
+        .option('-p, --profile <name>', 'Browser profile (optional if task is unique)')
+        .action(async (task, url, opts) => {
+        const response = await sendIPCRequest({
+            action: 'navigate',
+            task,
+            url,
+            profile: opts.profile,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(`Opened tab ${response.tabId}: ${url}`);
+    });
+    browser
+        .command('tabs [task]')
+        .description('List open tabs')
+        .option('-p, --profile <name>', 'Filter by profile')
+        .action(async (task, opts) => {
+        const response = await sendIPCRequest({
+            action: 'tabs',
+            task,
+            profile: opts.profile,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        if (!response.tabs || response.tabs.length === 0) {
+            console.log('No tabs open');
+            return;
+        }
+        console.log('TASK'.padEnd(15) + 'TAB'.padEnd(12) + 'URL');
+        console.log('-'.repeat(80));
+        for (const tab of response.tabs) {
+            const shortId = tab.id.slice(0, 8);
+            console.log(tab.task.padEnd(15) +
+                shortId.padEnd(12) +
+                tab.url.slice(0, 55));
+        }
+    });
+    browser
+        .command('close <task> [tabId]')
+        .description('Close tabs for a task')
+        .action(async (task, tabId) => {
+        const response = await sendIPCRequest({
+            action: 'close',
+            task,
+            tabId,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(tabId ? `Closed tab ${tabId}` : `Closed all tabs for task ${task}`);
+    });
+    browser
+        .command('screenshot <task> [tabId]')
+        .description('Take a screenshot')
+        .option('-o, --output <path>', 'Output path')
+        .action(async (task, tabId, opts) => {
+        const response = await sendIPCRequest({
+            action: 'screenshot',
+            task,
+            tabId,
+            path: opts.output,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(response.path);
+    });
+    browser
+        .command('evaluate <task> <tabId> <expression>')
+        .description('Evaluate JavaScript in a tab')
+        .action(async (task, tabId, expression) => {
+        const response = await sendIPCRequest({
+            action: 'evaluate',
+            task,
+            tabId,
+            expr: expression,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(response.result, null, 2));
+    });
+    browser
+        .command('status')
+        .description('Show running browser tasks')
+        .option('-p, --profile <name>', 'Filter by profile')
+        .action(async (opts) => {
+        const response = await sendIPCRequest({
+            action: 'status',
+            profile: opts.profile,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        if (!response.profiles || response.profiles.length === 0) {
+            console.log('No browser profiles running');
+            return;
+        }
+        for (const profile of response.profiles) {
+            console.log(`\n${profile.name} (port ${profile.port}, pid ${profile.pid})`);
+            if (profile.tasks.length === 0) {
+                console.log('  No active tasks');
+            }
+            else {
+                console.log('  TASK'.padEnd(17) + 'TABS'.padEnd(8) + 'CREATED');
+                for (const task of profile.tasks) {
+                    const age = formatAge(task.createdAt);
+                    console.log('  ' +
+                        task.id.padEnd(15) +
+                        String(task.tabCount).padEnd(8) +
+                        age);
+                }
+            }
+        }
+    });
+    browser
+        .command('tasks')
+        .description('List all browser tasks')
+        .option('-p, --profile <name>', 'Filter by profile')
+        .action(async (opts) => {
+        const response = await sendIPCRequest({
+            action: 'status',
+            profile: opts.profile,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        const allTasks = [];
+        for (const profile of response.profiles || []) {
+            for (const task of profile.tasks) {
+                allTasks.push({
+                    profile: profile.name,
+                    id: task.id,
+                    tabs: task.tabCount,
+                    created: task.createdAt,
+                });
+            }
+        }
+        if (allTasks.length === 0) {
+            console.log('No active tasks');
+            return;
+        }
+        console.log('PROFILE'.padEnd(18) + 'TASK'.padEnd(15) + 'TABS'.padEnd(8) + 'CREATED');
+        console.log('-'.repeat(55));
+        for (const t of allTasks) {
+            console.log(t.profile.padEnd(18) +
+                t.id.padEnd(15) +
+                String(t.tabs).padEnd(8) +
+                formatAge(t.created));
+        }
+    });
+    browser
+        .command('refs <task> [tabId]')
+        .description('Get DOM refs for interactive elements')
+        .option('--all', 'Include non-interactive elements')
+        .option('-l, --limit <n>', 'Max elements (default 500)', '500')
+        .action(async (task, tabId, opts) => {
+        const response = await sendIPCRequest({
+            action: 'refs',
+            task,
+            tabId,
+            interactive: !opts.all,
+            limit: parseInt(opts.limit, 10),
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(response.refs);
+    });
+    browser
+        .command('click <task> <tabId> <ref>')
+        .description('Click an element by ref')
+        .action(async (task, tabId, ref) => {
+        const response = await sendIPCRequest({
+            action: 'click',
+            task,
+            tabId,
+            ref: parseInt(ref, 10),
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log('Clicked');
+    });
+    browser
+        .command('type <task> <tabId> <ref> <text>')
+        .description('Type text into an element by ref')
+        .action(async (task, tabId, ref, text) => {
+        const response = await sendIPCRequest({
+            action: 'type',
+            task,
+            tabId,
+            ref: parseInt(ref, 10),
+            text,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log('Typed');
+    });
+    browser
+        .command('press <task> <tabId> <key>')
+        .description('Press a key (Enter, Tab, Escape, etc)')
+        .action(async (task, tabId, key) => {
+        const response = await sendIPCRequest({
+            action: 'press',
+            task,
+            tabId,
+            key,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log('Pressed');
+    });
+    browser
+        .command('hover <task> <tabId> <ref>')
+        .description('Hover over an element by ref')
+        .action(async (task, tabId, ref) => {
+        const response = await sendIPCRequest({
+            action: 'hover',
+            task,
+            tabId,
+            ref: parseInt(ref, 10),
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log('Hovered');
+    });
+}
+function collect(val, memo) {
+    memo.push(val);
+    return memo;
+}
+function formatAge(timestamp) {
+    const seconds = Math.floor((Date.now() - timestamp) / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ago`;
+}

package/dist/commands/daemon.js

@@ -92,7 +92,7 @@ you never need to start it manually.
         warnDeprecated('logs', 'agents routines scheduler-logs');
         if (options.follow) {
             const { getAgentsDir } = await import('../lib/state.js');
-            const logPath = path.join(getAgentsDir(), 'daemon.log');
+            const logPath = path.join(getAgentsDir(), 'helpers/daemon/logs.jsonl');
             const child = spawn('tail', ['-f', logPath], { stdio: ['ignore', 'pipe', 'pipe'] });
             child.stdout.pipe(process.stdout);
             child.stderr.pipe(process.stderr);

package/dist/commands/doctor.d.ts

@@ -1,15 +1,22 @@
 /**
  * `agents doctor` — diagnostic readout across the install.
  *
- * Three sections:
- *   1. CLI availability — which agent binaries can be invoked.
- *   2. Sync status — per (agent, default-version), is the version-home sync
- *      manifest fresh? (sync runs at launch; this surfaces what would happen.)
- *   3. Orphans — per resource type per default version, count of files that
- *      would be removed by `agents prune`.
- *
- * Read-only: doctor never mutates state. Run `agents prune` to act on the
- * orphan readout, or just launch the agent to apply pending sync.
+ * Two modes:
+ *
+ *   1. Overview (no target): three sections —
+ *      - CLI availability (which agent binaries can be invoked).
+ *      - Sync status per default version (fresh / stale / never-synced).
+ *      - Orphans per default version per resource type.
+ *
+ *   2. Target mode: `agents doctor <agent>[@version]` — full per-resource
+ *      diff for a single (agent, version) against the current cwd's resolved
+ *      sources. Reports ok / DIFF / MISS / EXTRA per resource with the source
+ *      layer (project, user, system, extra repo). With `--diff`, renders a
+ *      unified diff body for each divergent file. Mirrors the resolution that
+ *      the shim drives at runtime: project > user > system > extras.
+ *
+ * Read-only: doctor never mutates state. Run `agents prune` to act on orphan
+ * readouts, or just launch the agent to apply pending sync.
  */
 import type { Command } from 'commander';
 export declare function registerDoctorCommand(program: Command): void;