refactor(agent-manager): normalize agent types and remove display fields

Author: codeaholicguy

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

@@ -65,11 +65,10 @@ packages/agent-manager/
 
 ## Data Models
 
-All types are extracted from the existing `AgentAdapter.ts` without changes:
+Types are adapted for a data-first package contract:
 
-- **AgentType**: `'Claude Code' | 'Gemini CLI' | 'Codex' | 'Other'`
+- **AgentType**: `'claude' | 'gemini_cli' | 'codex' | 'other'`
 - **AgentStatus**: Enum (`RUNNING`, `WAITING`, `IDLE`, `UNKNOWN`)
-- **StatusConfig**: `{ emoji, label, color }`
 - **AgentInfo**: Full agent information (name, type, status, pid, projectPath, sessionId, slug, lastActive, etc.)
 - **ProcessInfo**: `{ pid, command, cwd, tty }`
 - **AgentAdapter**: Interface with `type`, `detectAgents()`, `canHandle()`
@@ -86,8 +85,8 @@ export { AgentManager } from './AgentManager';
 // Adapters
 export { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter';
 export type { AgentAdapter } from './adapters/AgentAdapter';
-export { AgentStatus, STATUS_CONFIG } from './adapters/AgentAdapter';
-export type { AgentType, AgentInfo, ProcessInfo, StatusConfig } from './adapters/AgentAdapter';
+export { AgentStatus } from './adapters/AgentAdapter';
+export type { AgentType, AgentInfo, ProcessInfo } from './adapters/AgentAdapter';
 
 // Terminal
 export { TerminalFocusManager } from './terminal/TerminalFocusManager';
@@ -109,10 +108,16 @@ manager.registerAdapter(new ClaudeCodeAdapter());
 
 const agents = await manager.listAgents();
 agents.forEach(agent => {
-  console.log(`${agent.name}: ${agent.statusDisplay}`);
+  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)
@@ -126,9 +131,9 @@ agents.forEach(agent => {
 ### 2. AgentAdapter + Types (interface layer)
 - Interface contract for adapters
 - Type definitions and enums
-- Status display configuration
+- Normalized agent type codes for machine-friendly integrations
 - **Extracted from**: `packages/cli/src/lib/adapters/AgentAdapter.ts`
-- **Changes**: None — direct copy
+- **Changes**: Agent type literals normalized; display-oriented fields removed from core model
 
 ### 3. ClaudeCodeAdapter (concrete adapter)
 - Claude Code process detection via `ps aux`

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

@@ -91,10 +91,18 @@ Completed on February 25, 2026 in worktree `feature-agent-manager`.
   - `src/__tests__/adapters/ClaudeCodeAdapter.test.ts`
 
 Validation:
-- `npm run lint` passes (warnings only from inherited `any` usage in extracted code)
+- `npm run lint` passes
 - `npm run typecheck` passes
 - `npm run build` passes
-- `npm run test` passes (43 tests)
+- `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
 
 ## Phase 6 Check Implementation (February 25, 2026)
 
@@ -150,3 +158,15 @@ Validation:
 
 - 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.

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

@@ -28,6 +28,7 @@ Agent detection and management code (AgentManager, adapters, process utilities,
 - Improve code quality during extraction (better error handling, consistent patterns)
 - Include TerminalFocusManager as an optional export (terminal focus capability)
 - Maintain backward compatibility — CLI should still function identically after extraction
+- Keep package contracts data-first (machine-friendly enums/codes, no UI display formatting)
 
 ### Non-Goals
 - Modifying the CLI `agent` command behavior or UI (stays in CLI, just re-imports)
@@ -66,6 +67,7 @@ Agent detection and management code (AgentManager, adapters, process utilities,
 - The CLI package will NOT be modified to import from the new package in this iteration
 - TerminalFocusManager is macOS-specific and should be documented as such
 - Process detection utilities (`ps aux`, `lsof`) are Unix/macOS-specific
+- Any consumer-facing formatting (emoji/labels/relative-time strings) is the responsibility of callers, not this package
 
 ## Questions & Open Items
 

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

@@ -29,7 +29,7 @@ description: Testing approach for the @ai-devkit/agent-manager package
 ### ClaudeCodeAdapter (`src/__tests__/adapters/ClaudeCodeAdapter.test.ts`)
 - [x] Adapter type and canHandle()
 - [x] Agent detection (mocked process/session data)
-- [x] Helper methods: truncateSummary(), getRelativeTime(), determineStatus(), generateAgentName()
+- [x] Helper methods: determineStatus(), generateAgentName()
 
 ## Test Data
 
@@ -48,5 +48,5 @@ description: Testing approach for the @ai-devkit/agent-manager package
 Executed on February 25, 2026:
 
 - `npm run test` passed
-- Total: 44 tests passed, 2 suites passed
+- Total: 38 tests passed, 2 suites passed
 - Claude adapter unit tests are deterministic and run without relying on host process permissions

packages/agent-manager/src/__tests__/AgentManager.test.ts

@@ -39,16 +39,14 @@ class MockAdapter implements AgentAdapter {
 function createMockAgent(overrides: Partial<AgentInfo> = {}): AgentInfo {
     return {
         name: 'test-agent',
-        type: 'Claude Code',
+        type: 'claude',
         status: AgentStatus.RUNNING,
-        statusDisplay: '🟢 run',
         summary: 'Test summary',
         pid: 12345,
         projectPath: '/test/path',
         sessionId: 'test-session-id',
         slug: 'test-slug',
         lastActive: new Date(),
-        lastActiveDisplay: 'just now',
         ...overrides,
     };
 }
@@ -62,47 +60,47 @@ describe('AgentManager', () => {
 
     describe('registerAdapter', () => {
         it('should register a new adapter', () => {
-            const adapter = new MockAdapter('Claude Code');
+            const adapter = new MockAdapter('claude');
 
             manager.registerAdapter(adapter);
 
-            expect(manager.hasAdapter('Claude Code')).toBe(true);
+            expect(manager.hasAdapter('claude')).toBe(true);
             expect(manager.getAdapterCount()).toBe(1);
         });
 
         it('should throw error when registering duplicate adapter type', () => {
-            const adapter1 = new MockAdapter('Claude Code');
-            const adapter2 = new MockAdapter('Claude Code');
+            const adapter1 = new MockAdapter('claude');
+            const adapter2 = new MockAdapter('claude');
 
             manager.registerAdapter(adapter1);
 
             expect(() => manager.registerAdapter(adapter2)).toThrow(
-                'Adapter for type "Claude Code" is already registered'
+                'Adapter for type "claude" is already registered'
             );
         });
 
         it('should allow registering multiple different adapter types', () => {
-            const adapter1 = new MockAdapter('Claude Code');
-            const adapter2 = new MockAdapter('Gemini CLI');
+            const adapter1 = new MockAdapter('claude');
+            const adapter2 = new MockAdapter('gemini_cli');
 
             manager.registerAdapter(adapter1);
             manager.registerAdapter(adapter2);
 
             expect(manager.getAdapterCount()).toBe(2);
-            expect(manager.hasAdapter('Claude Code')).toBe(true);
-            expect(manager.hasAdapter('Gemini CLI')).toBe(true);
+            expect(manager.hasAdapter('claude')).toBe(true);
+            expect(manager.hasAdapter('gemini_cli')).toBe(true);
         });
     });
 
     describe('unregisterAdapter', () => {
         it('should unregister an existing adapter', () => {
-            const adapter = new MockAdapter('Claude Code');
+            const adapter = new MockAdapter('claude');
             manager.registerAdapter(adapter);
 
-            const removed = manager.unregisterAdapter('Claude Code');
+            const removed = manager.unregisterAdapter('claude');
 
             expect(removed).toBe(true);
-            expect(manager.hasAdapter('Claude Code')).toBe(false);
+            expect(manager.hasAdapter('claude')).toBe(false);
             expect(manager.getAdapterCount()).toBe(0);
         });
 
@@ -119,8 +117,8 @@ describe('AgentManager', () => {
         });
 
         it('should return all registered adapters', () => {
-            const adapter1 = new MockAdapter('Claude Code');
-            const adapter2 = new MockAdapter('Gemini CLI');
+            const adapter1 = new MockAdapter('claude');
+            const adapter2 = new MockAdapter('gemini_cli');
 
             manager.registerAdapter(adapter1);
             manager.registerAdapter(adapter2);
@@ -134,12 +132,12 @@ describe('AgentManager', () => {
 
     describe('hasAdapter', () => {
         it('should return true for registered adapter', () => {
-            manager.registerAdapter(new MockAdapter('Claude Code'));
-            expect(manager.hasAdapter('Claude Code')).toBe(true);
+            manager.registerAdapter(new MockAdapter('claude'));
+            expect(manager.hasAdapter('claude')).toBe(true);
         });
 
         it('should return false for non-registered adapter', () => {
-            expect(manager.hasAdapter('Claude Code')).toBe(false);
+            expect(manager.hasAdapter('claude')).toBe(false);
         });
     });
 
@@ -154,7 +152,7 @@ describe('AgentManager', () => {
                 createMockAgent({ name: 'agent1' }),
                 createMockAgent({ name: 'agent2' }),
             ];
-            const adapter = new MockAdapter('Claude Code', mockAgents);
+            const adapter = new MockAdapter('claude', mockAgents);
 
             manager.registerAdapter(adapter);
             const agents = await manager.listAgents();
@@ -165,11 +163,11 @@ describe('AgentManager', () => {
         });
 
         it('should aggregate agents from multiple adapters', async () => {
-            const claudeAgents = [createMockAgent({ name: 'claude-agent', type: 'Claude Code' })];
-            const geminiAgents = [createMockAgent({ name: 'gemini-agent', type: 'Gemini CLI' })];
+            const claudeAgents = [createMockAgent({ name: 'claude-agent', type: 'claude' })];
+            const geminiAgents = [createMockAgent({ name: 'gemini-agent', type: 'gemini_cli' })];
 
-            manager.registerAdapter(new MockAdapter('Claude Code', claudeAgents));
-            manager.registerAdapter(new MockAdapter('Gemini CLI', geminiAgents));
+            manager.registerAdapter(new MockAdapter('claude', claudeAgents));
+            manager.registerAdapter(new MockAdapter('gemini_cli', geminiAgents));
 
             const agents = await manager.listAgents();
 
@@ -185,7 +183,7 @@ describe('AgentManager', () => {
                 createMockAgent({ name: 'running-agent', status: AgentStatus.RUNNING }),
                 createMockAgent({ name: 'unknown-agent', status: AgentStatus.UNKNOWN }),
             ];
-            const adapter = new MockAdapter('Claude Code', mockAgents);
+            const adapter = new MockAdapter('claude', mockAgents);
 
             manager.registerAdapter(adapter);
             const agents = await manager.listAgents();
@@ -197,10 +195,10 @@ describe('AgentManager', () => {
         });
 
         it('should handle adapter errors gracefully', async () => {
-            const goodAdapter = new MockAdapter('Claude Code', [
+            const goodAdapter = new MockAdapter('claude', [
                 createMockAgent({ name: 'good-agent' }),
             ]);
-            const badAdapter = new MockAdapter('Gemini CLI', [], true); // Will fail
+            const badAdapter = new MockAdapter('gemini_cli', [], true); // Will fail
 
             manager.registerAdapter(goodAdapter);
             manager.registerAdapter(badAdapter);
@@ -213,8 +211,8 @@ describe('AgentManager', () => {
         });
 
         it('should return empty array when all adapters fail', async () => {
-            const adapter1 = new MockAdapter('Claude Code', [], true);
-            const adapter2 = new MockAdapter('Gemini CLI', [], true);
+            const adapter1 = new MockAdapter('claude', [], true);
+            const adapter2 = new MockAdapter('gemini_cli', [], true);
 
             manager.registerAdapter(adapter1);
             manager.registerAdapter(adapter2);
@@ -230,18 +228,18 @@ describe('AgentManager', () => {
         });
 
         it('should return correct count', () => {
-            manager.registerAdapter(new MockAdapter('Claude Code'));
+            manager.registerAdapter(new MockAdapter('claude'));
             expect(manager.getAdapterCount()).toBe(1);
 
-            manager.registerAdapter(new MockAdapter('Gemini CLI'));
+            manager.registerAdapter(new MockAdapter('gemini_cli'));
             expect(manager.getAdapterCount()).toBe(2);
         });
     });
 
     describe('clear', () => {
         it('should remove all adapters', () => {
-            manager.registerAdapter(new MockAdapter('Claude Code'));
-            manager.registerAdapter(new MockAdapter('Gemini CLI'));
+            manager.registerAdapter(new MockAdapter('claude'));
+            manager.registerAdapter(new MockAdapter('gemini_cli'));
 
             manager.clear();