Add standalone package for agent manager

docs/ai/design/feature-agent-manager.md

@@ -0,0 +1,197 @@
+---
+phase: design
+title: "Agent Manager Package - Design"
+feature: agent-manager
+description: Architecture and design for the @ai-devkit/agent-manager package
+---
+
+# Design: @ai-devkit/agent-manager Package
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    subgraph "@ai-devkit/agent-manager"
+        AM[AgentManager] -->|registers| AA[AgentAdapter Interface]
+        AA -->|implemented by| CCA[ClaudeCodeAdapter]
+        AA -->|implemented by| FutureAdapter["Future Adapters..."]
+
+        CCA -->|uses| PU[Process Utils]
+        CCA -->|uses| FU[File Utils]
+
+        TFM[TerminalFocusManager] -->|uses| PU
+
+        Types[Types & Enums] -->|consumed by| AM
+        Types -->|consumed by| CCA
+        Types -->|consumed by| TFM
+    end
+
+    subgraph "CLI Package (consumer)"
+        CMD[agent command] -->|imports| AM
+        CMD -->|imports| CCA
+        CMD -->|imports| TFM
+        CMD -->|imports| Types
+    end
+```
+
+### Package Directory Structure
+
+```
+packages/agent-manager/
+├── src/
+│   ├── index.ts                    # Public API barrel export
+│   ├── AgentManager.ts             # Core orchestrator
+│   ├── adapters/
+│   │   ├── AgentAdapter.ts         # Interface, types, enums
+│   │   ├── ClaudeCodeAdapter.ts    # Claude Code detection
+│   │   └── index.ts                # Adapter barrel export
+│   ├── terminal/
+│   │   ├── TerminalFocusManager.ts # Terminal focus (macOS)
+│   │   └── index.ts                # Terminal barrel export
+│   └── utils/
+│       ├── process.ts              # Process detection utilities
+│       ├── file.ts                 # File reading utilities
+│       └── index.ts                # Utils barrel export
+├── src/__tests__/
+│   ├── AgentManager.test.ts
+│   └── adapters/
+│       └── ClaudeCodeAdapter.test.ts
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── project.json
+└── .eslintrc.json
+```
+
+## Data Models
+
+Types are adapted for a data-first package contract:
+
+- **AgentType**: `'claude' | 'gemini_cli' | 'codex' | 'other'`
+- **AgentStatus**: Enum (`RUNNING`, `WAITING`, `IDLE`, `UNKNOWN`)
+- **AgentInfo**: Full agent information (name, type, status, pid, projectPath, sessionId, slug, lastActive, etc.)
+- **ProcessInfo**: `{ pid, command, cwd, tty }`
+- **AgentAdapter**: Interface with `type`, `detectAgents()`, `canHandle()`
+- **TerminalType**: Enum (`TMUX`, `ITERM2`, `TERMINAL_APP`, `UNKNOWN`)
+- **TerminalLocation**: `{ type: TerminalType, identifier, tty }` (from TerminalFocusManager)
+
+## API Design
+
+### Public Exports (`index.ts`)
+
+```typescript
+// Core
+export { AgentManager } from './AgentManager';
+
+// Adapters
+export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter';
+export type { AgentAdapter } from './adapters/AgentAdapter';
+export { AgentStatus } from './adapters/AgentAdapter';
+export type { AgentType, AgentInfo, ProcessInfo } from './adapters/AgentAdapter';
+
+// Terminal
+export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager';
+export type { TerminalLocation } from './terminal/TerminalFocusManager';
+
+// Utilities
+export { listProcesses, getProcessCwd, getProcessTty, isProcessRunning, getProcessInfo } from './utils/process';
+export type { ListProcessesOptions } from './utils/process';
+export { readLastLines, readJsonLines, fileExists, readJson } from './utils/file';
+```
+
+### Usage Example
+
+```typescript
+import { AgentManager, ClaudeCodeAdapter } from '@ai-devkit/agent-manager';
+
+const manager = new AgentManager();
+manager.registerAdapter(new ClaudeCodeAdapter());
+
+const agents = await manager.listAgents();
+agents.forEach(agent => {
+  console.log(`${agent.name}: ${agent.status}`);
+});
+```
+
+### Migration Notes
+
+- `AgentType` values are now normalized codes (`claude`, `gemini_cli`, `codex`, `other`)
+- `AgentInfo` no longer includes UI/display fields (`statusDisplay`, `lastActiveDisplay`)
+- `STATUS_CONFIG` / `StatusConfig` were removed; consumers should map presentation in their own layer
+
+## Component Breakdown
+
+### 1. AgentManager (core orchestrator)
+- Adapter registration/unregistration
+- Agent listing with parallel adapter queries
+- Agent resolution (exact/partial name matching)
+- Status-based sorting
+- **Extracted from**: `packages/cli/src/lib/AgentManager.ts`
+- **Changes**: None — direct copy
+
+### 2. AgentAdapter + Types (interface layer)
+- Interface contract for adapters
+- Type definitions and enums
+- Normalized agent type codes for machine-friendly integrations
+- **Extracted from**: `packages/cli/src/lib/adapters/AgentAdapter.ts`
+- **Changes**: Agent type literals normalized; display-oriented fields removed from core model
+
+### 3. ClaudeCodeAdapter (concrete adapter)
+- Claude Code process detection via `ps aux`
+- Session file reading from `~/.claude/projects/`
+- Status determination from JSONL entries
+- History-based summary extraction
+- **Extracted from**: `packages/cli/src/lib/adapters/ClaudeCodeAdapter.ts`
+- **Changes**: Import paths updated to use local `utils/` instead of `../../util/`
+
+### 4. TerminalFocusManager (terminal control)
+- Terminal emulator detection (tmux, iTerm2, Terminal.app)
+- Terminal window/pane focusing
+- macOS-specific AppleScript integration
+- **Extracted from**: `packages/cli/src/lib/TerminalFocusManager.ts`
+- **Changes**: Import paths updated to use local `utils/process`
+
+### 5. Process Utilities
+- `listProcesses()` — system process listing with filtering
+- `getProcessCwd()` — process working directory lookup
+- `getProcessTty()` — process TTY device lookup
+- `isProcessRunning()` — process existence check
+- `getProcessInfo()` — detailed single-process info
+- **Extracted from**: `packages/cli/src/util/process.ts`
+- **Changes**: `ProcessInfo` type import updated (now from `../adapters/AgentAdapter`)
+
+### 6. File Utilities
+- `readLastLines()` — efficient last-N-lines reading
+- `readJsonLines()` — JSONL file parsing
+- `fileExists()` — file existence check
+- `readJson()` — safe JSON file parsing
+- **Extracted from**: `packages/cli/src/util/file.ts`
+- **Changes**: None — direct copy
+
+## Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Package name | `@ai-devkit/agent-manager` | Consistent with `@ai-devkit/memory` naming |
+| Build system | `tsc` (not SWC) | Simpler setup; no special transforms needed; consistent with CLI package |
+| Runtime deps | Zero | Only Node.js built-ins used; keeps package lightweight |
+| Include TerminalFocusManager | Yes, as separate module | Useful for consumers; closely related to agent management |
+| Include utilities | Yes, within package | They're tightly coupled to adapter implementation; not general-purpose enough for a separate package |
+| Test framework | Jest with ts-jest | Matches existing monorepo conventions |
+
+## Non-Functional Requirements
+
+### Performance
+- Process listing uses `ps aux` (single exec, ~50ms typical)
+- Session file reading limited to last 100 lines for large JSONL files
+- Adapter queries run in parallel via `Promise.all`
+
+### Platform Support
+- Process detection: macOS and Linux (uses `ps aux`, `lsof`, `pwdx`)
+- Terminal focus: macOS only (AppleScript for iTerm2/Terminal.app, tmux universal)
+
+### Security
+- No external network calls
+- Reads only from `~/.claude/` directory (user-owned)
+- Process inspection uses standard OS tools
+- No secrets or credentials handled

docs/ai/implementation/feature-agent-manager.md

@@ -0,0 +1,175 @@
+---
+phase: implementation
+title: "Agent Manager Package - Implementation Guide"
+feature: agent-manager
+description: Technical implementation notes for the @ai-devkit/agent-manager package
+---
+
+# Implementation Guide: @ai-devkit/agent-manager Package
+
+## Development Setup
+
+### Prerequisites
+- Node.js >= 16.0.0
+- npm (workspaces enabled in root)
+- TypeScript 5.3+
+
+### Setup Steps
+1. Package directory created at `packages/agent-manager/`
+2. Run `npm install` from monorepo root to link workspace
+3. Build with `npm run build` from `packages/agent-manager/`
+
+## Code Structure
+
+### Directory Organization
+```
+src/
+├── index.ts                    # Main barrel export
+├── AgentManager.ts             # Core orchestrator class
+├── adapters/
+│   ├── index.ts                # Adapter barrel
+│   ├── AgentAdapter.ts         # Interface + types + enums
+│   └── ClaudeCodeAdapter.ts    # Claude Code detection
+├── terminal/
+│   ├── index.ts                # Terminal barrel
+│   └── TerminalFocusManager.ts # macOS terminal focus
+└── utils/
+    ├── index.ts                # Utils barrel
+    ├── process.ts              # Process detection
+    └── file.ts                 # File reading helpers
+```
+
+### Import Path Mapping (CLI → agent-manager)
+| CLI Path | Agent Manager Path |
+|----------|-------------------|
+| `src/lib/AgentManager.ts` | `src/AgentManager.ts` |
+| `src/lib/adapters/AgentAdapter.ts` | `src/adapters/AgentAdapter.ts` |
+| `src/lib/adapters/ClaudeCodeAdapter.ts` | `src/adapters/ClaudeCodeAdapter.ts` |
+| `src/lib/TerminalFocusManager.ts` | `src/terminal/TerminalFocusManager.ts` |
+| `src/util/process.ts` | `src/utils/process.ts` |
+| `src/util/file.ts` | `src/utils/file.ts` |
+
+### Import Changes Required
+- `ClaudeCodeAdapter.ts`: `../../util/process` → `../utils/process`, `../../util/file` → `../utils/file`
+- `process.ts`: `../lib/adapters/AgentAdapter` → `../adapters/AgentAdapter`
+- `TerminalFocusManager.ts`: `../util/process` → `../utils/process`
+
+## Patterns & Best Practices
+
+- **Adapter pattern**: All agent detection goes through `AgentAdapter` interface
+- **Barrel exports**: Each directory has an `index.ts` for clean imports
+- **Zero dependencies**: Only Node.js built-ins (fs, path, child_process, util)
+- **Graceful degradation**: Adapter failures don't crash the system — partial results returned
+
+## Error Handling
+
+- AgentManager catches adapter errors individually, logs warnings, returns partial results
+- File utilities return empty arrays/null on read failures
+- Process utilities return empty results when `ps`/`lsof` commands fail
+- TerminalFocusManager returns `false`/`null` when terminal can't be found or focused
+
+## Implementation Status
+
+Completed on February 25, 2026 in worktree `feature-agent-manager`.
+
+- Scaffolded `packages/agent-manager/` with `package.json`, `tsconfig.json`, `project.json`, `jest.config.js`, `.eslintrc.json`
+- Extracted source files from CLI package into:
+  - `src/AgentManager.ts`
+  - `src/adapters/AgentAdapter.ts`
+  - `src/adapters/ClaudeCodeAdapter.ts`
+  - `src/terminal/TerminalFocusManager.ts`
+  - `src/utils/process.ts`
+  - `src/utils/file.ts`
+- Applied import-path updates defined in design/planning docs
+- Added barrel exports:
+  - `src/index.ts`
+  - `src/adapters/index.ts`
+  - `src/terminal/index.ts`
+  - `src/utils/index.ts`
+- Extracted and fixed test imports for:
+  - `src/__tests__/AgentManager.test.ts`
+  - `src/__tests__/adapters/ClaudeCodeAdapter.test.ts`
+
+Validation:
+- `npm run lint` passes
+- `npm run typecheck` passes
+- `npm run build` passes
+- `npm run test` passes (38 tests)
+
+Data-model refinements (February 25, 2026):
+- Normalized `AgentType` to code-style values: `claude`, `gemini_cli`, `codex`, `other`
+- Removed display-oriented contract elements from package API:
+  - Removed `STATUS_CONFIG` and `StatusConfig`
+  - Removed `AgentInfo.statusDisplay`
+  - Removed `AgentInfo.lastActiveDisplay`
+- Updated `ClaudeCodeAdapter` to return data-only fields (`status`, `lastActive`, `summary`) without UI formatting
+- Replaced hardcoded string literals with enums where appropriate:
+  - Added `TerminalType` enum for terminal location/focus flow
+  - Added `SessionEntryType` enum in `ClaudeCodeAdapter` status logic
+
+## Phase 6 Check Implementation (February 25, 2026)
+
+### Alignment Summary
+
+- Overall status: **Mostly aligned**
+- Requirements/design coverage: package scaffold, extracted components, API surface, and validations are implemented as specified
+- Backward-compatibility non-goal respected: CLI behavior/source was not modified in this feature branch
+
+### File-by-File Verification
+
+- `packages/agent-manager/package.json`
+  - Matches package naming/version/scripts/engine constraints from requirements
+  - Uses zero runtime dependencies (only devDependencies)
+- `packages/agent-manager/tsconfig.json`, `project.json`, `jest.config.js`, `.eslintrc.json`
+  - Conform to monorepo conventions and planned targets (build/test/lint/typecheck)
+- `packages/agent-manager/src/AgentManager.ts`
+  - Adapter orchestration and status-based sorting match design
+- `packages/agent-manager/src/adapters/AgentAdapter.ts`
+  - Types and interface extracted as designed
+- `packages/agent-manager/src/adapters/ClaudeCodeAdapter.ts`
+  - Core detection/session/status logic extracted with planned import-path updates
+- `packages/agent-manager/src/terminal/TerminalFocusManager.ts`
+  - Terminal focus logic extracted with planned import-path updates
+- `packages/agent-manager/src/utils/process.ts`, `src/utils/file.ts`
+  - Utility extraction and API signatures match design intent
+- `packages/agent-manager/src/index.ts` and barrel files
+  - Public API exports include core classes/types plus terminal and utils as designed
+- `packages/agent-manager/src/__tests__/...`
+  - Test files extracted and passing in package context
+
+### Deviations / Risks
+
+1. **Resolved (February 25, 2026)**: Claude adapter tests now mock process/session/history dependencies and no longer rely on local `~/.claude` state or `ps` availability.
+2. **Resolved (February 25, 2026)**: Explicit `any` warnings in extracted runtime code were removed by tightening adapter and utility generic typings.
+
+### Phase Decision
+
+- No major implementation/design mismatch detected.
+- Proceed to **Phase 8 (Code Review)**.
+
+## Phase 8 Code Review (February 25, 2026)
+
+### Findings
+
+1. **Resolved**: tmux focus command previously used shell interpolation for the target identifier.
+   - Updated `TerminalFocusManager.focusTmuxPane()` to use `execFile('tmux', ['switch-client', '-t', identifier])` to avoid shell command injection paths.
+
+2. **Non-blocking follow-up**: coverage threshold enforcement currently depends on running Jest with coverage enabled.
+   - Suggested project policy: require `npm run test:coverage` (or equivalent) in CI for this package.
+
+### Review Verdict
+
+- No remaining blocking correctness or security issues in `packages/agent-manager`.
+- Feature is ready for commit/PR from a code review perspective.
+
+## Code Review Continuation (February 25, 2026)
+
+### Findings
+
+1. **No new blocking issues** after `AgentType` normalization and display-field removal.
+2. **Compatibility note**: this is an intentional contract change for package consumers (type literals and removed display fields/constants).
+
+### Documentation Updates Applied
+
+- Requirements/design docs updated to describe the data-first API boundary.
+- Added explicit migration notes for callers formatting status/time displays externally.