@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/dist/commands/drive.js

@@ -1,183 +0,0 @@
-/**
- * Drive sync commands.
- *
- * Registers the `agents drive` command tree for syncing agent session
- * history across machines via rsync. Supports pull, push, attach
- * (redirect agent homes to drive), and detach operations.
- */
-import chalk from 'chalk';
-import ora from 'ora';
-import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
-import { setRemote, pull, push, attach, detach, getDriveStatus, } from '../lib/drive-sync.js';
-/** Register the `agents drive` command tree. */
-export function registerDriveCommands(program) {
-    const enabled = isBetaEnabled('drive');
-    const driveCmd = program
-        .command('drive', { hidden: !enabled })
-        .description('Sync agent session history across machines via rsync. Set up once, then pull/push to keep sessions in sync.')
-        .addHelpText('after', `
-Typical workflow:
-  # One-time setup: point to your remote machine
-  agents drive remote user@hostname
-
-  # Pull sessions from remote to local
-  agents drive pull
-
-  # Work locally with your agents...
-
-  # Push your new sessions back to remote
-  agents drive push
-
-  # Check sync state
-  agents drive status
-
-Use case: Keep session history consistent across your laptop and desktop,
-or back up sessions to a server you control.
-`);
-    driveCmd.hook('preAction', () => {
-        if (enabled)
-            return;
-        console.error(chalk.red('agents drive is in beta.'));
-        console.error(chalk.gray(betaEnableHint('drive')));
-        process.exit(1);
-    });
-    driveCmd
-        .command('remote <target>')
-        .description('Set the rsync remote target (e.g., user@hostname). Sessions sync to <target>:~/.agents/drive/')
-        .addHelpText('after', `
-Examples:
-  # Set remote to a server
-  agents drive remote user@server
-
-  # Set remote to a local machine on your network
-  agents drive remote macbook.local
-`)
-        .action((target) => {
-        try {
-            setRemote(target);
-            console.log(chalk.green(`Remote set to ${target}`));
-            console.log(chalk.gray(`Syncs to ${target}:~/.agents/drive/`));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    driveCmd
-        .command('pull')
-        .description('Fetch sessions from the remote and merge them into your local ~/.agents/drive/.')
-        .addHelpText('after', `
-Example:
-  agents drive pull
-
-Run this when you switch machines to get the latest session history.
-`)
-        .action(async () => {
-        const spinner = ora('Pulling from remote...').start();
-        try {
-            await pull();
-            spinner.succeed('Pull complete');
-        }
-        catch (err) {
-            spinner.fail(err.message);
-            process.exit(1);
-        }
-    });
-    driveCmd
-        .command('push')
-        .description('Upload your local sessions to the remote so other machines can pull them.')
-        .addHelpText('after', `
-Example:
-  agents drive push
-
-Run this after working locally to share your new sessions with other machines.
-`)
-        .action(async () => {
-        const spinner = ora('Pushing to remote...').start();
-        try {
-            await push();
-            spinner.succeed('Push complete');
-        }
-        catch (err) {
-            spinner.fail(err.message);
-            process.exit(1);
-        }
-    });
-    driveCmd
-        .command('attach')
-        .description('Point your agent homes (~/.claude, etc.) at drive so sessions write directly to the synced location.')
-        .addHelpText('after', `
-Example:
-  agents drive attach
-
-After attach, agent sessions are saved to ~/.agents/drive/ instead of version homes.
-Use 'detach' to switch back to version-specific homes.
-`)
-        .action(() => {
-        try {
-            attach();
-            console.log(chalk.green('Drive attached'));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    driveCmd
-        .command('detach')
-        .description('Restore agent homes back to their version-specific directories (undo attach).')
-        .addHelpText('after', `
-Example:
-  agents drive detach
-`)
-        .action(() => {
-        try {
-            detach();
-            console.log(chalk.green('Drive detached'));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    driveCmd
-        .command('status')
-        .description('Show current drive configuration, attach state, and last sync times.')
-        .addHelpText('after', `
-Example:
-  agents drive status
-`)
-        .action(() => {
-        const status = getDriveStatus();
-        console.log(chalk.bold('Drive'));
-        console.log(`  Remote:     ${status.remote || chalk.gray('not set')}`);
-        console.log(`  Attached:   ${status.attached ? chalk.green('yes') : chalk.gray('no')}`);
-        console.log(`  Last pull:  ${status.lastPull ? formatTime(status.lastPull) : chalk.gray('never')}`);
-        console.log(`  Last push:  ${status.lastPush ? formatTime(status.lastPush) : chalk.gray('never')}`);
-        console.log(`  Path:       ${chalk.gray(status.driveDir)}`);
-        console.log('');
-        console.log(chalk.bold('Symlinks'));
-        console.log(`  ~/.claude       -> ${status.configDirTarget || chalk.gray('not a symlink')}`);
-        for (const [hf, target] of Object.entries(status.homeFileTargets)) {
-            console.log(`  ~/${hf}  -> ${target || chalk.gray('not a symlink')}`);
-        }
-    });
-}
-/** Format an ISO timestamp as a human-readable relative time (e.g. "5 min ago"). */
-function formatTime(iso) {
-    const d = new Date(iso);
-    const now = Date.now();
-    const diffMin = Math.floor((now - d.getTime()) / 60_000);
-    if (diffMin < 1)
-        return 'just now';
-    if (diffMin < 60)
-        return `${diffMin} min ago`;
-    const diffHrs = Math.floor(diffMin / 60);
-    if (diffHrs < 24)
-        return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
-    const diffDays = Math.floor(diffHrs / 24);
-    if (diffDays < 7)
-        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-    return `${months[d.getMonth()]} ${d.getDate()}`;
-}

package/dist/commands/hq.d.ts

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

package/dist/commands/hq.js

@@ -1,58 +0,0 @@
-import chalk from 'chalk';
-import { getActiveSessions } from '../lib/session/active.js';
-import { AgentManager } from '../lib/teams/agents.js';
-import { handleStatus, handleTasks } from '../lib/teams/api.js';
-import { listAskStats, listBlocks } from '../lib/feed.js';
-import { buildSessionSignals, synthesizeControlCards } from '../lib/feed-ranking.js';
-import { discoverSessions } from '../lib/session/discover.js';
-import { buildHqFloor } from '../lib/hq/floor.js';
-import { die } from '../lib/format.js';
-async function collectFloorSnapshot() {
-    const manager = new AgentManager();
-    const [sessions, tasksResult] = await Promise.all([
-        getActiveSessions(),
-        handleTasks(manager, 1000),
-    ]);
-    const teammatesByTeam = new Map();
-    await Promise.all(tasksResult.tasks.map(async (team) => {
-        const status = await handleStatus(manager, team.task_name, 'all');
-        teammatesByTeam.set(team.task_name, status.agents);
-    }));
-    const sessionMetas = sessions.length > 0 ? await discoverSessions({ all: true, limit: 5000 }) : [];
-    const blocks = [
-        ...listBlocks(),
-        ...synthesizeControlCards(buildSessionSignals(sessions, sessionMetas), listAskStats()),
-    ];
-    return buildHqFloor({
-        sessions,
-        teams: tasksResult.tasks,
-        teammatesByTeam,
-        blocks,
-    });
-}
-export function registerHqCommand(program) {
-    const hq = program
-        .command('hq')
-        .description('Machine-readable bridge for Agents HQ floor management.');
-    hq
-        .command('floor')
-        .description('Emit the live floor snapshot: rooms, agents, ambient events, and runnable actions.')
-        .option('--json', 'Output machine-readable JSON')
-        .action(async (opts) => {
-        try {
-            const snapshot = await collectFloorSnapshot();
-            if (opts.json || !process.stdout.isTTY) {
-                console.log(JSON.stringify(snapshot, null, 2));
-                return;
-            }
-            console.log(chalk.bold('Agents HQ floor'));
-            console.log(chalk.gray(`${snapshot.counters.agents} agents, ${snapshot.counters.rooms} rooms, ${snapshot.counters.needsInput} need input`));
-            for (const room of snapshot.rooms) {
-                console.log(`${chalk.cyan(room.name)}  ${chalk.gray(`${room.counts.agents} agents, ${room.counts.running} running, ${room.counts.needsInput} need input`)}`);
-            }
-        }
-        catch (err) {
-            die(err.message);
-        }
-    });
-}

package/dist/commands/sessions-sync.d.ts

@@ -1,17 +0,0 @@
-/**
- * `agents sessions sync` — push this machine's transcripts to R2 and pull every
- * other machine's, merging copies of the same session via CRDT union. The local
- * sessions index is rebuilt from the synced-in mirror by the normal scanner.
- */
-import type { Command } from 'commander';
-interface SyncCmdOptions {
-    verbose?: boolean;
-    json?: boolean;
-    enable?: boolean;
-    disable?: boolean;
-    status?: boolean;
-    setup?: boolean;
-}
-export declare function runSessionsSync(options: SyncCmdOptions): Promise<void>;
-export declare function registerSessionsSyncCommand(sessionsCmd: Command): void;
-export {};

package/dist/commands/sessions-sync.js

@@ -1,135 +0,0 @@
-/**
- * `agents sessions sync` — push this machine's transcripts to R2 and pull every
- * other machine's, merging copies of the same session via CRDT union. The local
- * sessions index is rebuilt from the synced-in mirror by the normal scanner.
- */
-import chalk from 'chalk';
-import { setHelpSections } from '../lib/help.js';
-import { isSyncConfigured, SYNC_BUNDLE } from '../lib/session/sync/config.js';
-import { isBetaEnabled, setBetaEnabled, betaEnableHint } from '../lib/beta.js';
-import { syncSessions } from '../lib/session/sync/sync.js';
-/** The daemon's automatic session sync is gated by this beta feature. */
-const SYNC_BETA = 'session-sync';
-export async function runSessionsSync(options) {
-    // Toggle / status delegate to the `session-sync` beta feature — the single
-    // source of truth for whether the daemon auto-syncs (opt-in, off by default).
-    // These short-circuit before any network cycle.
-    if (options.disable) {
-        setBetaEnabled([SYNC_BETA], false);
-        console.log(chalk.yellow('Automatic session sync disabled') +
-            chalk.dim(' — the daemon stops pushing/pulling within ~90s. (Same as: agents beta disable session-sync)'));
-        return;
-    }
-    if (options.enable) {
-        setBetaEnabled([SYNC_BETA], true);
-        console.log(chalk.green('Automatic session sync enabled') +
-            chalk.dim(' — the daemon resumes on its next cycle. (Same as: agents beta enable session-sync)'));
-        return;
-    }
-    if (options.setup) {
-        const { promptAndProvisionSessionSync } = await import('./sync-provision.js');
-        await promptAndProvisionSessionSync({ explicit: true });
-        return;
-    }
-    if (options.status) {
-        const enabled = isBetaEnabled(SYNC_BETA);
-        const configured = isSyncConfigured();
-        if (options.json) {
-            console.log(JSON.stringify({ enabled, configured }, null, 2));
-        }
-        else {
-            console.log(`automatic sync: ${enabled ? chalk.green('enabled (beta)') : chalk.yellow('disabled')}` +
-                chalk.dim('  ·  ') +
-                `credentials: ${configured ? chalk.green('configured') : chalk.yellow(`missing (${SYNC_BUNDLE})`)}`);
-            if (!enabled)
-                console.log(chalk.dim(`  ${betaEnableHint(SYNC_BETA)}`));
-        }
-        return;
-    }
-    if (!isSyncConfigured()) {
-        console.error(chalk.red(`Sessions sync is not configured.`) +
-            `\nAdd R2 credentials to the '${SYNC_BUNDLE}' bundle:\n` +
-            `  agents secrets add ${SYNC_BUNDLE} R2_ACCOUNT_ID\n` +
-            `  agents secrets add ${SYNC_BUNDLE} R2_BUCKET_NAME\n` +
-            `  agents secrets add ${SYNC_BUNDLE} R2_ACCESS_KEY_ID\n` +
-            `  agents secrets add ${SYNC_BUNDLE} R2_SECRET_ACCESS_KEY\n` +
-            chalk.dim('\nOr let a guided prompt mint the bundle for you: ') + chalk.cyan('agents sessions sync --setup'));
-        process.exitCode = 1;
-        return;
-    }
-    try {
-        const result = await syncSessions({
-            verbose: options.verbose,
-            log: msg => console.error(chalk.dim(msg)),
-        });
-        if (options.json) {
-            console.log(JSON.stringify(result, null, 2));
-        }
-        else {
-            const parts = [
-                `pushed ${result.pushed}`,
-                `pulled ${result.pulled}`,
-                result.merged > 0 ? `merged ${result.merged}` : null,
-            ].filter(Boolean);
-            console.log(chalk.green('synced') + ` ${result.machine}: ` + parts.join(', ') +
-                chalk.dim(` (${result.pushSkipped + result.pullSkipped} unchanged)`));
-        }
-        if (!options.json && result.warnings.length > 0) {
-            for (const w of result.warnings)
-                console.error(chalk.yellow(`  warning: ${w}`));
-        }
-        if (result.errors.length > 0) {
-            for (const e of result.errors)
-                console.error(chalk.yellow(`  ! ${e}`));
-            process.exitCode = 1;
-        }
-    }
-    catch (err) {
-        console.error(chalk.red(`sync failed: ${err.message}`));
-        process.exitCode = 1;
-    }
-}
-export function registerSessionsSyncCommand(sessionsCmd) {
-    const syncCmd = sessionsCmd
-        .command('sync')
-        .description('Sync session transcripts across machines via R2 (CRDT merge). Claude, Codex, Droid, Grok, Kimi, and OpenCode.')
-        .option('-v, --verbose', 'Log each pushed and pulled session')
-        .option('--json', 'Output the sync result as JSON')
-        .option('--setup', 'Guided provisioning: mint the r2.backups bundle, verify connectivity, and enable sync')
-        .option('--enable', 'Opt in to automatic background sync (beta; alias for: agents beta enable session-sync)')
-        .option('--disable', 'Opt out of automatic background sync (alias for: agents beta disable session-sync)')
-        .option('--status', 'Show whether automatic sync is opted-in (beta) and configured');
-    setHelpSections(syncCmd, {
-        examples: `
-      # Guided first-time setup (mint R2 bundle, verify, enable)
-      agents sessions sync --setup
-
-      # One sync cycle (push local changes, pull + merge from other machines)
-      agents sessions sync
-
-      # See exactly what moved
-      agents sessions sync --verbose
-
-      # Stop this machine's daemon from auto-syncing (prefer on-demand --host reads)
-      agents sessions sync --disable
-
-      # Check the current switch + credential state
-      agents sessions sync --status
-    `,
-        notes: `
-      - Credentials come from the '${SYNC_BUNDLE}' secrets bundle (R2 S3 API, read+write).
-      - Each machine writes only its own prefix; conflicts are impossible by construction.
-      - Sessions present locally always win; synced-in copies fill in other machines' sessions.
-      - Automatic background sync is an opt-in BETA feature, OFF by default. The daemon only
-        syncs (~90s) once you opt in via 'agents beta enable session-sync' (or the --enable
-        alias here). A bare 'agents sessions sync' always forces a manual one-shot cycle
-        regardless of the beta opt-in.
-    `,
-    });
-    // `--json` is also declared on the parent `sessions` command, so a bare
-    // `options` arg would miss it (Commander binds the shared flag to the parent).
-    // optsWithGlobals() merges ancestor + local options so --json resolves here.
-    syncCmd.action(async (_options, cmd) => {
-        await runSessionsSync(cmd.optsWithGlobals());
-    });
-}

package/dist/commands/sync-provision.d.ts

@@ -1,23 +0,0 @@
-/**
- * Interactive provisioning flow for cross-machine session sync. Collects R2
- * credentials, writes the `r2.backups` bundle (via the pure lib helper), probes
- * connectivity, and opts the machine into the `session-sync` beta. Shared by
- * `agents setup` (offered, opt-in) and `agents sessions sync --setup` (explicit).
- *
- * The prompt/UI lives here in the command layer; the credential-writing and
- * connectivity logic is the pure, unit-tested `lib/session/sync/provision.ts`.
- */
-export interface ProvisionFlowOptions {
-    /**
-     * True when invoked explicitly (`agents sessions sync --setup`): we go straight
-     * into provisioning. False when offered inside `agents setup`: we ask first,
-     * default to No, and silently skip when already configured.
-     */
-    explicit?: boolean;
-}
-/**
- * Run the guided session-sync setup. Never throws for expected outcomes
- * (non-interactive shell, user declines, cancels, or a failed probe) — returns
- * quietly so a first-run `agents setup` is never blocked by the optional step.
- */
-export declare function promptAndProvisionSessionSync(opts?: ProvisionFlowOptions): Promise<void>;

package/dist/commands/sync-provision.js

@@ -1,107 +0,0 @@
-/**
- * Interactive provisioning flow for cross-machine session sync. Collects R2
- * credentials, writes the `r2.backups` bundle (via the pure lib helper), probes
- * connectivity, and opts the machine into the `session-sync` beta. Shared by
- * `agents setup` (offered, opt-in) and `agents sessions sync --setup` (explicit).
- *
- * The prompt/UI lives here in the command layer; the credential-writing and
- * connectivity logic is the pure, unit-tested `lib/session/sync/provision.ts`.
- */
-import chalk from 'chalk';
-import ora from 'ora';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { isSyncConfigured } from '../lib/session/sync/config.js';
-import { writeSyncBundle, probeR2Connectivity, readStoredEncKey } from '../lib/session/sync/provision.js';
-import { setBetaEnabled } from '../lib/beta.js';
-const SYNC_BETA = 'session-sync';
-const nonEmpty = (v) => (v.trim().length > 0 ? true : 'required');
-/**
- * Run the guided session-sync setup. Never throws for expected outcomes
- * (non-interactive shell, user declines, cancels, or a failed probe) — returns
- * quietly so a first-run `agents setup` is never blocked by the optional step.
- */
-export async function promptAndProvisionSessionSync(opts = {}) {
-    if (!isInteractiveTerminal()) {
-        if (opts.explicit)
-            console.error(chalk.red('Session-sync setup needs an interactive terminal.'));
-        return;
-    }
-    const alreadyConfigured = isSyncConfigured();
-    const { confirm, input, password } = await import('@inquirer/prompts');
-    try {
-        if (!opts.explicit) {
-            if (alreadyConfigured)
-                return; // first-run setup: nothing to do
-            const want = await confirm({
-                message: 'Set up cross-machine session sync (encrypted transcripts via Cloudflare R2)?',
-                default: false,
-            });
-            if (!want)
-                return;
-        }
-        else if (alreadyConfigured) {
-            const reconfigure = await confirm({
-                message: 'Session sync is already configured. Re-enter R2 credentials?',
-                default: false,
-            });
-            if (!reconfigure) {
-                const key = readStoredEncKey();
-                if (key) {
-                    console.log(chalk.dim('\nShared encryption key (paste on every other machine you sync):'));
-                    console.log('  ' + chalk.cyan(key));
-                }
-                return;
-            }
-        }
-        console.log(chalk.dim('\nR2 credentials — Cloudflare dashboard > R2 > Manage API Tokens (needs read+write):'));
-        const accountId = (await input({ message: 'R2 account ID:', validate: nonEmpty })).trim();
-        const bucketName = (await input({ message: 'R2 bucket name:', validate: nonEmpty })).trim();
-        const accessKeyId = (await password({ message: 'R2 access key ID:', mask: true })).trim();
-        const secretAccessKey = (await password({ message: 'R2 secret access key:', mask: true })).trim();
-        const endpoint = (await input({
-            message: 'S3 endpoint override (blank = Cloudflare R2):',
-            default: '',
-        })).trim();
-        // Encryption key: the first machine mints one; every other machine pastes it
-        // so the whole fabric shares a single key (and can decrypt each other).
-        const firstMachine = await confirm({ message: 'Is this the FIRST machine in your sync fabric?', default: true });
-        let encKey;
-        if (!firstMachine) {
-            encKey = (await password({
-                message: 'Paste the shared R2_SYNC_ENC_KEY from your first machine:',
-                mask: true,
-                validate: nonEmpty,
-            })).trim();
-        }
-        const { encKeyAction } = writeSyncBundle({
-            accountId, bucketName, accessKeyId, secretAccessKey,
-            endpoint: endpoint || undefined,
-            encKey: encKey || undefined,
-        });
-        const spinner = ora('Validating R2 read+write...').start();
-        const probe = await probeR2Connectivity();
-        if (!probe.ok) {
-            spinner.fail(`R2 probe failed: ${probe.error}`);
-            console.log(chalk.yellow('Credentials were saved to the r2.backups bundle but not verified. Fix them and re-run ' +
-                '`agents sessions sync --setup`, or rotate one key with `agents secrets rotate r2.backups <KEY>`.'));
-            return; // do not auto-enable sync against credentials that don't work
-        }
-        spinner.succeed('R2 read+write verified.');
-        setBetaEnabled([SYNC_BETA], true);
-        console.log(chalk.green('\nSession sync configured and enabled') + chalk.dim(' (the daemon syncs every ~90s).'));
-        if (encKeyAction === 'generated') {
-            const key = readStoredEncKey();
-            console.log(chalk.bold('\nShared encryption key — paste this on every OTHER machine you sync:'));
-            console.log('  ' + chalk.cyan(key ?? '(unavailable)'));
-            console.log(chalk.dim('Anyone with this key can decrypt your transcripts. Keep it secret.'));
-        }
-        console.log(chalk.dim('\nSync now with: agents sessions sync'));
-    }
-    catch (err) {
-        if (isPromptCancelled(err)) {
-            console.log(chalk.yellow('\nSession-sync setup cancelled.'));
-            return;
-        }
-        throw err;
-    }
-}

package/dist/lib/drive-sync.d.ts

@@ -1,45 +0,0 @@
-/**
- * Remote drive sync for agent sessions and config.
- *
- * Provides rsync-based push/pull between the local ~/.agents/drive/
- * directory and a remote host, plus attach/detach to swap the active
- * agent's config directory symlink to the drive directory (for working
- * with a remote machine's session data locally).
- */
-/** Persisted drive configuration stored at ~/.agents/drive/config.json. */
-export interface DriveConfig {
-    remote: string | null;
-    attached: boolean;
-    previousTargets: {
-        configDir: string;
-        homeFiles: Record<string, string>;
-    } | null;
-    lastPull: string | null;
-    lastPush: string | null;
-}
-/** Read drive config from disk, returning defaults if missing. */
-export declare function readDriveConfig(): DriveConfig;
-/** Write drive config to disk. */
-export declare function writeDriveConfig(config: DriveConfig): void;
-/** Set the remote target (user@host) for rsync operations. */
-export declare function setRemote(target: string): void;
-/** Pull drive data from the remote host via rsync. */
-export declare function pull(): Promise<void>;
-/** Push local drive data to the remote host via rsync. */
-export declare function push(): Promise<void>;
-/** Attach drive by swapping the agent's config directory symlink to the drive directory. */
-export declare function attach(): void;
-/** Detach drive by restoring the agent's config directory to its previous symlink target. */
-export declare function detach(): void;
-/** Current drive state for display purposes. */
-export interface DriveStatus {
-    remote: string | null;
-    attached: boolean;
-    lastPull: string | null;
-    lastPush: string | null;
-    driveDir: string;
-    configDirTarget: string | null;
-    homeFileTargets: Record<string, string | null>;
-}
-/** Gather current drive status by inspecting config, symlinks, and timestamps. */
-export declare function getDriveStatus(): DriveStatus;