docs: restructure docs into diataxis (#121)
This commit is contained in:
banteg
@@ -0,0 +1,382 @@
|
||||
Below is a concrete implementation spec for the **Anthropic Claude Code (“claude” CLI / Agent SDK runtime)** runner shipped in Takopi (v0.3.0).
|
||||
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
### Goal
|
||||
|
||||
Provide the **`claude`** engine backend so Takopi can:
|
||||
|
||||
* Run Claude Code non-interactively via the **Agent SDK CLI** (`claude -p`). ([Claude Code][1])
|
||||
* Stream progress in Telegram by parsing **`--output-format stream-json --verbose`** (newline-delimited JSON). Note: `--output-format` only works with `-p/--print`. ([Claude Code][1])
|
||||
* Support resumable sessions via **`--resume <session_id>`** (Takopi emits a canonical resume line the user can reply with). ([Claude Code][1])
|
||||
|
||||
### Non-goals (v1)
|
||||
|
||||
* Interactive Q&A inside a single run (e.g., answering `AskUserQuestion` prompts mid-flight).
|
||||
* Full “slash commands” integration (Claude Code docs note many slash commands are interactive-only). ([Claude Code][1])
|
||||
* MCP prompt-handling for permissions (use allow rules instead).
|
||||
|
||||
---
|
||||
|
||||
## UX and behavior
|
||||
|
||||
### Engine selection
|
||||
|
||||
* Default: `takopi` (auto-router uses `default_engine` from config)
|
||||
* Override: `takopi claude`
|
||||
|
||||
Takopi runs in auto-router mode by default; `takopi claude` or `/claude` selects
|
||||
Claude for new threads.
|
||||
|
||||
### Resume UX (canonical line)
|
||||
|
||||
Takopi appends a **single backticked** resume line at the end of the message, like:
|
||||
|
||||
```text
|
||||
`claude --resume 8b2d2b30-...`
|
||||
```
|
||||
|
||||
Rationale:
|
||||
|
||||
* Claude Code supports resuming a specific conversation by session ID with `--resume`. ([Claude Code][1])
|
||||
* The CLI reference also documents `--resume/-r` as the resume mechanism.
|
||||
|
||||
Takopi should parse either:
|
||||
|
||||
* `claude --resume <id>`
|
||||
* `claude -r <id>` (short form from docs)
|
||||
|
||||
**Note:** Claude session IDs should be treated as **opaque strings**. Do not assume UUID format.
|
||||
|
||||
### Permissions / non-interactive runs
|
||||
|
||||
In `-p` mode, Claude Code can require tool approvals. Takopi cannot click/answer interactive prompts, so **users must preconfigure permissions** (via Claude Code settings or `--allowedTools`). Claude’s settings system supports allow/deny tool rules. ([Claude Code][2])
|
||||
|
||||
**Safety note:** `-p/--print` skips the workspace trust dialog; only use this flag in trusted directories.
|
||||
|
||||
Takopi should document this clearly: if permissions aren’t configured and Claude tries to use a gated tool, the run may block or fail.
|
||||
|
||||
---
|
||||
|
||||
## Config additions
|
||||
|
||||
Takopi config lives at `~/.takopi/takopi.toml`.
|
||||
|
||||
Add a new optional `[claude]` section.
|
||||
|
||||
Recommended v1 schema:
|
||||
|
||||
```toml
|
||||
# ~/.takopi/takopi.toml
|
||||
|
||||
default_engine = "claude"
|
||||
|
||||
[claude]
|
||||
model = "claude-sonnet-4-5-20250929" # optional (Claude Code supports model override in settings too)
|
||||
allowed_tools = ["Bash", "Read", "Edit", "Write"] # optional but strongly recommended for automation
|
||||
dangerously_skip_permissions = false # optional (high risk; prefer sandbox use only)
|
||||
use_api_billing = false # optional (keep ANTHROPIC_API_KEY for API billing)
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
* `--allowedTools` exists specifically to auto-approve tools in programmatic runs. ([Claude Code][1])
|
||||
* Claude Code tools (Bash/Edit/Write/WebSearch/etc.) and whether permission is required are documented. ([Claude Code][2])
|
||||
* If `allowed_tools` is omitted, Takopi defaults to `["Bash", "Read", "Edit", "Write"]`.
|
||||
* Takopi only reads `model`, `allowed_tools`, `dangerously_skip_permissions`, and `use_api_billing` from `[claude]`.
|
||||
* By default Takopi strips `ANTHROPIC_API_KEY` from the subprocess environment so Claude uses subscription billing. Set `use_api_billing = true` to keep the key.
|
||||
|
||||
---
|
||||
|
||||
## Code changes (by file)
|
||||
|
||||
### 1) New file: `src/takopi/runners/claude.py`
|
||||
|
||||
#### Backend export
|
||||
|
||||
Expose a module-level `BACKEND = EngineBackend(...)` (from `takopi.backends`).
|
||||
Takopi auto-discovers runners by importing `takopi.runners.*` and looking for
|
||||
`BACKEND`.
|
||||
|
||||
`BACKEND` should provide:
|
||||
|
||||
* Engine id: `"claude"`
|
||||
* `install_cmd`:
|
||||
* Install command for `claude` (used by onboarding when missing on PATH).
|
||||
* Error message should include official install options and “run `claude` once to authenticate”.
|
||||
|
||||
* Install methods include install scripts, Homebrew, and npm. ([Claude Code][4])
|
||||
* Agent SDK / CLI can use Claude Code authentication from running `claude`, or API key auth. ([Claude][5])
|
||||
|
||||
* `build_runner()` should parse `[claude]` config and instantiate `ClaudeRunner`.
|
||||
|
||||
#### Runner implementation
|
||||
|
||||
Implement a new `Runner`:
|
||||
|
||||
#### Public API
|
||||
|
||||
* `engine: EngineId = "claude"`
|
||||
* `format_resume(token) -> str`: returns `` `claude --resume {token}` ``
|
||||
* `extract_resume(text) -> ResumeToken | None`: parse last match of `--resume/-r`
|
||||
* `is_resume_line(line) -> bool`: matches the above patterns
|
||||
* `run(prompt, resume)` async generator of `TakopiEvent`
|
||||
|
||||
#### Subprocess invocation
|
||||
|
||||
Use Agent SDK CLI non-interactively:
|
||||
|
||||
Core invocation:
|
||||
|
||||
* `claude -p --output-format stream-json --verbose` ([Claude Code][1])
|
||||
* `--verbose` overrides config and is required for full stream-json output.
|
||||
|
||||
Resume:
|
||||
|
||||
* add `--resume <session_id>` if resuming. ([Claude Code][1])
|
||||
|
||||
Model:
|
||||
|
||||
* add `--model <name>` if configured. ([Claude Code][1])
|
||||
|
||||
Permissions:
|
||||
|
||||
* add `--allowedTools "<rules>"` if configured. ([Claude Code][1])
|
||||
* add `--dangerously-skip-permissions` only if explicitly enabled (high risk; document clearly).
|
||||
|
||||
Prompt passing:
|
||||
|
||||
* Pass the prompt as the final positional argument after `--` (CLI expects `prompt` as an argument). This also protects prompts that begin with `-`. ([Claude Code][1])
|
||||
|
||||
Other flags:
|
||||
|
||||
* Claude exposes more CLI flags, but Takopi does not surface them in config.
|
||||
|
||||
#### Stream parsing
|
||||
|
||||
In stream-json mode, Claude emits newline-delimited JSON objects. ([Claude Code][1])
|
||||
|
||||
Per the official Agent SDK TypeScript reference, message types include:
|
||||
|
||||
* `system` with `subtype: 'init'` and fields like `session_id`, `cwd`, `tools`, `model`, `permissionMode`, `output_style`. ([Claude Code][3])
|
||||
* `assistant` / `user` messages with Anthropic SDK message objects. ([Claude Code][3])
|
||||
* final `result` message with:
|
||||
|
||||
* `subtype: 'success'` or error subtype(s),
|
||||
* `is_error`,
|
||||
* `result` (string on success),
|
||||
* `usage`, `total_cost_usd`, `modelUsage`,
|
||||
* `errors` list on failures,
|
||||
* `permission_denials`. ([Claude Code][3])
|
||||
|
||||
Takopi should:
|
||||
|
||||
* Parse each line as JSON; on decode error emit a warning ActionEvent (like CodexRunner does) and continue.
|
||||
* Prefer stdout for JSON; log stderr separately (do not merge).
|
||||
* Treat unknown top-level fields (e.g., `parent_tool_use_id`) as optional metadata and ignore them unless needed.
|
||||
|
||||
#### Mapping to Takopi events
|
||||
|
||||
**StartedEvent**
|
||||
|
||||
* Emit upon first `system/init` message:
|
||||
|
||||
* `resume = ResumeToken(engine="claude", value=session_id)`
|
||||
(treat `session_id` as opaque; do not validate as UUID)
|
||||
* `title = model` (or user-specified config title; default `"claude"`)
|
||||
* `meta` should include `cwd`, `tools`, `permissionMode`, `output_style` for debugging.
|
||||
|
||||
**Action events (progress)**
|
||||
The core useful progress comes from tool usage.
|
||||
|
||||
Claude Code tools list is documented (Bash/Edit/Write/WebSearch/WebFetch/TodoWrite/Task/etc.). ([Claude Code][2])
|
||||
|
||||
Strategy:
|
||||
|
||||
* When you see an **assistant message** with a content block `type: "tool_use"`:
|
||||
|
||||
* Emit `ActionEvent(phase="started")` with:
|
||||
|
||||
* `action.id = tool_use.id`
|
||||
* `action.kind` based on tool name (complete mapping):
|
||||
|
||||
* `Bash` → `command`
|
||||
* `Edit`/`Write`/`NotebookEdit` → `file_change` (best-effort path extraction)
|
||||
* `Read` → `tool`
|
||||
* `Glob`/`Grep` → `tool`
|
||||
* `WebSearch`/`WebFetch` → `web_search`
|
||||
* `TodoWrite`/`TodoRead` → `note`
|
||||
* `AskUserQuestion` → `note`
|
||||
* `Task`/`Agent` → `tool`
|
||||
* `KillShell` → `command`
|
||||
* otherwise → `tool`
|
||||
* `action.title`:
|
||||
|
||||
* Bash: use `input.command` if present
|
||||
* Read/Write/Edit/NotebookEdit: use file path (best-effort; field may be `file_path` or `path`)
|
||||
* Glob/Grep: use pattern
|
||||
* WebSearch: use query
|
||||
* WebFetch: use URL
|
||||
* TodoWrite/TodoRead: short summary (e.g., “update todos”)
|
||||
* AskUserQuestion: short summary (e.g., “ask user”)
|
||||
* otherwise: tool name
|
||||
* `detail` includes a compacted copy of input (or a safe summary).
|
||||
|
||||
* When you see a **user message** with a content block `type: "tool_result"`:
|
||||
|
||||
* Emit `ActionEvent(phase="completed")` for `tool_use_id`
|
||||
* `ok = not is_error`
|
||||
* `content` may be a string or an array of content blocks; normalize to a string for summaries
|
||||
* `detail` includes a small summary (char count / first line / “(truncated)”)
|
||||
|
||||
This mirrors CodexRunner’s “started → completed” item tracking and renders well in existing `TakopiProgressRenderer`.
|
||||
|
||||
**CompletedEvent**
|
||||
|
||||
* Emit on `result` message:
|
||||
|
||||
* `ok = (is_error == false)` (treat `is_error` as authoritative; `subtype` is informational)
|
||||
* `answer = result` on success; on error, a concise message using `errors` and/or denials
|
||||
* `usage` attach:
|
||||
|
||||
* `total_cost_usd`, `usage`, `modelUsage`, `duration_ms`, `duration_api_ms`, `num_turns` ([Claude Code][3])
|
||||
* Always include `resume` (same session_id).
|
||||
* Emit exactly one completed event per run. After emitting it, ignore any
|
||||
trailing JSON lines (do not emit a second completion).
|
||||
* We do not use an idle-timeout completion; completion is driven by Claude’s
|
||||
`result` event or process exit handling.
|
||||
|
||||
**Permission denials**
|
||||
Because result includes `permission_denials`, optionally emit warning ActionEvent(s) *before* CompletedEvent (CompletedEvent must be final):
|
||||
|
||||
* kind: `warning`
|
||||
* title: “permission denied: <tool_name>”
|
||||
This preserves the “warnings before started/completed” ordering principle Takopi already tests for CodexRunner.
|
||||
|
||||
#### Session serialization / locks
|
||||
|
||||
Must match Takopi runner contract:
|
||||
|
||||
* Lock key: `claude:<session_id>` (string) in a `WeakValueDictionary` of `anyio.Lock`.
|
||||
* When resuming:
|
||||
|
||||
* acquire lock before spawning subprocess.
|
||||
* When starting a new session:
|
||||
|
||||
* you don’t know session_id until `system/init`, so:
|
||||
|
||||
* spawn process,
|
||||
* wait until the **first** `system/init`,
|
||||
* acquire lock for that session id **before** yielding StartedEvent,
|
||||
* then continue yielding.
|
||||
|
||||
This mirrors CodexRunner’s correct behavior and ensures “new run + resume run” serialize once the session is known.
|
||||
Assumption: Claude emits a single `system/init` per run. If multiple `init`
|
||||
events arrive, ignore the subsequent ones (do not attempt to re-lock).
|
||||
|
||||
#### Cancellation / termination
|
||||
|
||||
Reuse the existing subprocess lifecycle pattern (like `CodexRunner.manage_subprocess`):
|
||||
|
||||
* Kill the process group on cancellation
|
||||
* Drain stderr concurrently (log-only)
|
||||
* Ensure locks release in `finally`
|
||||
|
||||
## Documentation updates
|
||||
|
||||
### README
|
||||
|
||||
Add a “Claude Code engine” section that covers:
|
||||
|
||||
* Installation (install script / brew / npm). ([Claude Code][4])
|
||||
* Authentication:
|
||||
|
||||
* run `claude` once and follow prompts, or use API key auth (Agent SDK docs mention `ANTHROPIC_API_KEY`). ([Claude][5])
|
||||
* Non-interactive permission caveat + how to configure:
|
||||
|
||||
* settings allow/deny rules,
|
||||
* or `--allowedTools` / `[claude].allowed_tools`. ([Claude Code][2])
|
||||
* Resume format: `` `claude --resume <id>` ``.
|
||||
|
||||
### `docs/developing.md`
|
||||
|
||||
Extend “Adding a Runner” with:
|
||||
|
||||
* “ClaudeRunner parses Agent SDK stream-json output”
|
||||
* Mention key message types and the init/result messages.
|
||||
|
||||
---
|
||||
|
||||
## Test plan
|
||||
|
||||
Mirror the existing `CodexRunner` tests patterns.
|
||||
|
||||
### New tests: `tests/test_claude_runner.py`
|
||||
|
||||
1. **Contract & locking**
|
||||
|
||||
* `test_run_serializes_same_session` (stub `run_impl` like Codex tests)
|
||||
* `test_run_allows_parallel_new_sessions`
|
||||
* `test_run_serializes_new_session_after_session_is_known`:
|
||||
|
||||
* Provide a fake `claude` executable in tmp_path that:
|
||||
|
||||
* prints system/init with session_id,
|
||||
* then waits on a file gate,
|
||||
* a second invocation with `--resume` writes a marker file and exits,
|
||||
* assert the resume invocation doesn’t run until gate opens.
|
||||
|
||||
2. **Resume parsing**
|
||||
|
||||
* `format_resume` returns `claude --resume <id>`
|
||||
* `extract_resume` handles both `--resume` and `-r`
|
||||
|
||||
3. **Translation / event ordering**
|
||||
|
||||
* Fake `claude` outputs:
|
||||
|
||||
* system/init
|
||||
* assistant tool_use (Bash)
|
||||
* user tool_result
|
||||
* result success with `result: "ok"`
|
||||
* Assert Takopi yields:
|
||||
|
||||
* StartedEvent
|
||||
* ActionEvent started
|
||||
* ActionEvent completed
|
||||
* CompletedEvent(ok=True, answer="ok")
|
||||
|
||||
4. **Failure modes**
|
||||
|
||||
* `result` subtype error with `errors: [...]`:
|
||||
|
||||
* CompletedEvent(ok=False)
|
||||
* permission_denials exist:
|
||||
|
||||
* warning ActionEvent(s) emitted before CompletedEvent
|
||||
|
||||
5. **Cancellation**
|
||||
|
||||
* Stub `claude` that sleeps; ensure cancellation kills it (pattern already used for codex subprocess cancellation tests).
|
||||
|
||||
---
|
||||
|
||||
## Implementation checklist (v0.3.0)
|
||||
|
||||
* [x] Export `BACKEND = EngineBackend(...)` from `src/takopi/runners/claude.py`.
|
||||
* [x] Add `src/takopi/runners/claude.py` implementing the `Runner` protocol.
|
||||
* [x] Add tests + stub executable fixtures.
|
||||
* [x] Update README and developing docs.
|
||||
* [ ] Run full test suite before release.
|
||||
|
||||
---
|
||||
|
||||
If you want, I can also propose the exact **event-to-action mapping table** (tool → kind/title/detail rules) you should start with, based on Claude Code’s documented tool list (Bash/Edit/Write/WebSearch/etc.). ([Claude Code][2])
|
||||
|
||||
[1]: https://code.claude.com/docs/en/headless "Run Claude Code programmatically - Claude Code Docs"
|
||||
[2]: https://code.claude.com/docs/en/settings "Claude Code settings - Claude Code Docs"
|
||||
[3]: https://code.claude.com/docs/en/sdk/sdk-typescript "Agent SDK reference - TypeScript - Claude Docs"
|
||||
[4]: https://code.claude.com/docs/en/quickstart "Quickstart - Claude Code Docs"
|
||||
[5]: https://platform.claude.com/docs/en/agent-sdk/quickstart "Quickstart - Claude Docs"
|
||||
Reference in New Issue
Block a user