# AGENTS.md

## Repo layout
- `pipeline-runner/` — single Python package (FastAPI + uvicorn). All code lives here.
- `pipeline-runner/app.py` — FastAPI app entrypoint with REST API + WebSocket + static file serving.
- `pipeline-runner/main.py` — uvicorn dev server launcher (`python main.py`).
- `pipeline-runner/static/index.html` — frontend UI.
- `pipeline-runner/storage/pipelines/` — JSON files for persisted pipelines.
- `pipeline-runner/storage/logs/` — execution logs (one file per run).

## Dev commands
- Install deps: `cd pipeline-runner && pip install -r requirements.txt`
- Start dev server: `cd pipeline-runner && python main.py` (uvicorn with reload, port 8000)
- Deploy with auto-reload: `cd pipeline-runner && ./deploy.sh` (activates venv, installs deps, starts uvicorn with `--reload`)
- Run tests: `cd pipeline-runner && python -m pytest`
  - Tests use `httpx`-backed `TestClient` from FastAPI.
  - Tests that exercise pipeline execution (`TestExecutePipeline`) monkeypatch `asyncio.create_subprocess_exec` to avoid calling `opencode` — they do not require `opencode` to be installed.
  - The `clean_storage` fixture auto-removes `storage/pipelines/` and `storage/logs/` before/after each test.

## Key behaviors
- Pipeline execution runs `opencode run <prompt> --title <title>` per step via `asyncio.create_subprocess_exec`.
- Pipeline stops on first step error (non-zero return code).
- Real-time logs are streamed over WebSocket at `/ws/{run_id}`.
- CORS is open (`allow_origins=["*"]`) for dev convenience.
- No lint, typecheck, or formatter tooling is configured.