Files
pipelines/internal/server/AGENTS.md
T

3.2 KiB

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

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.