Add agent open command

Author: codeaholicguy

docs/ai/planning/feature-agent-management.md

@@ -141,60 +141,60 @@ feature: agent-management
 ### Phase 4: Agent Open Command
 
 #### Task 4.1: Create TerminalFocusManager
-**Status**: 🔲 Not Started
-- [ ] Create `packages/cli/src/lib/TerminalFocusManager.ts`
-- [ ] Implement `findTerminal(pid)` to get TTY from process
-- [ ] Implement `focusTerminal(location)` dispatcher
-- [ ] Define `TerminalLocation` interface
-- [ ] Write unit tests
+**Status**: ✅ Completed
+- [x] Create `packages/cli/src/lib/TerminalFocusManager.ts`
+- [x] Implement `findTerminal(pid)` to get TTY from process
+- [x] Implement `focusTerminal(location)` dispatcher
+- [x] Define `TerminalLocation` interface
+- [x] Write unit tests
 
 **Estimated Effort**: 1.5 hours
 
 #### Task 4.2: Implement Tmux Support
-**Status**: 🔲 Not Started
-- [ ] Implement `findTmuxPane(tty)` method
-- [ ] Parse `tmux list-panes` output
-- [ ] Implement focus with `tmux switch-client`
-- [ ] Write unit tests with mock tmux output
+**Status**: ✅ Completed
+- [x] Implement `findTmuxPane(tty)` method
+- [x] Parse `tmux list-panes` output
+- [x] Implement focus with `tmux switch-client`
+- [x] Write unit tests with mock tmux output
 
 **Estimated Effort**: 1.5 hours
 
 #### Task 4.3: Implement iTerm2 Support
-**Status**: 🔲 Not Started
-- [ ] Create AppleScript to enumerate iTerm2 sessions
-- [ ] Match TTY to session
-- [ ] Implement focus with AppleScript window selection
-- [ ] Write unit tests
+**Status**: ✅ Completed
+- [x] Create AppleScript to enumerate iTerm2 sessions
+- [x] Match TTY to session
+- [x] Implement focus with AppleScript window selection
+- [x] Write unit tests
 
 **Estimated Effort**: 1.5 hours
 
 #### Task 4.4: Implement Terminal.app Support
-**Status**: 🔲 Not Started
-- [ ] Create AppleScript to enumerate Terminal.app windows
-- [ ] Match TTY to window/tab
-- [ ] Implement focus with AppleScript activation
-- [ ] Write unit tests
+**Status**: ✅ Completed
+- [x] Create AppleScript to enumerate Terminal.app windows
+- [x] Match TTY to window/tab
+- [x] Implement focus with AppleScript activation
+- [x] Write unit tests
 
 **Estimated Effort**: 1 hour
 
 #### Task 4.5: Implement Agent Name Resolution
-**Status**: 🔲 Not Started
-- [ ] Implement `resolveAgentName(input, agents)` function
-- [ ] Handle exact match (case-insensitive)
-- [ ] Handle unique partial match
-- [ ] Handle ambiguous match with user prompt
-- [ ] Handle no match with available agents list
-- [ ] Write unit tests
+**Status**: ✅ Completed
+- [x] Implement `resolveAgentName(input, agents)` function
+- [x] Handle exact match (case-insensitive)
+- [x] Handle unique partial match
+- [x] Handle ambiguous match with user prompt
+- [x] Handle no match with available agents list
+- [x] Write unit tests
 
 **Estimated Effort**: 1 hour
 
 #### Task 4.6: Create Agent Open Subcommand
-**Status**: 🔲 Not Started
-- [ ] Register `agent open <name>` subcommand
-- [ ] Integrate AgentManager + TerminalFocusManager
-- [ ] Display success/error messages
-- [ ] Handle unfocusable terminals gracefully
-- [ ] Manual testing with different terminal environments
+**Status**: ✅ Completed
+- [x] Register `agent open <name>` subcommand
+- [x] Integrate AgentManager + TerminalFocusManager
+- [x] Display success/error messages
+- [x] Handle unfocusable terminals gracefully
+- [x] Manual testing with different terminal environments
 
 **Estimated Effort**: 1.5 hours
 
@@ -253,11 +253,11 @@ graph LR
 | Phase 1: Foundation | 1.1, 1.2, 1.3 | 5 hours | ✅ Completed |
 | Phase 2: Claude Code Integration | 2.1, 2.2, 2.3, 2.4 | 9 hours | ✅ Completed |
 | Phase 3: CLI Integration (List) | 3.1, 3.2 | 3 hours | ✅ Completed |
-| Phase 4: Agent Open Command | 4.1, 4.2, 4.3, 4.4, 4.5, 4.6 | 8 hours | 🔲 Not Started |
+| Phase 4: Agent Open Command | 4.1, 4.2, 4.3, 4.4, 4.5, 4.6 | 8 hours | ✅ Completed |
 | Phase 5: Testing & Documentation | 5.1, 5.2 | 3 hours | 🔲 Not Started |
 | **Total** | | **28 hours** | |
-| **Completed** | | **17 hours** | 60% Complete |
-| **Remaining** | | **11 hours** | |
+| **Completed** | | **25 hours** | 89% Complete |
+| **Remaining** | | **3 hours** | |
 
 ### Suggested Implementation Order
 1. Task 1.2 (Interface) - Define contracts first

packages/cli/src/__tests__/lib/AgentManager.test.ts

@@ -249,4 +249,62 @@ describe('AgentManager', () => {
             expect(manager.getAdapters()).toEqual([]);
         });
     });
+
+    describe('resolveAgent', () => {
+        it('should return null for empty input or empty agents list', () => {
+            const agent = createMockAgent({ name: 'test-agent' });
+            expect(manager.resolveAgent('', [agent])).toBeNull();
+            expect(manager.resolveAgent('test', [])).toBeNull();
+        });
+
+        it('should resolve exact match (case-insensitive)', () => {
+            const agent = createMockAgent({ name: 'My-Agent' });
+            const agents = [agent, createMockAgent({ name: 'Other' })];
+
+            // Exact match
+            expect(manager.resolveAgent('My-Agent', agents)).toBe(agent);
+            // Case-insensitive
+            expect(manager.resolveAgent('my-agent', agents)).toBe(agent);
+        });
+
+        it('should resolve unique partial match', () => {
+            const agent = createMockAgent({ name: 'ai-devkit' });
+            const agents = [
+                agent,
+                createMockAgent({ name: 'other-project' })
+            ];
+
+            const result = manager.resolveAgent('dev', agents);
+            expect(result).toBe(agent);
+        });
+
+        it('should return array for ambiguous partial match', () => {
+            const agent1 = createMockAgent({ name: 'my-website' });
+            const agent2 = createMockAgent({ name: 'my-app' });
+            const agents = [agent1, agent2, createMockAgent({ name: 'other' })];
+
+            const result = manager.resolveAgent('my', agents);
+
+            expect(Array.isArray(result)).toBe(true);
+            const matches = result as AgentInfo[];
+            expect(matches).toHaveLength(2);
+            expect(matches).toContain(agent1);
+            expect(matches).toContain(agent2);
+        });
+
+        it('should return null for no match', () => {
+            const agents = [createMockAgent({ name: 'ai-devkit' })];
+            expect(manager.resolveAgent('xyz', agents)).toBeNull();
+        });
+
+        it('should prefer exact match over partial matches', () => {
+            // Edge case: "test" matches "test" (exact) and "testing" (partial)
+            // Should return exact "test"
+            const exact = createMockAgent({ name: 'test' });
+            const partial = createMockAgent({ name: 'testing' });
+            const agents = [exact, partial];
+
+            expect(manager.resolveAgent('test', agents)).toBe(exact);
+        });
+    });
 });

packages/cli/src/commands/agent.ts

@@ -1,8 +1,10 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
+import inquirer from 'inquirer';
 import { AgentManager } from '../lib/AgentManager';
 import { ClaudeCodeAdapter } from '../lib/adapters/ClaudeCodeAdapter';
-import { AgentStatus, STATUS_CONFIG } from '../lib/adapters/AgentAdapter';
+import { AgentStatus, STATUS_CONFIG, AgentInfo } from '../lib/adapters/AgentAdapter';
+import { TerminalFocusManager } from '../lib/TerminalFocusManager';
 import { ui } from '../util/terminal-ui';
 
 export function registerAgentCommand(program: Command): void {
@@ -77,4 +79,78 @@ export function registerAgentCommand(program: Command): void {
                 process.exit(1);
             }
         });
+
+    agentCommand
+        .command('open <name>')
+        .description('Focus a running agent terminal')
+        .action(async (name) => {
+            try {
+                const manager = new AgentManager();
+                const focusManager = new TerminalFocusManager();
+
+                manager.registerAdapter(new ClaudeCodeAdapter());
+
+                const agents = await manager.listAgents();
+                if (agents.length === 0) {
+                    ui.error('No running agents found.');
+                    return;
+                }
+
+                const resolved = manager.resolveAgent(name, agents);
+
+                if (!resolved) {
+                    ui.error(`No agent found matching "${name}".`);
+                    ui.info('Available agents:');
+                    agents.forEach(a => console.log(`  - ${a.name}`));
+                    return;
+                }
+
+                let targetAgent = resolved;
+
+                if (Array.isArray(resolved)) {
+                    ui.warning(`Multiple agents match "${name}":`);
+
+                    const { selectedAgent } = await inquirer.prompt([
+                        {
+                            type: 'list',
+                            name: 'selectedAgent',
+                            message: 'Select an agent to open:',
+                            choices: resolved.map(a => ({
+                                name: `${a.name} (${a.statusDisplay}) - ${a.summary}`,
+                                value: a
+                            }))
+                        }
+                    ]);
+                    targetAgent = selectedAgent;
+                }
+
+                // Focus terminal
+                const agent = targetAgent as AgentInfo;
+                if (!agent.pid) {
+                    ui.error(`Cannot focus agent "${agent.name}" (No PID found).`);
+                    return;
+                }
+
+                const spinner = ui.spinner(`Switching focus to ${agent.name}...`);
+                spinner.start();
+
+                const location = await focusManager.findTerminal(agent.pid);
+                if (!location) {
+                    spinner.fail(`Could not find terminal window for agent "${agent.name}" (PID: ${agent.pid}).`);
+                    return;
+                }
+
+                const success = await focusManager.focusTerminal(location);
+
+                if (success) {
+                    spinner.succeed(`Focused ${agent.name}!`);
+                } else {
+                    spinner.fail(`Failed to switch focus to ${agent.name}.`);
+                }
+
+            } catch (error: any) {
+                ui.error(`Failed to open agent: ${error.message}`);
+                process.exit(1);
+            }
+        });
 }

packages/cli/src/lib/AgentManager.ts

@@ -170,4 +170,29 @@ export class AgentManager {
     clear(): void {
         this.adapters.clear();
     }
+
+    /**
+     * Resolve an agent by name (exact or partial match)
+     * 
+     * @param input Name to search for
+     * @param agents List of agents to search within
+     * @returns Matched agent (unique), array of agents (ambiguous), or null (none)
+     */
+    resolveAgent(input: string, agents: AgentInfo[]): AgentInfo | AgentInfo[] | null {
+        if (!input || agents.length === 0) return null;
+
+        const lowerInput = input.toLowerCase();
+
+        // 1. Exact match (case-insensitive)
+        const exactMatch = agents.find(a => a.name.toLowerCase() === lowerInput);
+        if (exactMatch) return exactMatch;
+
+        // 2. Partial match (prefix or contains)
+        const matches = agents.filter(a => a.name.toLowerCase().includes(lowerInput));
+
+        if (matches.length === 1) return matches[0];
+        if (matches.length > 1) return matches;
+
+        return null;
+    }
 }