Skip to content

Commit 45a6bbb

Browse files
codeaholicguycodeaholicguy
committed
docs(ai): add codex adapter agent-manager lifecycle docs
1 parent 425f317 commit 45a6bbb

5 files changed

Lines changed: 370 additions & 0 deletions

‎docs/ai/design/feature-codex-adapter-agent-manager-package.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
phase: design
3+
title: "Codex Adapter in @ai-devkit/agent-manager - Design"
4+
feature: codex-adapter-agent-manager-package
5+
description: Architecture and implementation design for introducing Codex adapter support in the shared agent manager package
6+
---
7+
8+
# Design: Codex Adapter for @ai-devkit/agent-manager
9+
10+
## Architecture Overview
11+
12+
```mermaid
13+
graph TD
14+
User[User runs ai-devkit agent list/open] --> Cmd[packages/cli/src/commands/agent.ts]
15+
Cmd --> Manager[AgentManager]
16+
17+
subgraph Pkg[@ai-devkit/agent-manager]
18+
Manager --> Claude[ClaudeCodeAdapter]
19+
Manager --> Codex[CodexAdapter]
20+
Codex --> Proc[process utils]
21+
Codex --> File[file utils]
22+
Codex --> Types[AgentAdapter/AgentInfo/AgentStatus]
23+
Focus[TerminalFocusManager]
24+
end
25+
26+
Cmd --> Focus
27+
Cmd --> Output[CLI table/json rendering]
28+
```
29+
30+
Responsibilities:
31+
- `CodexAdapter`: discover and map running Codex sessions to `AgentInfo`
32+
- `AgentManager`: aggregate Codex + existing adapter results
33+
- CLI command: register adapters, display results, and invoke open/focus behavior
34+
35+
## Data Models
36+
37+
- Reuse existing `AgentAdapter`, `AgentInfo`, `AgentStatus`, and `AgentType` models
38+
- `AgentType` already supports `codex`; adapter emits `type: 'codex'`
39+
- Codex raw metadata (internal to adapter) is normalized into:
40+
- `id`: deterministic session/process identifier
41+
- `name`: user-facing label derived from `cwd`; fallback to `codex-<session-id-prefix>` when `cwd` is missing
42+
- `cwd`: workspace path (if available)
43+
- `status`: computed from recency/activity metadata using the same threshold values already used by existing adapters
44+
- `command`: executable + args required for open/focus flow
45+
46+
## API Design
47+
48+
### Package Exports
49+
- Add `CodexAdapter` to:
50+
- `packages/agent-manager/src/adapters/index.ts`
51+
- `packages/agent-manager/src/index.ts`
52+
53+
### CLI Integration
54+
- Update `packages/cli/src/commands/agent.ts` to register `CodexAdapter` alongside `ClaudeCodeAdapter`
55+
- Keep display mapping logic in CLI; do not move presentation concerns into package
56+
57+
## Component Breakdown
58+
59+
1. `packages/agent-manager/src/adapters/CodexAdapter.ts`
60+
- Implement adapter contract methods/properties
61+
- Discover Codex sessions from `~/.codex/sessions/YYYY/MM/DD/*.jsonl`
62+
- Map session data to standardized `AgentInfo`
63+
64+
2. `packages/agent-manager/src/__tests__/adapters/CodexAdapter.test.ts`
65+
- Unit tests for detection/parsing/status mapping/error handling
66+
67+
3. `packages/agent-manager/src/adapters/index.ts` and `src/index.ts`
68+
- Export adapter class
69+
70+
4. `packages/cli/src/commands/agent.ts`
71+
- Register Codex adapter in manager setup path(s)
72+
73+
## Design Decisions
74+
75+
- Decision: Implement Codex detection in package, not CLI.
76+
- Rationale: preserves package as the single source of truth for agent discovery.
77+
- Decision: Reuse existing adapter contract and manager aggregation flow.
78+
- Rationale: minimizes surface area and regression risk.
79+
- Decision: Keep CLI output semantics unchanged.
80+
- Rationale: this feature adds detection capability, not UX changes.
81+
- Decision: Parse the first JSON line (`type=session_meta`) as the authoritative session identity/cwd/timestamp source.
82+
- Rationale: sampled session files consistently include this shape, and it avoids scanning full transcript payloads.
83+
- Decision: Determine end-of-session by reading the last JSON line and checking `payload.type`.
84+
- Rationale: `task_complete`/`turn_aborted` reliably indicate ended runs in sampled data.
85+
- Decision: Keep status-threshold values consistent across adapters.
86+
- Rationale: preserves cross-agent behavior consistency and avoids adapter-specific drift.
87+
- Decision: Use `codex-<session-id-prefix>` fallback naming when `cwd` is unavailable.
88+
- Rationale: keeps identifiers deterministic and short while remaining user-readable.
89+
90+
## Non-Functional Requirements
91+
92+
- Performance: `agent list` should remain bounded by existing adapter aggregation patterns.
93+
- Reliability: Codex adapter failures must be isolated (no full-command failure when one adapter errors).
94+
- Maintainability: follow Claude adapter structure to keep adapter implementations consistent.
95+
- Security: only read local metadata/process info already permitted by existing CLI behavior.

‎docs/ai/implementation/feature-codex-adapter-agent-manager-package.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
phase: implementation
3+
title: "Codex Adapter in @ai-devkit/agent-manager - Implementation"
4+
feature: codex-adapter-agent-manager-package
5+
description: Implementation notes for Codex adapter support in package agent manager and CLI integration
6+
---
7+
8+
# Implementation Guide: Codex Adapter in @ai-devkit/agent-manager
9+
10+
## Development Setup
11+
12+
- Use branch/worktree: `feature-codex-adapter-agent-manager-package`
13+
- Install dependencies with `npm ci`
14+
- Validate docs and feature scope with:
15+
- `npx ai-devkit@latest lint`
16+
- `npx ai-devkit@latest lint --feature codex-adapter-agent-manager-package`
17+
18+
## Code Structure
19+
20+
- Package adapter implementation:
21+
- `packages/agent-manager/src/adapters/CodexAdapter.ts`
22+
- Package exports:
23+
- `packages/agent-manager/src/adapters/index.ts`
24+
- `packages/agent-manager/src/index.ts`
25+
- CLI wiring:
26+
- `packages/cli/src/commands/agent.ts`
27+
- Tests:
28+
- `packages/agent-manager/src/__tests__/adapters/CodexAdapter.test.ts`
29+
- CLI tests touching adapter registration/open flow
30+
31+
## Implementation Notes
32+
33+
### Core Features
34+
- Implement Codex adapter contract (`type`, `name`, `listRunningAgents`) using existing utilities where possible.
35+
- Normalize Codex metadata into stable `AgentInfo` output.
36+
- Register Codex adapter in command paths that instantiate `AgentManager`.
37+
38+
### Patterns & Best Practices
39+
- Follow `ClaudeCodeAdapter` structure for consistency.
40+
- Keep adapter-specific parsing in adapter module; keep formatting in CLI.
41+
- Fail soft on malformed/partial entries; avoid throwing across adapter boundary.
42+
43+
## Integration Points
44+
45+
- `AgentManager` parallel aggregation behavior
46+
- `TerminalFocusManager` open/focus flow compatibility for Codex command metadata
47+
- CLI list/json output mapping
48+
49+
## Error Handling
50+
51+
- Handle missing/unreadable Codex source data by returning empty results.
52+
- Catch parsing errors per-entry and continue processing valid entries.
53+
- Let manager collect adapter errors without crashing full command.
54+
55+
## Performance Considerations
56+
57+
- Avoid repeated filesystem scans where possible.
58+
- Keep parsing linear to discovered entries.
59+
- Reuse existing async aggregation model.
60+
61+
## Security Notes
62+
63+
- Read only local metadata/process information necessary for agent detection.
64+
- Do not execute arbitrary commands during detection.

‎docs/ai/planning/feature-codex-adapter-agent-manager-package.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
phase: planning
3+
title: "Codex Adapter in @ai-devkit/agent-manager - Planning"
4+
feature: codex-adapter-agent-manager-package
5+
description: Task plan for adding Codex adapter support and integrating it into CLI agent commands
6+
---
7+
8+
# Planning: Codex Adapter in @ai-devkit/agent-manager
9+
10+
## Milestones
11+
12+
- [ ] Milestone 1: Codex adapter design finalized and scaffolding created
13+
- [ ] Milestone 2: Codex adapter implementation and package exports complete
14+
- [ ] Milestone 3: CLI integration, tests, and verification complete
15+
16+
## Task Breakdown
17+
18+
### Phase 1: Foundation
19+
- [ ] Task 1.1: Confirm Codex discovery inputs and mapping contract
20+
- Use `~/.codex/sessions/YYYY/MM/DD/*.jsonl` as the primary source
21+
- Parse line 1 `session_meta` for `id`, `cwd`, `timestamp`
22+
- Parse the last line for terminal event markers (`task_complete`, `turn_aborted`)
23+
- Define normalization rules for `id`, `name`, `cwd`, and `status`
24+
- [ ] Task 1.2: Scaffold package adapter files
25+
- Add `CodexAdapter.ts` and test file skeleton
26+
- Update adapter/index exports
27+
28+
### Phase 2: Core Features
29+
- [ ] Task 2.1: Implement Codex discovery and mapping logic
30+
- Parse metadata with robust validation/fallback behavior
31+
- Compute status using existing status model
32+
- [ ] Task 2.2: Register Codex adapter in CLI command flow
33+
- Update all manager registration paths in `commands/agent.ts`
34+
- Preserve output structure and errors
35+
36+
### Phase 3: Integration & Polish
37+
- [ ] Task 3.1: Add/extend tests
38+
- Unit tests for Codex adapter branches and failure handling
39+
- CLI command tests for registration/path coverage
40+
- [ ] Task 3.2: Validate and document
41+
- Run lint/build/tests for affected projects
42+
- Record implementation + testing outcomes in docs/ai
43+
44+
## Dependencies
45+
46+
- Existing `@ai-devkit/agent-manager` adapter contract and utilities
47+
- Existing CLI agent command integration points
48+
- Availability of Codex metadata sources in local runtime
49+
50+
## Timeline & Estimates
51+
52+
- Task 1.1-1.2: 0.5 day
53+
- Task 2.1-2.2: 1.0 day
54+
- Task 3.1-3.2: 0.5 day
55+
- Total estimate: 2.0 days
56+
57+
## Risks & Mitigation
58+
59+
- Risk: Codex metadata format may vary across versions.
60+
- Mitigation: defensive parsing + tests with partial/malformed fixtures.
61+
- Risk: `agent open` behavior for Codex may need command-specific nuances.
62+
- Mitigation: validate open flow with representative commands and add focused tests.
63+
- Risk: Adding adapter increases list latency.
64+
- Mitigation: keep async aggregation pattern and short-circuit invalid entries.
65+
66+
## Resources Needed
67+
68+
- Existing adapter examples (`ClaudeCodeAdapter`) as implementation template
69+
- Maintainer validation for Codex session/source assumptions
70+
- CI runtime for lint/build/test verification

‎docs/ai/requirements/feature-codex-adapter-agent-manager-package.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
phase: requirements
3+
title: "Codex Adapter in @ai-devkit/agent-manager - Requirements"
4+
feature: codex-adapter-agent-manager-package
5+
description: Add a Codex adapter to the shared agent-manager package and wire CLI consumption through package exports
6+
---
7+
8+
# Requirements: Add Codex Adapter to @ai-devkit/agent-manager
9+
10+
## Problem Statement
11+
12+
`@ai-devkit/agent-manager` currently ships `ClaudeCodeAdapter` as the only concrete adapter, while `AgentType` already includes `codex`. As a result, Codex sessions are not detected/listed/opened through the shared package flow used by CLI agent commands.
13+
14+
Who is affected:
15+
- Users running Codex alongside other supported agents who expect `ai-devkit agent list/open` to include Codex
16+
- CLI maintainers who want adapter support centralized in `@ai-devkit/agent-manager`
17+
- Contributors who need a reference implementation for adding new adapters
18+
19+
## Goals & Objectives
20+
21+
### Primary Goals
22+
- Implement a package-level `CodexAdapter` under `packages/agent-manager`
23+
- Export `CodexAdapter` from package public entry points
24+
- Update CLI agent command wiring to register `CodexAdapter` through package imports
25+
- Preserve existing behavior for Claude and existing output/error contracts
26+
27+
### Secondary Goals
28+
- Reuse shared process/file utilities and adapter contract patterns
29+
- Add tests for Codex adapter discovery, status mapping, and command metadata
30+
- Establish a clean extension path for future adapters (Gemini/others)
31+
32+
### Non-Goals
33+
- Reworking overall `ai-devkit agent` UX
34+
- Refactoring unrelated CLI command modules
35+
- Introducing a new plugin system for adapters in this phase
36+
37+
## User Stories & Use Cases
38+
39+
1. As a Codex user, I want running Codex sessions to appear in `ai-devkit agent list` so I can inspect active work quickly.
40+
2. As a CLI user, I want `ai-devkit agent open <id>` to support Codex agents with the same behavior guarantees as existing agents.
41+
3. As a maintainer, I want Codex detection logic in `@ai-devkit/agent-manager` so package/CLI behavior does not drift.
42+
4. As an adapter author, I want Codex adapter tests to act as a template for future adapter implementations.
43+
44+
## Success Criteria
45+
46+
- `packages/agent-manager/src/adapters/CodexAdapter.ts` exists and implements `AgentAdapter`
47+
- `@ai-devkit/agent-manager` public exports include `CodexAdapter`
48+
- `packages/cli/src/commands/agent.ts` registers `CodexAdapter` from package exports
49+
- Unit tests cover Codex adapter happy path, empty/no-session path, and invalid data handling
50+
- Existing agent command tests continue to pass without regressions
51+
52+
## Constraints & Assumptions
53+
54+
### Technical Constraints
55+
- Must follow existing Nx TypeScript project structure and test setup
56+
- Must keep adapter contract compatibility (`AgentAdapter`, `AgentInfo`, `AgentStatus`)
57+
- Must not break JSON/table output schema consumed by users
58+
59+
### Assumptions
60+
- Codex session metadata is available in `~/.codex/sessions/YYYY/MM/DD/*.jsonl` with a stable first-line `session_meta` payload
61+
- `TerminalFocusManager` can open Codex sessions using command metadata supplied by adapter or existing CLI flow
62+
- Codex naming and workspace path conventions are stable enough for first-pass implementation
63+
64+
## Questions & Open Items
65+
66+
- Resolved (2026-02-26): Canonical discovery source is `~/.codex/sessions` JSONL files. In 88/88 sampled files, line 1 is `type=session_meta` with `payload.id`, `payload.cwd`, and `payload.timestamp`.
67+
- Resolved (2026-02-26): Active-vs-ended heuristic should use latest event in session file.
68+
- `payload.type` of `task_complete` or `turn_aborted` => session ended.
69+
- other trailing event/message types + recent timestamp => potentially active.
70+
- Resolved (2026-02-26): Use the same status threshold values across all adapters (Codex uses existing shared/Claude-equivalent thresholds).
71+
- Resolved (2026-02-26): If `cwd` is missing, fallback display identifier is `codex-<session-id-prefix>`.

‎docs/ai/testing/feature-codex-adapter-agent-manager-package.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
phase: testing
3+
title: "Codex Adapter in @ai-devkit/agent-manager - Testing"
4+
feature: codex-adapter-agent-manager-package
5+
description: Test strategy and coverage plan for Codex adapter integration
6+
---
7+
8+
# Testing Strategy: Codex Adapter in @ai-devkit/agent-manager
9+
10+
## Test Coverage Goals
11+
12+
- Unit test coverage target: 100% of new/changed code
13+
- Integration scope: package adapter integration with `AgentManager` and CLI registration paths
14+
- End-to-end scope: `ai-devkit agent list` and `ai-devkit agent open` behavior with Codex entries
15+
16+
## Unit Tests
17+
18+
### `CodexAdapter`
19+
- [ ] Detect and map valid Codex entries into `AgentInfo`
20+
- [ ] Return empty array when no Codex metadata exists
21+
- [ ] Skip malformed entries without failing full result
22+
- [ ] Map status values based on activity thresholds
23+
- [ ] Produce stable name/id collision handling
24+
25+
### `AgentManager` integration seam
26+
- [ ] Aggregates Codex + Claude adapter output
27+
- [ ] Handles Codex adapter errors while preserving other adapter results
28+
29+
## Integration Tests
30+
31+
- [ ] `agent` command registers `CodexAdapter` in manager setup path(s)
32+
- [ ] `agent list --json` includes Codex entries with expected fields
33+
- [ ] `agent open` handles Codex agent command metadata path correctly
34+
35+
## End-to-End Tests
36+
37+
- [ ] User flow: run `ai-devkit agent list` with Codex running
38+
- [ ] User flow: run `ai-devkit agent open <codex-id>`
39+
- [ ] Regression: Claude list/open remains unchanged
40+
41+
## Test Data
42+
43+
- Mock Codex session/process fixtures:
44+
- valid, empty, partial, malformed
45+
- Mock filesystem and process utility responses
46+
47+
## Test Reporting & Coverage
48+
49+
- Commands:
50+
- `npm run lint`
51+
- `npm run build`
52+
- `npm run test -- --coverage`
53+
- project-scoped Nx tests for `agent-manager` and `cli`
54+
- Capture coverage deltas and list any residual gaps in this doc
55+
56+
## Manual Testing
57+
58+
- Verify table output readability for mixed Claude/Codex lists
59+
- Verify JSON output schema consistency
60+
- Validate open/focus behavior in a local Codex session
61+
62+
## Performance Testing
63+
64+
- Compare `agent list` runtime before/after Codex adapter registration
65+
- Validate no major latency regression for typical session counts
66+
67+
## Bug Tracking
68+
69+
- Track defects by severity (`blocking`, `major`, `minor`)
70+
- Re-run adapter + command regressions for every bug fix

0 commit comments

Comments
 (0)