116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# Custodian Agent Runtime — v0.1
|
||
|
||
Single-pass OODA agent loop. Observes project state via the State Hub, reasons
|
||
about it with an LLM, and executes bounded write operations.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
agent.py CLI entry point + OODA orchestrator
|
||
context.py Observe: fetch state-hub data + build LLM context prompt
|
||
actions.py Act: execute sanctioned write operations
|
||
prompts/ System prompt templates and recurring review prompts
|
||
policies/ Agent-level policies (future)
|
||
tool_adapters/ Additional MCP/API tool adapters (future)
|
||
tests/ Unit tests (offline, no live API required)
|
||
```
|
||
|
||
See `canon/architecture/adr-002-custodian-agent-runtime-design.md` for
|
||
all architectural decisions.
|
||
|
||
## OODA Loop
|
||
|
||
```
|
||
Observe → fetch_state(domain) # HTTP GET /state/summary or /state/domain/{slug}
|
||
Orient → load_constitution() # reads canon/constitution/
|
||
build_context(state, const) # assembles LLM prompt
|
||
Decide → LLM call via llm-connect # returns markdown + JSON action plan
|
||
Act → parse_plan(response) # extract JSON block
|
||
execute(plan) # run sanctioned writes
|
||
```
|
||
|
||
## Sanctioned Write Operations (ADR-002 D4)
|
||
|
||
Only three operations may be executed without human approval:
|
||
|
||
| Operation | State-hub endpoint | Reversible |
|
||
|---|---|---|
|
||
| `add_progress_event` | `POST /progress/` | Yes (append-only log) |
|
||
| `update_task_status` | `PATCH /tasks/{id}/` | Yes |
|
||
| `flag_for_human` | `PATCH /tasks/{id}/` | Yes (clear with `clear_human_flag`) |
|
||
|
||
## Prerequisites
|
||
|
||
- State-hub running: `cd state-hub && make api`
|
||
- LLM available: `claude` CLI in PATH (for default `claude-code` provider)
|
||
or set `OPENROUTER_API_KEY` / `GEMINI_API_KEY` for other providers
|
||
|
||
## Install
|
||
|
||
```bash
|
||
cd runtime
|
||
uv sync
|
||
```
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
cd runtime
|
||
|
||
# Focus on custodian domain (cheaper — ~10% of full summary tokens)
|
||
uv run python agent.py --domain custodian
|
||
|
||
# Full cross-domain view
|
||
uv run python agent.py --all
|
||
|
||
# Preview actions without executing
|
||
uv run python agent.py --domain custodian --dry-run
|
||
|
||
# Use a different LLM provider
|
||
uv run python agent.py --domain custodian --llm gemini
|
||
uv run python agent.py --domain custodian --llm openrouter
|
||
|
||
# Custom state-hub URL
|
||
uv run python agent.py --domain custodian --api-base http://10.0.0.5:8000
|
||
```
|
||
|
||
## Output
|
||
|
||
The agent prints a trace to stdout:
|
||
|
||
```
|
||
[custodian-agent] 2026-03-12T20:00:00 scope=domain=custodian
|
||
[observe] fetching state from state-hub…
|
||
[orient] loading constitution and building context…
|
||
[decide] calling LLM via provider='claude-code'…
|
||
[act] executing plan (live): 1 events, 0 task updates, 0 flags
|
||
✓ add_progress_event: 'Reviewed custodian domain: 2 active workstreams…'
|
||
[custodian-agent] done — 1 actions.
|
||
```
|
||
|
||
The LLM's reasoning trace is saved to `memory/working/agent-session-{ts}-{scope}.md`.
|
||
|
||
Recurring review prompts:
|
||
|
||
- `prompts/daily_statehub_wsgi_triage.md` - daily State Hub WSJF triage used by
|
||
the `daily-state-hub-wsjf-triage` automation and the activity-core handoff
|
||
definition in `../activity-definitions/`.
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
cd runtime
|
||
uv run pytest -v
|
||
```
|
||
|
||
All 32 tests run offline (no live state-hub, no LLM API key required).
|
||
|
||
## Extending
|
||
|
||
- **New observations**: extend `build_context()` in `context.py`
|
||
- **New actions**: add to `actions.py` and update `SANCTIONED_ACTIONS` — but
|
||
any expansion of the action surface requires a new ADR and human approval
|
||
(see constitution §2–§4)
|
||
- **Tool adapters**: add to `tool_adapters/` following the llm-connect
|
||
`LLMAdapter` pattern
|