Files
pipelines/internal/server/AGENTS.md
T

55 lines
3.2 KiB
Markdown

# The Pipelines server — working map
Read this before touching `internal/server/`, `internal/stage/`, `internal/pipeline/` or
`internal/protocol/`. The generic half — how a Go service is built, tested and reviewed — belongs to
the pipeline that started you.
## Build and test
```sh
go build ./... && go vet ./...
go test ./internal/server # ~10-15 s
go test ./internal/stage ./internal/pipeline ./internal/protocol
go test ./... # ~1 min for everything; `gofmt -l .` must print nothing
```
## Where things are
- `internal/server/websocket.go` — the `/connect` transport and the request dispatch. Envelope
validation lives here; every command returns its own typed reply.
- `internal/server/home_files.go` — the contained `/files` endpoint for regular files under the operator home.
- `internal/server/runner.go` — run execution: the stage loop, stage outcomes, budgets, retries,
ownership and settlement. This is where a run's state changes.
- `internal/server/runevents.go` — the push hub: subscriptions scoped per workspace, per-run frames,
coalescing. Live clients fold these instead of polling.
- `internal/server/server_stats.go` and `server_stats_gpu.go` — bounded host, process, storage and GPU health sampling.
- `internal/server/chat_*.go` — the chat broker: `chat_sessions`, claims, the stream, permissions,
session registry.
- `internal/stage/` — one client per harness and stage type: `opencode.go` (native sessions),
`pi.go` (RPC), `model.go`, `agent.go`, `human.go` (decision stages), `ntfy.go` (notifications),
`model_prompt.go` (file-based turn prompt), `budget.go` (usage accounting). Model stages return
markdown for `output.md`; only its `# outcome` section is parsed (`internal/turn`).
- `internal/pipeline/` — the store: definitions and immutable versions, runs and steps, the
operator-session registry, retention, search.
- `internal/protocol/` — every wire shape. A new command means a message field here, documentation in
`docs/cli.md`, and tests both sides.
- `cmd/pipelines-server/main.go` — flags and wiring, including which OpenCode endpoint chat brokers
from (`-opencode-endpoint`, `PIPELINES_OPENCODE_ENDPOINT`, or the recorded choice).
## Checking behaviour without disturbing the live server
`scripts/run-local-server.sh` starts a scratch server, and the binary takes `-addr` and `-db`, so a
live check runs against a **scratch database and a free loopback port**. The operator's deployment is
`~/.local/share/pipelines` with the service on `0.0.0.0:8080` and ntfy on `8090`.
## Hard rules
- **Never restart, rebuild or redeploy the deployed server, ntfy or a running run** to test a change:
a restart kills every run in flight. Deploying is the operator's step.
- Commit locally only, never push.
- One run per workspace at a time — the server refuses a second one rather than sharing a tree.
- The service is durable: sessions, runs and definitions live in SQLite, so a migration must open an
existing database cleanly (see the `migrateRun*`/`addColumnIfMissing` pattern).
- Artifacts are inventoried with bounds (`internal/server/artifacts.go`: file count, per-file and total
size); a large file is served by direct URL, not by growing the inventory.