Merge pull request #3 from ebarti/stack/phase-3-claude-codex

Add Claude and Codex runtime adapters

Author: ebarti

.planning/REQUIREMENTS.md

@@ -166,10 +166,10 @@ Which phases cover which requirements. Updated during roadmap creation.
 | EVNT-03 | Phase 2 | Complete |
 | EVNT-04 | Phase 2 | Complete |
 | EVNT-05 | Phase 2 | Complete |
-| ADPT-01 | Phase 3 | Pending |
-| ADPT-02 | Phase 3 | Pending |
-| ADPT-03 | Phase 3 | Pending |
-| ADPT-04 | Phase 3 | Pending |
+| ADPT-01 | Phase 3 | Complete |
+| ADPT-02 | Phase 3 | Complete |
+| ADPT-03 | Phase 3 | Complete |
+| ADPT-04 | Phase 3 | Complete |
 | ADPT-05 | Phase 4 | Pending |
 | ADPT-06 | Phase 4 | Pending |
 | ADPT-07 | Phase 4 | Pending |
@@ -180,7 +180,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | TEST-05 | Phase 5 | Pending |
 | TEST-06 | Phase 4 | Pending |
 | DOCS-01 | Phase 5 | Pending |
-| DOCS-02 | Phase 3 | Pending |
+| DOCS-02 | Phase 3 | Complete |
 | DOCS-03 | Phase 4 | Pending |
 | DOCS-04 | Phase 5 | Pending |
 | DOCS-05 | Phase 5 | Pending |

.planning/ROADMAP.md

@@ -19,7 +19,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 
 - [x] **Phase 1: Core Runtime Skeleton** - Installable core package with public task/result/runtime contracts.
 - [x] **Phase 2: Events and Test Harness** - Optional extras skeleton, event system, and fake SDK contract tests.
-- [ ] **Phase 3: Claude and Codex Runtimes** - First two real vendor adapters through the shared API.
+- [x] **Phase 3: Claude and Codex Runtimes** - First two real vendor adapters through the shared API.
 - [ ] **Phase 4: Antigravity and Cross-Runtime Proof** - Third adapter plus same-task multi-runtime proof and Mestre compatibility checks.
 - [ ] **Phase 5: Public Release Readiness** - Documentation, capability matrix, live-smoke guidance, and PyPI publish checklist.
 
@@ -119,6 +119,6 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
 |-------|----------------|--------|-----------|
 | 1. Core Runtime Skeleton | 3/3 | Complete | 2026-06-10 |
 | 2. Events and Test Harness | 3/3 | Complete | 2026-06-10 |
-| 3. Claude and Codex Runtimes | 0/3 | Not started | - |
+| 3. Claude and Codex Runtimes | 3/3 | Complete | 2026-06-10 |
 | 4. Antigravity and Cross-Runtime Proof | 0/3 | Not started | - |
 | 5. Public Release Readiness | 0/3 | Not started | - |

.planning/STATE.md

@@ -3,10 +3,10 @@ gsd_state_version: '1.0'
 status: executing
 progress:
   total_phases: 5
-  completed_phases: 2
+  completed_phases: 3
   total_plans: 15
-  completed_plans: 6
-  percent: 40
+  completed_plans: 9
+  percent: 60
 ---
 
 # Project State
@@ -18,21 +18,21 @@ See: .planning/PROJECT.md (updated 2026-06-10)
 **Core value:** Developers can run the same agentic task through Claude, Codex,
 or Antigravity using one small, typed Python API while preserving the
 vendor-specific capabilities needed for real work.
-**Current focus:** Phase 3: Claude and Codex Runtimes
+**Current focus:** Phase 4: Antigravity and Cross-Runtime Proof
 
 ## Current Position
 
-Phase: 3 of 5 (Claude and Codex Runtimes)
+Phase: 4 of 5 (Antigravity and Cross-Runtime Proof)
 Plan: 0 of 3 in current phase
-Status: Phase 2 complete; ready for Phase 3
-Last activity: 2026-06-10 - Phase 2 added normalized events and fake SDK contract helpers.
+Status: Phase 3 complete; ready for Phase 4
+Last activity: 2026-06-10 - Phase 3 added Claude and Codex adapters.
 
-Progress: [####------] 40%
+Progress: [######----] 60%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 6
+- Total plans completed: 9
 - Average duration: n/a
 - Total execution time: 0.0 hours
 
@@ -42,9 +42,10 @@ Progress: [####------] 40%
 |-------|-------|-------|----------|
 | 1. Core Runtime Skeleton | 3 | 3 | n/a |
 | 2. Events and Test Harness | 3 | 3 | n/a |
+| 3. Claude and Codex Runtimes | 3 | 3 | n/a |
 
 **Recent Trend:**
-- Last 5 plans: 01-02, 01-03, 02-01, 02-02, 02-03
+- Last 5 plans: 02-02, 02-03, 03-01, 03-02, 03-03
 - Trend: n/a
 
 *Updated after each plan completion*
@@ -65,6 +66,8 @@ Recent decisions affecting current work:
   to optional adapter modules.
 - Phase 2: Event payloads use a normalized dictionary shape and sanitize
   sensitive/high-volume attributes before emission.
+- Phase 3: Claude and Codex adapters use lazy imports and fake-injected tests
+  so default CI remains credential-free.
 
 ### Pending Todos
 

.planning/phases/03-claude-and-codex-runtimes/03-CONTEXT.md

@@ -0,0 +1,65 @@
+# Phase 3: Claude and Codex Runtimes - Context
+
+**Gathered:** 2026-06-10
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Implement runnable Claude Agent SDK and OpenAI Codex SDK adapters through the
+shared runtime API, with clear diagnostics and fake-injected tests.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Adapter Boundaries
+- Keep imports lazy so `agent_runtime_kit` remains dependency-free.
+- Expose real adapter classes under `agent_runtime_kit.adapters`.
+- Use injected SDK surfaces in tests rather than live credentials.
+- Reject unsupported provider inputs with typed errors.
+
+### Provider Mapping
+- Claude maps system prompt, cwd, permissions, MCP, sessions, structured
+  output, allowed/disallowed tools, and budget where supported.
+- Codex maps cwd, developer instructions, model, approval mode, sandbox,
+  sessions, structured output, and reasoning effort.
+- Codex rejects per-task MCP because the Python SDK does not expose that
+  configuration path.
+
+### the agent's Discretion
+Use generic, community-facing names while preserving Mestre-compatible fields.
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- Phase 2 events and fake SDK helpers provide adapter test surfaces.
+- Mestre's Claude and Codex vendor-lane adapters informed mapping choices.
+
+### Established Patterns
+- Runtime adapters emit normalized events and return `AgentResult`.
+
+### Integration Points
+- `agent_runtime_kit.adapters.register_adapters()` registers provider runtimes
+  into the core registry.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+The quickstart should demonstrate one provider end to end through the public
+API.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+Antigravity and cross-runtime proof are deferred to Phase 4.
+
+</deferred>

.planning/phases/03-claude-and-codex-runtimes/03-PLAN.md

@@ -0,0 +1,21 @@
+# Phase 3: Claude and Codex Runtimes - Plan
+
+## Plan 03-01: Claude Agent SDK adapter and tests
+
+- Implement `ClaudeAgentRuntime`.
+- Map task fields into `ClaudeAgentOptions`.
+- Translate streamed SDK messages into `AgentResult`.
+- Cover success, tools, sessions, diagnostics, and unsupported model handling.
+
+## Plan 03-02: Codex SDK adapter and tests
+
+- Implement `CodexAgentRuntime`.
+- Map task fields into `AsyncCodex`, `CodexConfig`, thread start/resume, and
+  thread run kwargs.
+- Cover success, structured output, sessions, diagnostics, and unsupported MCP.
+
+## Plan 03-03: One-runtime quickstart and provider diagnostics docs
+
+- Add quickstart documentation using Claude.
+- Add provider diagnostics documentation.
+- Add a diagnostics helper for installed adapter availability.

.planning/phases/03-claude-and-codex-runtimes/03-SUMMARY.md

@@ -0,0 +1,12 @@
+# Phase 3: Claude and Codex Runtimes - Summary
+
+Implemented the first real vendor adapters:
+
+- `ClaudeAgentRuntime` with lazy `claude-agent-sdk` imports and injected SDK
+  tests.
+- `CodexAgentRuntime` with lazy `openai-codex` imports and injected SDK tests.
+- Adapter registry helper.
+- Provider diagnostics helper.
+- Quickstart and provider diagnostics docs.
+
+Default tests remain credential-free and do not require vendor packages.

.planning/phases/03-claude-and-codex-runtimes/03-VERIFICATION.md

@@ -0,0 +1,18 @@
+---
+status: passed
+---
+
+# Phase 3 Verification
+
+## Automated Checks
+
+- `uv run pytest` - passed, 17 tests.
+- `uv run ruff check .` - passed.
+- `uv run mypy` - passed.
+
+## Result
+
+Phase 3 success criteria are satisfied. Claude and Codex adapters are runnable
+through injected SDK surfaces, missing-package diagnostics are exposed through
+`availability()`, unsupported model/MCP cases are typed, and the quickstart
+documents one provider end to end.

docs/providers.md

@@ -0,0 +1,20 @@
+# Provider Diagnostics
+
+`agent-runtime-kit` keeps provider setup checks explicit. Each runtime exposes
+`availability()` and returns a `RuntimeAvailability` value with:
+
+- runtime kind
+- availability flag
+- reason
+- message
+- package name
+- installed version when discoverable
+
+Claude uses the `claude-agent-sdk` package and maps working directory,
+permissions, MCP servers, sessions, structured output, tool allow/deny lists,
+and budget where supported by the installed SDK.
+
+Codex uses the `openai-codex` package and maps working directory, session
+resume, approval mode, sandbox, structured output, model, and reasoning effort.
+Codex does not currently support per-task MCP server configuration through this
+adapter, so `mcp_servers` is rejected with a typed error.

docs/quickstart.md

@@ -0,0 +1,34 @@
+# Quickstart
+
+Install the dependency-free core:
+
+```bash
+pip install agent-runtime-kit
+```
+
+Install one provider extra:
+
+```bash
+pip install "agent-runtime-kit[claude]"
+```
+
+Run a task:
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentTask
+from agent_runtime_kit.adapters import ClaudeAgentRuntime
+
+
+async def main() -> None:
+    runtime = ClaudeAgentRuntime(default_model="claude-sonnet-4-6")
+    result = await runtime.run(AgentTask(goal="Summarize this repository"))
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+Use `runtime.availability()` before dispatching work in applications that need
+clear setup diagnostics.

src/agent_runtime_kit/adapters/__init__.py

@@ -1,5 +1,19 @@
-"""Vendor adapter modules.
+"""Vendor adapter modules."""
 
-Import concrete adapters from their provider modules so optional dependencies
-remain lazy.
-"""
+from agent_runtime_kit._types import AgentRuntimeKind
+from agent_runtime_kit.adapters.claude import ClaudeAgentRuntime
+from agent_runtime_kit.adapters.codex import CodexAgentRuntime
+from agent_runtime_kit.registry import RuntimeRegistry
+
+__all__ = [
+    "ClaudeAgentRuntime",
+    "CodexAgentRuntime",
+    "register_adapters",
+]
+
+
+def register_adapters(registry: RuntimeRegistry, *, replace: bool = False) -> None:
+    """Register the built-in vendor adapters in a runtime registry."""
+
+    registry.register(AgentRuntimeKind.CLAUDE_AGENT_SDK, ClaudeAgentRuntime, replace=replace)
+    registry.register(AgentRuntimeKind.CODEX_AGENT_SDK, CodexAgentRuntime, replace=replace)