steerdev 1.1.48__tar.gz → 1.1.62__tar.gz

steerdev-1.1.62/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Overview
+
+**steerdev-agent** is a Python CLI that orchestrates AI coding agents via subprocess execution, streaming events to the steerdev.com API. It fetches tasks, builds prompts, launches agents (Claude Code and pi are wired; `openai-codex` is a stub), and reports activity.
+
+## Project Structure
+
+```
+src/steerdev_agent/
+├── cli.py               # Typer CLI commands
+├── runner.py             # Main orchestrator
+├── agent_loop.py         # Persistent agent mode
+├── version.py            # Version management
+├── integration.py        # Integration utilities
+├── api/                  # API clients (tasks, sessions, events, workflows, etc.)
+├── config/               # Pydantic config models and settings
+├── executor/             # Agent subprocess execution (base, claude, stream)
+├── workflow/             # Multi-phase workflow execution and memory
+├── prompt/               # Prompt building and templates
+├── setup/                # Project setup and templates
+├── handlers/             # Task/PRD handlers
+└── git/                  # Git utilities
+```
+
+## Development
+
+- **Python 3.12+** with **uv** package manager
+- `uv sync` — install deps
+- `uv run pytest` — run tests
+- `uv run ruff check . && uv run ruff format .` — lint and format
+- `uv run basedpyright` — type check
+
+## Conventions
+
+- Type hints on all function signatures
+- Pydantic v2 for data models and config
+- Async/await for I/O (HTTP, subprocess)
+- `loguru` for logging
+- Specific exception classes (no bare `except`)
+- Absolute imports (`from steerdev_agent.config.models import ...`)
+- Import order: stdlib, third-party, local
+
+## Key Integration Points
+
+- **steerdev.com API**: Bearer auth via `STEERDEV_API_KEY`. Events POSTed to `/api/v1/sessions/{id}/events`.
+- **Executor**: Launches agents as subprocesses with `--output-format stream-json`. Parses newline-delimited JSON events.
+- **Config**: YAML config file + environment variable overrides.
+
+## Environment Variables
+
+| Variable | Purpose |
+| --- | --- |
+| `STEERDEV_API_KEY` | API authentication |
+| `STEERDEV_PROJECT_ID` | Default project |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex`, `acp:<agent>` |
+| `STEERDEV_ACP_HARNESS` | ACP agent name when the provider is bare `acp` (equivalent to `--acp-agent`) |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login` instead) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
+| Per-harness (e.g. `GEMINI_API_KEY` for `acp:gemini`) | ACP credentials — declared per agent in the registry (`credential_env`) |
+
+## Providers
+
+The agent supports multiple harness providers via `--provider` (or `STEERDEV_PROVIDER`):
+
+```bash
+steerdev run --provider claude --project-id abc123        # default (Claude Code)
+steerdev run --provider pi --project-id abc123            # pi.dev coding agent
+steerdev run --provider acp:gemini --project-id abc123    # any ACP harness (Gemini CLI here)
+steerdev run --provider openai-codex --project-id abc123  # stub (not yet wired)
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` is launched headless as `pi --mode json "<prompt>"`, with
+resume via `--session`, model via `--model`, and tool allow/deny lists via
+`--tools`/`--exclude-tools`; see `executor/pi.py` and `executor/pi_stream.py`.
+`openai-codex` is a clearly-stubbed seam (`executor/codex.py`) that fails fast
+with a "not yet supported" message.
+
+### ACP harnesses (`acp:<agent>`)
+
+`acp:<agent>` drives **any** harness speaking the
+[Agent Client Protocol](https://agentclientprotocol.com) (JSON-RPC 2.0 over
+stdio) through a single executor — steerdev acts as the ACP *Client*
+(filesystem, terminals, permissions) and the harness is the ACP *Agent*.
+Built-in registry entries (`executor/acp_registry.py`): `acp:gemini`
+(Gemini CLI via `gemini --experimental-acp`), `acp:claude-code` (via
+`npx @zed-industries/claude-code-acp`), `acp:goose` (`goose acp`).
+
+Adding a new harness requires **no code** — declare it under `acp.agents` in
+`steerdev.yaml`:
+
+```yaml
+acp:
+  # default agent for `--provider acp`
+  agent: gemini
+  # auto_approve_all (default) | auto_approve_workdir | read_only | escalate
+  permission_policy: auto_approve_all
+  agents:
+    myagent:
+      name: myagent
+      command: my-acp-agent
+      args: ["--serve"]
+      credential_env: ["MY_AGENT_API_KEY"]
+```
+
+Key modules: `executor/acp.py` (`ACPExecutor` — spawn, initialize,
+session/new|load, prompt), `executor/acp_client.py` (`SteerdevAcpClient` +
+`AcpPermissionPolicy` — fs/terminal/permission callbacks), `executor/acp_stream.py`
+(ACP `session/update` → canonical `EventType` translation), `executor/acp_spec.py`
++ `executor/acp_registry.py` (declarative launch specs). ACP turns end with a
+`stopReason`, not an exit code — `wait()` synthesizes one (nonzero only on
+refusal/error).
+
+Credentials arrive via ENV (the sandbox bootstrap injects them); the agent never
+fetches credentials itself. For providers with a persisted local login (`claude`,
+`pi`, and ACP agents with `requires_local_login`) a missing credential env var
+only warns; for the rest the matching env var must be present or the command
+hard-fails.

{steerdev-1.1.48 → steerdev-1.1.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerdev
-Version: 1.1.48
+Version: 1.1.62
 Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
 Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
 Project-URL: Repository, https://github.com/pentoai/steerdev-agent
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Terminals
 Requires-Python: >=3.12
+Requires-Dist: agent-client-protocol<0.11,>=0.10
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic-settings>=2.0.0
@@ -43,7 +44,7 @@ Task runner for [steerdev.com](https://steerdev.com) — orchestrates AI coding
 
 ## What It Does
 
-SteerDev Agent connects your AI coding agent (Claude Code, Codex, Aider) to the steerdev.com platform:
+SteerDev Agent connects your AI coding agent (Claude Code or pi; `openai-codex` is a stub) to the steerdev.com platform:
 
 1. **Fetches tasks** from your SteerDev project
 2. **Builds prompts** with project context, task details, and workflow instructions
@@ -299,7 +300,7 @@ api:
   project_id_env: STEERDEV_PROJECT_ID
 
 executor:
-  type: claude               # claude, codex, aider
+  type: claude               # claude (wired), pi (wired), openai-codex (stub)
   permission_mode: default
   allowed_tools: []
   disallowed_tools: []
@@ -316,8 +317,30 @@ worktrees:
 | `STEERDEV_API_KEY` | API key for steerdev.com |
 | `STEERDEV_PROJECT_ID` | Default project ID |
 | `STEERDEV_AGENT_NAME` | Agent name for session tracking |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex` |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login`) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
 
-> **Note:** CLI agents (Claude Code, Codex, etc.) must be logged in independently before running steerdev. No LLM API keys are needed here.
+> **Note:** Locally, CLI agents like Claude Code and pi can be logged in
+> independently (`claude login`, or `pi` + `/login`) before running steerdev — no
+> LLM API keys are strictly needed. In a sandbox, the bootstrap injects the
+> per-provider credentials above; steerdev never fetches credentials itself.
+
+### Providers
+
+Select the harness with `--provider` (or `STEERDEV_PROVIDER`). Defaults to `claude`:
+
+```bash
+steerdev run --provider claude --project-id YOUR_PROJECT_ID  # Claude Code
+steerdev run --provider pi --project-id YOUR_PROJECT_ID       # pi.dev coding agent
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` runs headless as `pi --mode json "<prompt>"` and streams
+its JSON events back to steerdev. `openai-codex` is a clearly-stubbed seam that
+fails fast with a "not yet supported" message, reserved for a future harness
+protocol.
 
 ## Architecture
 

{steerdev-1.1.48 → steerdev-1.1.62}/README.md

@@ -6,7 +6,7 @@ Task runner for [steerdev.com](https://steerdev.com) — orchestrates AI coding
 
 ## What It Does
 
-SteerDev Agent connects your AI coding agent (Claude Code, Codex, Aider) to the steerdev.com platform:
+SteerDev Agent connects your AI coding agent (Claude Code or pi; `openai-codex` is a stub) to the steerdev.com platform:
 
 1. **Fetches tasks** from your SteerDev project
 2. **Builds prompts** with project context, task details, and workflow instructions
@@ -262,7 +262,7 @@ api:
   project_id_env: STEERDEV_PROJECT_ID
 
 executor:
-  type: claude               # claude, codex, aider
+  type: claude               # claude (wired), pi (wired), openai-codex (stub)
   permission_mode: default
   allowed_tools: []
   disallowed_tools: []
@@ -279,8 +279,30 @@ worktrees:
 | `STEERDEV_API_KEY` | API key for steerdev.com |
 | `STEERDEV_PROJECT_ID` | Default project ID |
 | `STEERDEV_AGENT_NAME` | Agent name for session tracking |
+| `STEERDEV_PROVIDER` | Harness provider: `claude` (default), `pi`, `openai-codex` |
+| `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` | Claude credentials (sandbox-injected; locally use `claude login`) |
+| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `GEMINI_API_KEY` | pi credentials — whichever matches the selected model's provider (sandbox-injected; locally use `pi` + `/login`) |
+| `OPENAI_API_KEY` | Codex credentials for `openai-codex` (sandbox-injected) |
 
-> **Note:** CLI agents (Claude Code, Codex, etc.) must be logged in independently before running steerdev. No LLM API keys are needed here.
+> **Note:** Locally, CLI agents like Claude Code and pi can be logged in
+> independently (`claude login`, or `pi` + `/login`) before running steerdev — no
+> LLM API keys are strictly needed. In a sandbox, the bootstrap injects the
+> per-provider credentials above; steerdev never fetches credentials itself.
+
+### Providers
+
+Select the harness with `--provider` (or `STEERDEV_PROVIDER`). Defaults to `claude`:
+
+```bash
+steerdev run --provider claude --project-id YOUR_PROJECT_ID  # Claude Code
+steerdev run --provider pi --project-id YOUR_PROJECT_ID       # pi.dev coding agent
+```
+
+`claude` (Claude Code) and `pi` (the [pi.dev](https://pi.dev) coding agent) are
+wired end-to-end. `pi` runs headless as `pi --mode json "<prompt>"` and streams
+its JSON events back to steerdev. `openai-codex` is a clearly-stubbed seam that
+fails fast with a "not yet supported" message, reserved for a future harness
+protocol.
 
 ## Architecture