From 59e6ab2bf51b8f61a79aee67cf0c0105c8eb1ea8 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 28 Jan 2026 23:13:38 +0700 Subject: [PATCH] feat(cli): add agent ps command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements the `paseo agent ps` command for listing agents: - Lists running agents by default - `-a, --all` flag to include archived agents - `--status ` filter by agent status - `--cwd ` filter by working directory - Supports all output formats (table, json, yaml, quiet) - Graceful error handling when daemon not running Output format: AGENT ID NAME PROVIDER STATUS CWD CREATED a1b2c3d 🎭 Test fixer claude running ~/dev/paseo 2 minutes ago Phase 3 of CLI implementation (TDD checklist 3.1-3.5) --- packages/cli/src/cli.ts | 12 +- packages/cli/src/commands/agent/index.ts | 18 +++ packages/cli/src/commands/agent/ps.ts | 159 +++++++++++++++++++++++ packages/cli/tests/04-agent-ps.test.mts | 147 +++++++++++++++++++++ 4 files changed, 328 insertions(+), 8 deletions(-) create mode 100644 packages/cli/src/commands/agent/index.ts create mode 100644 packages/cli/src/commands/agent/ps.ts create mode 100644 packages/cli/tests/04-agent-ps.test.mts diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 6c9a0c6d2..23b12c30d 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -1,4 +1,5 @@ import { Command } from 'commander' +import { createAgentCommand } from './commands/agent/index.js' import { createDaemonCommand } from './commands/daemon/index.js' const VERSION = '0.1.0' @@ -16,15 +17,10 @@ export function createCli(): Command { .option('--no-headers', 'omit table headers') .option('--no-color', 'disable colored output') - // Placeholder subcommands - program - .command('agent') - .description('Manage agents') - .action(() => { - console.log('agent command (not yet implemented)') - }) + // Agent commands + program.addCommand(createAgentCommand()) - // Real daemon command + // Daemon commands program.addCommand(createDaemonCommand()) program diff --git a/packages/cli/src/commands/agent/index.ts b/packages/cli/src/commands/agent/index.ts new file mode 100644 index 000000000..ae116d097 --- /dev/null +++ b/packages/cli/src/commands/agent/index.ts @@ -0,0 +1,18 @@ +import { Command } from 'commander' +import { runPsCommand } from './ps.js' +import { withOutput } from '../../output/index.js' + +export function createAgentCommand(): Command { + const agent = new Command('agent').description('Manage agents') + + agent + .command('ps') + .description('List agents') + .option('-a, --all', 'include archived agents') + .option('--status ', 'filter by status (running, idle, error)') + .option('--cwd ', 'filter by working directory') + .option('--host ', 'Daemon host:port (default: localhost:6767)') + .action(withOutput(runPsCommand)) + + return agent +} diff --git a/packages/cli/src/commands/agent/ps.ts b/packages/cli/src/commands/agent/ps.ts new file mode 100644 index 000000000..83018dc61 --- /dev/null +++ b/packages/cli/src/commands/agent/ps.ts @@ -0,0 +1,159 @@ +import type { Command } from 'commander' +import { connectToDaemon, getDaemonHost } from '../../utils/client.js' +import type { CommandOptions, ListResult, OutputSchema, CommandError } from '../../output/index.js' + +/** Minimal agent snapshot type (from daemon client) */ +interface AgentSnapshot { + id: string + provider: string + cwd: string + createdAt: string + status: string + title: string | null + archivedAt?: string | null +} + +/** Agent list item for display */ +export interface AgentListItem { + id: string + shortId: string + name: string + provider: string + status: string + cwd: string + created: string +} + +/** Helper to get relative time string */ +function relativeTime(date: Date | string): string { + const now = Date.now() + const then = new Date(date).getTime() + const seconds = Math.floor((now - then) / 1000) + + if (seconds < 60) return 'just now' + if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes ago` + if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago` + return `${Math.floor(seconds / 86400)} days ago` +} + +/** Shorten home directory in path */ +function shortenPath(path: string): string { + const home = process.env.HOME + if (home && path.startsWith(home)) { + return '~' + path.slice(home.length) + } + return path +} + +/** Schema for agent ps output */ +export const agentPsSchema: OutputSchema = { + idField: 'shortId', + columns: [ + { header: 'AGENT ID', field: 'shortId', width: 12 }, + { header: 'NAME', field: 'name', width: 20 }, + { header: 'PROVIDER', field: 'provider', width: 10 }, + { + header: 'STATUS', + field: 'status', + width: 10, + color: (value) => { + if (value === 'running') return 'green' + if (value === 'idle') return 'yellow' + if (value === 'error') return 'red' + return undefined + }, + }, + { header: 'CWD', field: 'cwd', width: 30 }, + { header: 'CREATED', field: 'created', width: 15 }, + ], +} + +/** Transform agent snapshot to AgentListItem */ +function toListItem(agent: AgentSnapshot): AgentListItem { + return { + id: agent.id, + shortId: agent.id.slice(0, 7), + name: agent.title ?? '-', + provider: agent.provider, + status: agent.status, + cwd: shortenPath(agent.cwd), + created: relativeTime(agent.createdAt), + } +} + +export type AgentPsResult = ListResult + +export interface AgentPsOptions extends CommandOptions { + all?: boolean + status?: string + cwd?: string +} + +export async function runPsCommand( + options: AgentPsOptions, + _command: Command +): Promise { + const host = getDaemonHost({ host: options.host as string | undefined }) + + let client + try { + client = await connectToDaemon({ host: options.host as string | undefined }) + } catch (err) { + const message = err instanceof Error ? err.message : String(err) + const error: CommandError = { + code: 'DAEMON_NOT_RUNNING', + message: `Cannot connect to daemon at ${host}: ${message}`, + details: 'Start the daemon with: paseo daemon start', + } + throw error + } + + try { + // Request session state to get agent information + client.requestSessionState() + + // Wait a moment for the session state to be populated + await new Promise((resolve) => setTimeout(resolve, 500)) + + let agents = client.listAgents() + + // Filter out archived agents unless -a flag is set + if (!options.all) { + agents = agents.filter((a) => !a.archivedAt) + } + + // Filter by status if specified + if (options.status) { + agents = agents.filter((a) => a.status === options.status) + } + + // Filter by cwd if specified + if (options.cwd) { + const filterCwd = options.cwd + agents = agents.filter((a) => { + // Normalize paths for comparison + const agentCwd = a.cwd.replace(/\/$/, '') + const targetCwd = filterCwd.replace(/\/$/, '') + return agentCwd === targetCwd || agentCwd.startsWith(targetCwd + '/') + }) + } + + await client.close() + + const items = agents.map(toListItem) + + return { + type: 'list', + data: items, + schema: agentPsSchema, + } + } catch (err) { + await client.close().catch(() => {}) + const message = err instanceof Error ? err.message : String(err) + const error: CommandError = { + code: 'LIST_AGENTS_FAILED', + message: `Failed to list agents: ${message}`, + } + throw error + } +} diff --git a/packages/cli/tests/04-agent-ps.test.mts b/packages/cli/tests/04-agent-ps.test.mts new file mode 100644 index 000000000..b37ec0629 --- /dev/null +++ b/packages/cli/tests/04-agent-ps.test.mts @@ -0,0 +1,147 @@ +#!/usr/bin/env npx tsx + +/** + * Phase 3: Agent PS Command Tests + * + * Tests the agent ps command - listing agents. + * Since daemon may not be running, we test both: + * - Help and argument parsing + * - Graceful error handling when daemon not running + * - JSON output format + * + * Tests: + * - agent --help shows subcommands + * - agent ps --help shows options + * - agent ps returns empty list or error when no daemon + * - agent ps --format json returns valid JSON (or error) + * - agent ps -a flag is accepted + * - agent ps --status flag is accepted + * - agent ps --cwd flag is accepted + */ + +import assert from 'node:assert' +import { $ } from 'zx' +import { mkdtemp, rm } from 'fs/promises' +import { tmpdir } from 'os' +import { join } from 'path' + +$.verbose = false + +console.log('=== Agent PS Command Tests ===\n') + +// Get random port that's definitely not in use (never 6767) +const port = 10000 + Math.floor(Math.random() * 50000) +const paseoHome = await mkdtemp(join(tmpdir(), 'paseo-test-home-')) + +try { + // Test 1: agent --help shows subcommands + { + console.log('Test 1: agent --help shows subcommands') + const result = await $`npx paseo agent --help`.nothrow() + assert.strictEqual(result.exitCode, 0, 'agent --help should exit 0') + assert(result.stdout.includes('ps'), 'help should mention ps subcommand') + console.log('✓ agent --help shows subcommands\n') + } + + // Test 2: agent ps --help shows options + { + console.log('Test 2: agent ps --help shows options') + const result = await $`npx paseo agent ps --help`.nothrow() + assert.strictEqual(result.exitCode, 0, 'agent ps --help should exit 0') + assert(result.stdout.includes('-a'), 'help should mention -a flag') + assert(result.stdout.includes('--all'), 'help should mention --all flag') + assert(result.stdout.includes('--status'), 'help should mention --status option') + assert(result.stdout.includes('--cwd'), 'help should mention --cwd option') + assert(result.stdout.includes('--host'), 'help should mention --host option') + console.log('✓ agent ps --help shows options\n') + } + + // Test 3: agent ps returns error when no daemon running + { + console.log('Test 3: agent ps handles daemon not running') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps`.nothrow() + // Should fail because daemon not running + assert.notStrictEqual(result.exitCode, 0, 'should fail when daemon not running') + const output = result.stdout + result.stderr + const hasError = + output.toLowerCase().includes('daemon') || + output.toLowerCase().includes('connect') || + output.toLowerCase().includes('cannot') + assert(hasError, 'error message should mention connection issue') + console.log('✓ agent ps handles daemon not running\n') + } + + // Test 4: agent ps --format json returns valid JSON error + { + console.log('Test 4: agent ps --format json handles errors') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --format json`.nothrow() + // Should still fail (daemon not running) + assert.notStrictEqual(result.exitCode, 0, 'should fail when daemon not running') + // But output should be valid JSON if present + const output = result.stdout.trim() + if (output.length > 0) { + try { + JSON.parse(output) + console.log('✓ agent ps --format json outputs valid JSON error\n') + } catch { + // Empty or stderr-only output is acceptable + console.log('✓ agent ps --format json handled error (output may be in stderr)\n') + } + } else { + console.log('✓ agent ps --format json handled error gracefully\n') + } + } + + // Test 5: agent ps -a flag is accepted + { + console.log('Test 5: agent ps -a flag is accepted') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps -a`.nothrow() + // Will fail due to no daemon, but flag should be parsed without error + // (no "unknown option" error) + const output = result.stdout + result.stderr + assert(!output.includes('unknown option'), 'should accept -a flag') + assert(!output.includes('error: option'), 'should not have option parsing error') + console.log('✓ agent ps -a flag is accepted\n') + } + + // Test 6: agent ps --status flag is accepted + { + console.log('Test 6: agent ps --status flag is accepted') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --status running`.nothrow() + const output = result.stdout + result.stderr + assert(!output.includes('unknown option'), 'should accept --status flag') + assert(!output.includes('error: option'), 'should not have option parsing error') + console.log('✓ agent ps --status flag is accepted\n') + } + + // Test 7: agent ps --cwd flag is accepted + { + console.log('Test 7: agent ps --cwd flag is accepted') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --cwd /tmp`.nothrow() + const output = result.stdout + result.stderr + assert(!output.includes('unknown option'), 'should accept --cwd flag') + assert(!output.includes('error: option'), 'should not have option parsing error') + console.log('✓ agent ps --cwd flag is accepted\n') + } + + // Test 8: -q (quiet) flag is accepted globally + { + console.log('Test 8: -q (quiet) flag is accepted') + const result = + await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo -q agent ps`.nothrow() + const output = result.stdout + result.stderr + assert(!output.includes('unknown option'), 'should accept -q flag') + assert(!output.includes('error: option'), 'should not have option parsing error') + console.log('✓ -q (quiet) flag is accepted\n') + } +} finally { + // Clean up temp directory + await rm(paseoHome, { recursive: true, force: true }) +} + +console.log('=== All agent ps tests passed ===')