agent
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
---
|
|
name: agent_runner_api
|
|
lang: go
|
|
domain: agents
|
|
version: 0.1.0
|
|
description: "Service Go que orquesta agentes Claude headless en git worktrees con DoD"
|
|
tags: [service, agents, go, workflows, dod]
|
|
icon:
|
|
phosphor: "robot"
|
|
accent: "#3b82f6"
|
|
framework: "stdlib-http"
|
|
entry_point: "main.go"
|
|
dir_path: "apps/agent_runner_api"
|
|
repo_url: "https://gitea.organic-machine.com/dataforge/agent_runner_api"
|
|
uses_functions: []
|
|
uses_types: []
|
|
service:
|
|
port: 8486
|
|
health_endpoint: /api/health
|
|
health_timeout_s: 3
|
|
systemd_unit: agent_runner_api.service
|
|
systemd_scope: user
|
|
restart_policy: always
|
|
runtime: systemd-user
|
|
pc_targets:
|
|
- aurgi-pc
|
|
- home-wsl
|
|
is_local_only: true
|
|
e2e_checks:
|
|
- id: build
|
|
cmd: "CGO_ENABLED=1 go build -o agent_runner_api ."
|
|
timeout_s: 120
|
|
- id: smoke
|
|
cmd: "./agent_runner_api --port 8486 --db /tmp/agent_runner_api_e2e.db &"
|
|
health: "http://127.0.0.1:8486/api/health"
|
|
- id: tests
|
|
cmd: "go test -count=1 ./..."
|
|
---
|
|
|
|
## Visual
|
|
|
|
Backend puro, sin UI. Consume por skill_tree v2 + kanban_cpp.
|
|
|
|
## Endpoints
|
|
|
|
- `GET /api/health` — `{status, port, db}`.
|
|
- `POST /api/runs` — body `{issue_id?, card_id?, kanban_app?, mode, prompt?}` -> `{run_id, branch, worktree_path, sse_url}`. Crea worktree + lanza subprocess Claude (o `echo STUB:` si `AGENT_RUNNER_STUB=1`).
|
|
- `GET /api/runs?status=&app=&since=` — lista runs filtrada.
|
|
- `GET /api/runs/:id` — detalle + dod_items.
|
|
- `GET /api/runs/:id/sse` — stream `text/event-stream` (events: `connected`, `status`, `evidence`, `validated`, `merged`, `aborted`).
|
|
- `POST /api/runs/:id/evidence` — `{item_id|item_key, kind, payload_path?, payload_url?, payload_text?}`. Auto-crea `dod_item` si solo se da `item_key`.
|
|
- `POST /api/runs/:id/evidence/:eid/validate` — `{validated_by}`.
|
|
- `POST /api/runs/:id/merge` — TBD merge `auto/<branch>` a master `--no-ff` (gate: todos los `dod_items.required = 1` deben tener evidencia `validated`).
|
|
- `POST /api/runs/:id/abort` — kill PID + `git worktree remove --force` + `branch -D` + `status=aborted`.
|
|
|
|
## Schema (5 migrations idempotentes via embed.FS)
|
|
|
|
| Tabla | Para que |
|
|
|---|---|
|
|
| `workflows` | Templates de prompt + `dod_schema_json` |
|
|
| `runs` | Run vivo: workflow/issue/card/kanban_app + branch + worktree_path + PID + status |
|
|
| `worktrees` | 1 row por worktree creada, marcada `removed_at` al abort/merge |
|
|
| `dod_items` | Items DoD del run (`pending|done|validated|failed`) |
|
|
| `dod_evidence` | Evidencias adjuntas (`text|file|url`) con `validated_at/validated_by` |
|
|
|
|
## Lanzamiento
|
|
|
|
```bash
|
|
cd apps/agent_runner_api
|
|
CGO_ENABLED=1 go build -o agent_runner_api .
|
|
./agent_runner_api --port 8486 --db agent_runs.db --repo-root /home/lucas/fn_registry --worktrees-root /tmp
|
|
```
|
|
|
|
systemd-user: `systemctl --user enable --now agent_runner_api.service` (despues de copiar `agent_runner_api.service` a `~/.config/systemd/user/`).
|
|
|
|
## Gotchas
|
|
|
|
- `git worktree add` falla si la rama ya existe -> el `Spawn()` la borra antes con `branch -D` (best-effort).
|
|
- Worktree y main repo comparten `.git/hooks/` — pre-commit del main puede bloquear commits del agente; usar `--no-verify` documentado.
|
|
- `claude --headless` requiere PATH correcto en systemd. Si `claude` no esta en `$PATH`, el subprocess cae automaticamente a `echo STUB:` (mismo comportamiento que `AGENT_RUNNER_STUB=1`).
|
|
- Subprocess corre async — el handler HTTP devuelve `run_id` apenas inserta + lanza, no espera al exit.
|
|
- SSE: clientes deben reconectar al cerrar conexion. Heartbeat cada 15s para mantener conexion abierta.
|
|
|
|
## Capability growth log
|
|
|
|
- v0.1.0 (2026-05-18) — scaffold inicial: stdlib http, embed.FS migrations, SSE hub, spawn stub fallback, DoD gate en merge.
|