@phnx-labs/agents-cli 1.22.113 → 1.22.115

package/dist/commands/pty.js

@@ -1,404 +0,0 @@
-/**
- * PTY Commands
- *
- * CLI commands for managing interactive PTY sessions.
- * Auto-starts the sidecar server on first use.
- *
- * Usage:
- *   agents pty start [--rows 24 --cols 120 --shell zsh --cwd /path]
- *   agents pty exec  <id> <command>
- *   agents pty read  <id> [--ms 200]
- *   agents pty write <id> <input>
- *   agents pty screen <id>
- *   agents pty signal <id> [INT|TERM|KILL]
- *   agents pty list
- *   agents pty stop  <id>
- *   agents pty server [start|stop|status]
- */
-import chalk from 'chalk';
-import { ptyRequest, unescapeInput } from '../lib/pty-client.js';
-import { isPtyServerRunning, runPtyServer, getPtyPidPath, getPtyLogPath } from '../lib/pty-server.js';
-import * as fs from 'fs';
-import { setHelpSections } from '../lib/help.js';
-/** Register the `agents pty` command tree. */
-export function registerPtyCommands(program) {
-    const pty = program
-        .command('pty')
-        .description('Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.');
-    setHelpSections(pty, {
-        examples: `
-      # Start a session (returns a session ID)
-      SID=$(agents pty start)
-
-      # Run a command (non-blocking)
-      agents pty exec $SID "python3"
-
-      # Wait, then see what's on screen (clean text, no ANSI)
-      sleep 1 && agents pty screen $SID
-
-      # Type input (supports escapes: \\n \\t \\e \\xHH)
-      agents pty write $SID "print('hello')\\n"
-
-      # Read again
-      agents pty screen $SID
-
-      # Clean up
-      agents pty stop $SID
-    `,
-        notes: `
-      Use cases:
-        - Drive REPLs (python, node, irb) from agent code
-        - Automate TUI programs (npm init, interactive wizards)
-        - Test CLI tools that require a real PTY
-        - Run the 'agents' CLI itself from another agent
-
-      The PTY server auto-starts on first use and runs in the background.
-      Health: 'agents pty server status'.
-    `,
-    });
-    // --- Session lifecycle ---
-    const startCmd = pty
-        .command('start')
-        .description('Start a new PTY session and return its ID. The session persists until you stop it.')
-        .option('-r, --rows <n>', 'Terminal height in rows', '24')
-        .option('-c, --cols <n>', 'Terminal width in columns', '120')
-        .option('-s, --shell <shell>', 'Shell to launch (defaults to $SHELL, e.g., zsh, bash)')
-        .option('-d, --cwd <dir>', 'Working directory for the shell')
-        .option('--json', 'Output full session metadata as JSON');
-    setHelpSections(startCmd, {
-        examples: `
-      # Start a session and capture its ID
-      SID=$(agents pty start)
-
-      # Start a Python REPL in a specific directory
-      agents pty start --shell python3 --cwd /tmp
-
-      # Start a wider terminal for TUI programs
-      agents pty start --cols 160 --rows 40
-    `,
-    });
-    startCmd.action(async (opts) => {
-        const params = {
-            rows: parseInt(opts.rows, 10),
-            cols: parseInt(opts.cols, 10),
-        };
-        if (opts.shell)
-            params.shell = opts.shell;
-        if (opts.cwd)
-            params.cwd = opts.cwd;
-        const res = await ptyRequest('start', undefined, params);
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(res));
-        }
-        else {
-            console.log(res.id);
-        }
-    });
-    const execCmd = pty
-        .command('exec <id> <command>')
-        .description('Send a command to a PTY session. Returns immediately (non-blocking). Use screen or read to see output.')
-        .option('--wait <ms>', 'Wait this many milliseconds then return the screen (convenience for quick commands)', '0')
-        .option('--json', 'Output as JSON');
-    setHelpSections(execCmd, {
-        examples: `
-      # Run a command and return immediately
-      agents pty exec $SID "ls -la"
-
-      # Run a command and wait 500ms to see output
-      agents pty exec $SID "git status" --wait 500
-
-      # Start a long-running process (returns right away)
-      agents pty exec $SID "npm run dev"
-    `,
-    });
-    execCmd.action(async (id, command, opts) => {
-        const res = await ptyRequest('exec', id, { command });
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        const waitMs = parseInt(opts.wait, 10);
-        if (waitMs > 0) {
-            // Wait then return screen
-            await new Promise(r => setTimeout(r, waitMs));
-            const screen = await ptyRequest('screen', id);
-            if (opts.json) {
-                console.log(JSON.stringify(screen));
-            }
-            else if (screen.ok) {
-                console.log(screen.screen);
-            }
-        }
-        else if (opts.json) {
-            console.log(JSON.stringify(res));
-        }
-    });
-    const readCmd = pty
-        .command('read <id>')
-        .description('Read raw output from the PTY (includes ANSI codes). Use screen for clean text instead.')
-        .option('-m, --ms <ms>', 'Wait up to this many milliseconds for new output (50-5000)', '200')
-        .option('--json', 'Output as JSON');
-    setHelpSections(readCmd, {
-        examples: `
-      # Read pending output (wait up to 200ms)
-      agents pty read $SID
-
-      # Read with longer wait for slow commands
-      agents pty read $SID --ms 1000
-    `,
-    });
-    readCmd.action(async (id, opts) => {
-        const ms = parseInt(opts.ms, 10);
-        const res = await ptyRequest('read', id, { ms });
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(res));
-        }
-        else {
-            if (res.output)
-                process.stdout.write(res.output);
-        }
-    });
-    const writeCmd = pty
-        .command('write <id> <input>')
-        .description('Send keystrokes to the PTY (like typing into the terminal). Processes escape sequences by default.')
-        .option('--raw', 'Send input literally without processing \\n \\t \\e \\xHH escape codes')
-        .option('--json', 'Output as JSON');
-    setHelpSections(writeCmd, {
-        examples: `
-      # Send Enter key
-      agents pty write $SID "\\n"
-
-      # Type a command and press Enter
-      agents pty write $SID "ls -la\\n"
-
-      # Send Ctrl-C (interrupt signal)
-      agents pty write $SID "\\x03"
-
-      # Send Escape key
-      agents pty write $SID "\\e"
-
-      # Send literal backslash-n (not newline)
-      agents pty write $SID "\\\\n" --raw
-    `,
-    });
-    writeCmd.action(async (id, input, opts) => {
-        const processed = opts.raw ? input : unescapeInput(input);
-        const res = await ptyRequest('write', id, { input: processed });
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(res));
-        }
-    });
-    const screenCmd = pty
-        .command('screen <id>')
-        .description('Render the terminal screen as clean text (no ANSI codes). This is what a human sees looking at the terminal.')
-        .option('--json', 'Output as JSON (includes cursor position and dimensions)');
-    setHelpSections(screenCmd, {
-        examples: `
-      # See what's currently on screen
-      agents pty screen $SID
-
-      # Get screen with cursor position as JSON
-      agents pty screen $SID --json
-    `,
-        notes: `
-      Use this (not read) when you want clean text for an LLM to parse.
-    `,
-    });
-    screenCmd.action(async (id, opts) => {
-        const res = await ptyRequest('screen', id);
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(res));
-        }
-        else {
-            console.log(res.screen);
-        }
-    });
-    const signalCmd = pty
-        .command('signal <id> [signal]')
-        .description('Send a POSIX signal to the running process. Defaults to INT (Ctrl-C).');
-    setHelpSections(signalCmd, {
-        examples: `
-      # Send Ctrl-C (interrupt)
-      agents pty signal $SID INT
-
-      # Terminate gracefully
-      agents pty signal $SID TERM
-
-      # Force kill
-      agents pty signal $SID KILL
-    `,
-    });
-    signalCmd.action(async (id, signal) => {
-        const res = await ptyRequest('signal', id, { signal: signal || 'INT' });
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-    });
-    pty
-        .command('resize <id>')
-        .description('Resize a PTY session')
-        .option('-r, --rows <n>', 'Terminal rows')
-        .option('-c, --cols <n>', 'Terminal columns')
-        .action(async (id, opts) => {
-        const params = {};
-        if (opts.rows)
-            params.rows = parseInt(opts.rows, 10);
-        if (opts.cols)
-            params.cols = parseInt(opts.cols, 10);
-        const res = await ptyRequest('resize', id, params);
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        console.log(`${res.cols}x${res.rows}`);
-    });
-    const stopCmd = pty
-        .command('stop <id>')
-        .description('Stop a PTY session and clean up. The session ID becomes invalid.');
-    setHelpSections(stopCmd, {
-        examples: `
-      # Stop a session by ID
-      agents pty stop $SID
-    `,
-    });
-    stopCmd.action(async (id) => {
-        const res = await ptyRequest('stop', id);
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-    });
-    // --- Session listing ---
-    const listCmd = pty
-        .command('list')
-        .description('List all active PTY sessions (running or idle).')
-        .option('--json', 'Output as JSON');
-    setHelpSections(listCmd, {
-        examples: `
-      # List all active sessions
-      agents pty list
-    `,
-    });
-    listCmd.action(async (opts) => {
-        const res = await ptyRequest('list');
-        if (!res.ok) {
-            console.error(chalk.red(res.error));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(res.sessions));
-            return;
-        }
-        if (res.sessions.length === 0) {
-            console.log(chalk.gray('No active PTY sessions'));
-            return;
-        }
-        for (const s of res.sessions) {
-            const age = formatAge(Date.now() - s.started_at);
-            const status = s.exited
-                ? chalk.red(`exited (${s.exit_code})`)
-                : s.app_active
-                    ? chalk.yellow(`running: ${s.active_command}`)
-                    : chalk.green('idle');
-            console.log(`  ${chalk.bold(s.id)}  pid=${s.pid}  ${s.shell}  ${s.cols}x${s.rows}  ${age}  ${status}`);
-            console.log(`    ${chalk.gray(s.cwd)}`);
-        }
-    });
-    // --- Server management ---
-    const serverCmd = pty
-        .command('server')
-        .description('Manage the PTY sidecar server (auto-starts on first use, usually you do not need this).');
-    serverCmd
-        .command('start')
-        .description('Start the PTY server manually (auto-starts on first pty command anyway).')
-        .action(async () => {
-        if (isPtyServerRunning()) {
-            const pidPath = getPtyPidPath();
-            const pid = fs.existsSync(pidPath) ? fs.readFileSync(pidPath, 'utf-8').trim() : '?';
-            console.log(chalk.yellow(`PTY server already running (PID: ${pid})`));
-            return;
-        }
-        // Use ptyRequest which auto-starts the server
-        const res = await ptyRequest('ping');
-        if (res.ok) {
-            console.log(chalk.green(`PTY server started (PID: ${res.pid})`));
-        }
-        else {
-            console.error(chalk.red('Failed to start PTY server'));
-            process.exit(1);
-        }
-    });
-    serverCmd
-        .command('stop')
-        .description('Stop the PTY server and kill all active sessions.')
-        .action(async () => {
-        if (!isPtyServerRunning()) {
-            console.log(chalk.yellow('PTY server is not running'));
-            return;
-        }
-        const pidPath = getPtyPidPath();
-        try {
-            const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
-            process.kill(pid, 'SIGTERM');
-            console.log(chalk.green('PTY server stopped'));
-        }
-        catch {
-            console.error(chalk.red('Failed to stop PTY server'));
-            process.exit(1);
-        }
-    });
-    serverCmd
-        .command('status')
-        .description('Check if the PTY server is running and how many sessions are active.')
-        .action(async () => {
-        const running = isPtyServerRunning();
-        console.log(`  Status: ${running ? chalk.green('running') : chalk.gray('stopped')}`);
-        if (running) {
-            try {
-                const res = await ptyRequest('ping');
-                if (res.ok) {
-                    console.log(`  PID:      ${res.pid}`);
-                    console.log(`  Sessions: ${res.sessions}`);
-                }
-            }
-            catch { }
-        }
-        const logPath = getPtyLogPath();
-        console.log(`  Log:    ${logPath}`);
-    });
-    // Internal: run server in foreground (spawned by auto-start)
-    pty
-        .command('_server', { hidden: true })
-        .description('Run PTY server (internal)')
-        .action(async () => {
-        await runPtyServer();
-    });
-}
-/** Format a millisecond duration as a compact human-readable string (e.g. "5m", "2h 30m"). */
-function formatAge(ms) {
-    const secs = Math.floor(ms / 1000);
-    if (secs < 60)
-        return `${secs}s`;
-    const mins = Math.floor(secs / 60);
-    if (mins < 60)
-        return `${mins}m`;
-    const hours = Math.floor(mins / 60);
-    return `${hours}h ${mins % 60}m`;
-}

package/dist/commands/reconnect.d.ts

@@ -1,46 +0,0 @@
-/**
- * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
- * link dropped.
- *
- * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
- * pane over its own bounded backoff on a transient blink. This is the MANUAL
- * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
- * that closed with the dead ssh client. One verb that always tries hardest to put
- * you back into that agent: attach the live pane if it still exists, else resume
- * the session; live pane > resumed copy > a clear message about what was lost.
- *
- * It delegates to `focus`, which already does exactly attach-else-resume for a
- * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
- * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
- * with no id, targeting the MOST RECENT session in this shell's directory — the one
- * that most likely just dropped — instead of opening the full fleet picker.
- */
-import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
-/**
- * The recency signal a no-id reconnect targets: last activity if the scan
- * computed one, else the creation time. A row with neither parseable sorts last.
- * Pure so target selection is unit-tested without the scanner.
- */
-export declare function sessionRecency(s: Pick<SessionMeta, 'lastActivity' | 'timestamp'>): number;
-/**
- * Pick the session to reconnect when the user gave no id: the most recently
- * active one in scope — the terminal that most likely just dropped. Pure; returns
- * undefined for an empty scope so the caller can print guidance.
- */
-export declare function pickMostRecentSession(sessions: SessionMeta[]): SessionMeta | undefined;
-/**
- * Resolve the no-id target: prefer the most recent session started from THIS
- * directory (the shell the user is reconnecting from), falling back to the most
- * recent session anywhere when the current directory has none. Best-effort — a
- * discovery failure yields undefined, never throws. Injectable `discover` keeps
- * the two-step scope preference testable without touching the real scanner.
- */
-export declare function resolveRecentTarget(cwd: string, discover?: (opts: {
-    cwd?: string;
-    all?: boolean;
-    since?: string;
-    limit?: number;
-}) => Promise<SessionMeta[]>): Promise<SessionMeta | undefined>;
-export declare function reconnectAction(id: string | undefined): Promise<void>;
-export declare function registerReconnectCommand(program: Command): void;

package/dist/commands/reconnect.js

@@ -1,115 +0,0 @@
-/**
- * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
- * link dropped.
- *
- * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
- * pane over its own bounded backoff on a transient blink. This is the MANUAL
- * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
- * that closed with the dead ssh client. One verb that always tries hardest to put
- * you back into that agent: attach the live pane if it still exists, else resume
- * the session; live pane > resumed copy > a clear message about what was lost.
- *
- * It delegates to `focus`, which already does exactly attach-else-resume for a
- * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
- * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
- * with no id, targeting the MOST RECENT session in this shell's directory — the one
- * that most likely just dropped — instead of opening the full fleet picker.
- */
-import chalk from 'chalk';
-import { focusAction } from './focus.js';
-import { discoverSessions } from '../lib/session/discover.js';
-import { setHelpSections } from '../lib/help.js';
-/**
- * The recency signal a no-id reconnect targets: last activity if the scan
- * computed one, else the creation time. A row with neither parseable sorts last.
- * Pure so target selection is unit-tested without the scanner.
- */
-export function sessionRecency(s) {
-    const t = Date.parse(s.lastActivity ?? s.timestamp ?? '');
-    return Number.isFinite(t) ? t : Number.NEGATIVE_INFINITY;
-}
-/**
- * Pick the session to reconnect when the user gave no id: the most recently
- * active one in scope — the terminal that most likely just dropped. Pure; returns
- * undefined for an empty scope so the caller can print guidance.
- */
-export function pickMostRecentSession(sessions) {
-    let best;
-    for (const s of sessions) {
-        if (!best || sessionRecency(s) > sessionRecency(best))
-            best = s;
-    }
-    return best;
-}
-/**
- * Resolve the no-id target: prefer the most recent session started from THIS
- * directory (the shell the user is reconnecting from), falling back to the most
- * recent session anywhere when the current directory has none. Best-effort — a
- * discovery failure yields undefined, never throws. Injectable `discover` keeps
- * the two-step scope preference testable without touching the real scanner.
- */
-export async function resolveRecentTarget(cwd, discover = discoverSessions) {
-    try {
-        const here = await discover({ cwd, since: '7d', limit: 200 });
-        const local = pickMostRecentSession(here);
-        if (local)
-            return local;
-        const any = await discover({ all: true, since: '7d', limit: 200 });
-        return pickMostRecentSession(any);
-    }
-    catch {
-        return undefined;
-    }
-}
-export async function reconnectAction(id) {
-    if (id) {
-        // focus already attaches a live pane or recovers a dropped one for a resolved
-        // id — on the origin device for a remote session. Reconnect is that path with
-        // a recovery-first name; no reason to duplicate the resolution/attach logic.
-        await focusAction(id, {});
-        return;
-    }
-    const recent = await resolveRecentTarget(process.cwd());
-    if (!recent) {
-        console.log(chalk.gray('No recent session to reconnect from here.'));
-        console.log(chalk.gray('  reconnect a specific one:  agents reconnect <session-id>'));
-        console.log(chalk.gray('  or pick from the fleet:    agents sessions'));
-        return;
-    }
-    const where = recent.machine ? ` on ${recent.machine}` : '';
-    console.log(chalk.gray(`Reconnecting ${recent.shortId}${where} (most recent here)…`));
-    await focusAction(recent.id, {});
-}
-export function registerReconnectCommand(program) {
-    // Deprecated: superseded by `agents sessions resume`, which does the same
-    // attach-else-recover and additionally takes a tmux alias. Hidden + warned +
-    // functional for one release. Bare `reconnect` targeted the most recent
-    // session in this directory; that default now lives on `resume`'s picker.
-    const cmd = program
-        .command('reconnect', { hidden: true })
-        .argument('[session-id]', 'Session id/prefix to reconnect (default: the most recent session started here)')
-        .description('Deprecated — use `agents sessions resume` instead.')
-        .action(async (id) => {
-        console.warn(chalk.yellow('`agents reconnect` is deprecated — use `agents sessions resume` instead:'));
-        console.warn(chalk.gray(`  agents sessions resume${id ? ` ${id}` : ''}`));
-        await reconnectAction(id);
-    });
-    setHelpSections(cmd, {
-        examples: `
-      # Reconnect the session that just dropped in this shell (most recent here)
-      agents reconnect
-
-      # Reconnect one specific agent terminal by id/prefix
-      agents reconnect 74b13b0b
-
-      # Same, spelled under the sessions group
-      agents sessions reconnect 74b13b0b
-    `,
-        notes: `
-      - Best-effort recovery: a living remote tmux pane is JOINED (a second client, no fork); a dropped one is RESUMED on its origin device (a copy if it was mid-run, a /continue if idle).
-      - With no id, targets the most recent session started from this directory (the terminal that most likely just dropped), not the full fleet picker. Falls back to the most recent session anywhere when this directory has none.
-      - This is the manual companion to the automatic reconnect that runs during a live 'agents run --device <box>' when the network blinks; use it after that gave up or the terminal tab closed.
-      - Deprecated: use 'agents sessions resume' — it attaches a live pane, foregrounds a headless session, or recovers an ended one.
-    `,
-    });
-}