Skip to content

feat: serve the orchestrator's work list over HTTP - #218

Merged
outofcoffee merged 3 commits into
mainfrom
orchestrator-work-api
Sep 14, 2026
Merged

outofcoffee merged 3 commits into
mainfrom
orchestrator-work-api

Conversation

@outofcoffee

@outofcoffee outofcoffee commented Sep 14, 2026

Copy link
Copy Markdown
Collaborator

The orchestrator's work list gets a front door: a pluggable state store and an HTTP API another client can query and mutate, the gateway's server pattern port for port.

Summary

  • The orchestrator's state store becomes a Store interface — the per-item records, the per-item logs, the lock, the restart recovery — with the file-backed store as the default implementation; the existing state and lock behaviour is unchanged
  • The orchestrator serves the work list over HTTP, the spinloop gateway pattern: --listen (default :4010), -l/--loopback (loopback on the default port, no token), --api-token/--api-token-file resolved the daemon's way, a non-loopback bind refused without a token, bearer on every path, unknown paths 404 naming the surface
  • The API answers GET /v1/items, GET /v1/items/{id}/log, POST /v1/items, DELETE /v1/items/{id}, and POST /v1/items/{id}/abort, each with the validation and refusal the items file and the run give today
  • spinloop orchestrator gains the four server flags, stands the server before the run's first pass, takes it down with the clean interrupt after the agents are stopped, and prints the work list's address beside its banner
  • Spec delta on fleet-orchestrator: "The orchestrator command" modified with the server flags, new requirement "Serving the work list API" (openspec/changes/add-orchestrator-work-api, all tasks done)

Implementation details

  • The API lives in the orchestrator process rather than a separate command: the mutations need the in-flight children (an abort stops one) and the lock (a second opener is refused by design)
  • The items file stays the source of truth for items: the API's add and remove write back to it — parse, change, validate, write — and the state file keeps owning only the records
  • The loop and the API act on one core — records, in-flight, and the items view under one mutex — so a client cannot race the run over the files
  • An abort stops the agent the way a clean interrupt stops it — the polite signal, the grace, then the hard end — and puts the item back in the backlog, where the run admits it again

Verification

  • New tests: the API's paths, bearer on every path, every mutation's acceptances and refusals over a fake store, a two-goroutine race test over the shared core, a loop-versus-API integration test, and the command's server lifecycle (conflict, tokenless refusal, token resolution, loopback serving, clean interrupt)
  • examples/gateway-docker gains an orchestrator work list scenario beside the existing backlog scenario; the existing scenario takes -l, the default bind now being token-gated
  • go build, go vet, gofmt clean; go test ./... green, coverage at or above 80% everywhere it was before
  • Docs: the orchestrator command reference documents the API's paths, refusals, and token, and work-items.md points a client at it

The first clients are the work commands (#206-#209); none of them is built here.

@outofcoffee outofcoffee added the enhancement New feature or request label Sep 14, 2026
@outofcoffee outofcoffee changed the title docs: propose the orchestrator's work list API feat: serve the orchestrator's work list over HTTP Sep 14, 2026
@outofcoffee
outofcoffee marked this pull request as ready for review September 14, 2026 18:53
@outofcoffee
outofcoffee merged commit bd22b36 into main Sep 14, 2026
3 checks passed
@outofcoffee
outofcoffee deleted the orchestrator-work-api branch September 14, 2026 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant