foreman/progress.md

foreman — progress

Phase 1: Scaffold — 2026-05-23

• Go module initialized (gitea.stevedudenhoeffer.com/steve/foreman)
• Project layout: cmd/foreman/, internal/config/, internal/store/, internal/server/
• internal/config: loads all FOREMAN_* env vars with defaults and validation
• internal/store: SQLite-backed durable queue (WAL mode, modernc.org/sqlite)
  • jobs table: ULID PK, model, payload, state machine, retry tracking, timestamps
  • artifacts table: named typed blobs per job, unique on (job_id, name)
  • Full CRUD: CreateJob, GetJob, UpdateJobState, ListJobs, CreateArtifact, GetArtifact, GetArtifactsByJob
• internal/server: stdlib net/http server
  • GET /healthz returning {"status":"ok","degraded":false}
  • Optional bearer-token auth middleware (skips /healthz)
• cmd/foreman/main.go: subcommand dispatch (serve + stubs for submit, jobs, ps)
• CI: .gitea/workflows/ci.yaml (build, vet, test -race, tidy check)
• Dockerfile: multi-stage distroless build
• Config files: .env.example, .gitignore
• Tests: config validation, store CRUD + edge cases, server health + auth middleware

Phase 2: Ollama target client, model poller, native passthrough — 2026-05-23

• internal/ollama/ — target client package:
  • Wire types (types.go): ChatRequest/Response, EmbedRequest/Response, TagsResponse, PsResponse, ModelInfo, RunningModel — matching Ollama's native JSON API exactly. Polymorphic fields (think, keep_alive, tools, options) use json.RawMessage for transparent passthrough fidelity.
  • Client interface (client.go): Chat (stream/non-stream), Embed, Tags, Ps, RawChat, RawEmbed. RawChat/RawEmbed return *http.Response for zero-copy streaming passthrough.
  • httpClient implementation: auth token injection, NDJSON streaming via bufio.Scanner with 4 MB buffer, connection vs HTTP error classification.
  • Custom error types (errors.go): *ConnectionError for network failures (retry-eligible), *HTTPError for non-2xx responses. errors.Is/errors.As compatible.
  • ModelInventory (inventory.go): mutex-protected in-memory cache of installed and running models. Methods: Models(), HasModel(), ResidentModels(), LastPoll(), Degraded(), Refresh(). Background Start() goroutine polls at FOREMAN_POLL_INTERVAL (default 30s). On target unreachable: retains last-known inventory, sets degraded=true. Clears degraded on recovery.
• internal/server/ — new Ollama passthrough routes:
  • GET /api/tags — serves poller's cached model list
  • GET /api/ps — serves poller's cached running models
  • POST /api/embed, POST /api/embeddings — direct concurrent proxy to target, bypasses the chat gate entirely (ADR-0013)
  • POST /api/chat — critical path: validates model (re-poll on miss, 404 if still absent), serializes through a capacity-1 channel gate, proxies to target with NDJSON streaming (application/x-ndjson, flushed per chunk) or non-streaming JSON passthrough
  • GET /healthz — now wired to inventory.Degraded() for real target status
• cmd/foreman/main.go — full serve wiring:
  • Creates Ollama client, starts model poller goroutine, warms embedder (keep_alive: -1), creates server with all dependencies, signal-based graceful shutdown via context.NotifyContext
• Tests (all passing with -race):
  • Client: tags/ps parsing, chat streaming + non-streaming, embed, auth token forwarding, *ConnectionError on unreachable target, *HTTPError on non-2xx
  • Inventory: refresh populates models, degraded on failure, model retention, recovery from degraded, Start/cancel lifecycle
  • Server: tags/ps passthrough, model validation (404 on unknown), non-streaming chat proxy, NDJSON streaming passthrough with correct Content-Type, chat serialization (gate holds concurrent requests to max 1 in-flight), concurrent embed bypass (multiple requests run in parallel), degraded health endpoint, embeddings alias path

The Mac is now usable as a go-llm target through foreman: llm.OllamaCloud(token, WithBaseURL("http://foreman:8080")) works transparently for chat (streaming + non-streaming), tags, ps, and embeddings.