Sync

Author: ddebowczyk

.beads/config.yaml

@@ -52,3 +52,5 @@
 # - linear.api-key
 # - github.org
 # - github.repo
+
+dolt.shared-server: true

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run mypy libs/py_agent_ctrl
+      - run: uv run pytest -q

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-23
+
+### Added
+
+- `AgentCtrl` facade with five bridge factories: `claude_code()`, `codex()`, `opencode()`, `pi()`, `gemini()`
+- Fluent immutable builder pattern on all action classes with base methods: `with_model`,
+  `with_system_prompt`, `append_system_prompt`, `with_max_turns`, `in_directory`,
+  `with_additional_dirs`, `with_timeout`, `resume_session`, `continue_session`
+- Agent-specific builder methods — Claude Code: `with_permission_mode`, `with_allowed_tools`;
+  Codex: `with_sandbox`, `full_auto`, `dangerously_bypass`, `skip_git_repo_check`, `with_images`;
+  OpenCode: `with_agent`, `with_files`, `with_title`, `share_session`;
+  Pi: `with_provider`, `with_thinking`, `with_tools`, `with_extensions`, `with_skills`, `ephemeral`, `with_session_dir`;
+  Gemini: `with_approval_mode`, `plan_mode`, `yolo`, `with_sandbox`, `with_allowed_tools`
+- `execute(prompt)` — blocking subprocess call returning `AgentResponse`
+- `stream(prompt)` — real-time line-by-line streaming via `subprocess.Popen`, returns `StreamResult`
+- `StreamResult` — iterable of `AgentEvent` with `.exit_code` accessible after iterator exhaustion
+- Subprocess watchdog timeout: `threading.Timer` kills hung processes regardless of output flow
+- `AgentResponse` model with fields: `text`, `exit_code`, `session_id`, `usage` (`TokenUsage`),
+  `tool_calls`, `cost_usd`, `duration_ms`, `parse_failures`, `parse_failure_samples`
+- `TokenUsage` model: `input_tokens`, `output_tokens`, `total_tokens`, `cache_read_tokens`,
+  `cache_write_tokens`, `reasoning_tokens`
+- `AgentTextEvent`, `AgentToolCallEvent`, `AgentResultEvent`, `AgentUnknownEvent` normalized event types
+- Gemini streaming: stateful `tool_use`/`tool_result` pairing yields `AgentToolCallEvent` in real time
+- `AgentError` and `BinaryNotFoundError` structured exception hierarchy (both subclass `RuntimeError`)
+- Session continuity: `resume_session(id)` and `continue_session()` supported across all five bridges
+- `ctrlagent` CLI with commands: `execute`, `stream`, `resume`, `continue`,
+  `agents list`, `agents capabilities`
+- 82 unit and feature tests; 10 integration smoke tests (skip automatically without live CLI binaries)
+- GitHub Actions CI pipeline: `ruff check`, `mypy --strict`, `pytest` on push and PR to `main`
+- PEP 561 `py.typed` marker for IDE type inference from installed package
+- Full mypy strict-mode compliance across all 41 source files

README.md

@@ -1,81 +1,90 @@
 # py-agent-ctrl
 
-Programmatic wrapper for the **Claude Code CLI** — Python port of [cognesy/agent-ctrl](https://github.com/cognesy/agent-ctrl) (PHP).
+Unified Python bridge for CLI coding agents.
 
-Zero dependencies beyond the Python standard library.
+This repo exposes:
 
-## Install
+- a Python API under `py_agent_ctrl`
+- a unified `ctrlagent` CLI
+- direct CLI bridges for `claude`, `codex`, `opencode`, `pi`, and `gemini`
+
+The codebase follows the clean layout described in [docs/dev/architecture.md](docs/dev/architecture.md):
+
+- `apps/` for runnable shells
+- `libs/` for importable code
+- `resources/` for passive assets
+- `docs/` for documentation
+- `tests/` for unit, integration, feature, and regression coverage
+
+## Development
+
+Use `uv` only:
 
 ```bash
-pip install git+https://github.com/cognesy/py-agent-ctrl.git@main
+uv sync --extra dev
+uv run pytest tests/unit tests/integration tests/feature tests/regression
+uv run ctrlagent agents list
 ```
 
-## Usage
+## Python API
 
 ```python
-from agent_ctrl import ClaudeCodeClient
+from py_agent_ctrl import AgentCtrl
+
+response = (
+    AgentCtrl.claude_code()
+    .with_model("claude-sonnet-4-5")
+    .with_permission_mode("bypassPermissions")
+    .execute("Summarize this repository.")
+)
 
-# Simple sync
-response = ClaudeCodeClient().execute("Summarise this repo.")
 print(response.text)
 print(response.session_id)
+```
 
-# With options
-response = (
-    ClaudeCodeClient()
-    .with_system_prompt("You are a code analysis assistant.")
-    .with_max_turns(5)
-    .with_cwd("/path/to/project")
-    .execute("List all API endpoints.")
-)
+Other bridges use the same top-level facade:
 
-# Session continuity
-r1 = ClaudeCodeClient().execute("Start a multi-turn analysis.")
-r2 = ClaudeCodeClient().resume(r1.session_id).execute("Now summarise what you found.")
+```python
+from py_agent_ctrl import AgentCtrl
 
-# Async streaming with callbacks
-import asyncio
+AgentCtrl.codex().with_sandbox("workspace-write").execute("Review the tests.")
+AgentCtrl.opencode().with_agent("coder").execute("Refactor the payment flow.")
+AgentCtrl.pi().with_thinking("high").execute("Create an implementation plan.")
+AgentCtrl.gemini().plan_mode().execute("Inspect the architecture.")
+```
 
-async def main():
-    async for event in ClaudeCodeClient().stream("Explain this codebase."):
-        from agent_ctrl import AssistantEvent
-        if isinstance(event, AssistantEvent):
-            print(event.text, end="", flush=True)
+## CLI
 
-asyncio.run(main())
+```bash
+uv run ctrlagent agents list
+uv run ctrlagent agents capabilities --agent claude-code
+uv run ctrlagent execute --agent claude-code "Summarize this repository."
+uv run ctrlagent resume --agent codex --session thread_123 "Continue."
+uv run ctrlagent continue --agent gemini "Proceed."
 ```
 
-## ClaudeCodeClient builder options
-
-| Method | Description |
-|--------|-------------|
-| `.with_model(model)` | Override the Claude model |
-| `.with_system_prompt(text)` | Replace the default system prompt |
-| `.append_system_prompt(text)` | Append to the default system prompt |
-| `.with_max_turns(n)` | Limit agentic turns |
-| `.with_permission_mode(mode)` | `bypassPermissions` (default) / `acceptEdits` / `default` |
-| `.with_allowed_tools(*tools)` | Pre-approve specific tools, e.g. `"Read"`, `"Edit"` |
-| `.resume(session_id)` | Resume a specific prior session |
-| `.continue_session()` | Resume the most recent session |
-| `.with_cwd(path)` | Working directory for the subprocess |
-| `.with_timeout(seconds)` | Subprocess timeout (default 120s) |
-| `.on_text(fn)` | Callback for each text chunk during async streaming |
-| `.on_tool_use(fn)` | Callback for each tool use during async streaming |
-
-## ClaudeResponse
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | `str` | Concatenated assistant text |
-| `session_id` | `str \| None` | Session ID for resuming |
-| `success` | `bool` | `exit_code == 0 and not is_error` |
-| `tool_calls` | `list[ToolUseContent]` | Tools invoked during the run |
-| `cost_usd` | `float \| None` | Reported cost (if available) |
-| `duration_ms` | `int \| None` | Reported duration (if available) |
-| `events` | `list[StreamEvent]` | All raw typed events |
-
-## Requirements
-
-- Python 3.12+
-- `claude` CLI installed and on `PATH`: `npm install -g @anthropic-ai/claude-code`
-- `ANTHROPIC_API_KEY` set in the environment
+## Supported Agents
+
+| Agent | Python Facade | CLI Name |
+|-------|---------------|----------|
+| Claude Code | `AgentCtrl.claude_code()` | `claude-code` |
+| Codex | `AgentCtrl.codex()` | `codex` |
+| OpenCode | `AgentCtrl.opencode()` | `opencode` |
+| Pi | `AgentCtrl.pi()` | `pi` |
+| Gemini | `AgentCtrl.gemini()` | `gemini` |
+
+## Migration
+
+This repo is a clean cut from the old flat Claude-only layout.
+
+- old root package: `agent_ctrl`
+- new root package: `py_agent_ctrl`
+- old client: `ClaudeCodeClient`
+- new entrypoint: `AgentCtrl`
+
+See:
+
+- [docs/user/quickstart.md](docs/user/quickstart.md)
+- [docs/user/cli.md](docs/user/cli.md)
+- [docs/user/migration.md](docs/user/migration.md)
+- [resources/skills/upgrade/SKILL.md](resources/skills/upgrade/SKILL.md)