feat: pull worker image on demand at spawn, with SSE progress (closes #38) #41

Merged
lz merged 11 commits from feat/worker-image-pull into main 2026-06-23 16:13:56 +02:00
Owner

Summary

Lets the operator obtain a worker image from the registry during workspace creation — choosing from a bundled catalog of official images or a custom tag — with live pull progress, without leaving the create form. Closes #38 (follow-up to #37, which decoupled onboarding from the worker image).

Approach: pre-pull, then unchanged spawn. A dedicated SSE endpoint pulls + streams progress; the transactional spawnWorker and its allowlist validation are left completely untouched. No new worker status, no async/background spawn, no reconcile-loop changes.

Flow

NewWorker Create → if the chosen tag isn't local, open EventSource('/api/worker-images/pull?tag=…') → render progress → on done, call the existing POST /api/workers. Any pull failure creates no worker row.

What's new

  • pullWorkerImage async generator (image-pull.ts) — present? → org.nexus.worker label check → docker.pull + followProgress → re-check label. Aborts the pull stream on client disconnect. 6 unit tests.
  • SSE endpoint GET /api/worker-images/pull?tag=… (text/event-stream); auth is the global /api/* hook, no extra gate.
  • Bundled catalog OFFICIAL_WORKER_IMAGES (Base + Playwright), registry-qualified.
  • pull.ts browser EventSource wrapper; PullProgress.svelte progress bar.
  • NewWorker.svelte: "Use existing / Pull a new image" mode, catalog + custom-tag, pull-before-spawn.
  • image-tag.ts: shared tag regex extracted from the settings validator.

Guarantees by construction

  • An image only reaches done if it carries org.nexus.worker=true — the exact filter listWorkerImages / spawn validation use — so a pulled image always passes the existing allowlist.
  • Anonymous pulls only (v1). Private-registry auth, live catalog, and a pulling status were explicitly scoped out.

Design spec + plan included under docs/superpowers/.

Test Plan

  • pnpm test — 550 pass (incl. new image-tag / image-pull / worker-images suites)
  • pnpm typecheck — 0 errors
  • pnpm lint — clean
  • pnpm build — success
  • Manual: in pull mode, pick a catalog image absent locally → Create shows the progress bar and the workspace appears on completion
  • Manual: enter a bogus custom tag → error toast, no workspace created
  • Manual: with ≥1 image present, "Use existing" still lists and spawns present images unchanged
## Summary Lets the operator obtain a worker image from the registry during workspace creation — choosing from a bundled catalog of official images or a custom tag — with live pull progress, without leaving the create form. Closes #38 (follow-up to #37, which decoupled onboarding from the worker image). **Approach:** pre-pull, then unchanged spawn. A dedicated SSE endpoint pulls + streams progress; the transactional `spawnWorker` and its allowlist validation are left **completely untouched**. No new worker status, no async/background spawn, no reconcile-loop changes. ### Flow `NewWorker` Create → if the chosen tag isn't local, open `EventSource('/api/worker-images/pull?tag=…')` → render progress → on `done`, call the existing `POST /api/workers`. Any pull failure creates **no** worker row. ### What's new - **`pullWorkerImage`** async generator (`image-pull.ts`) — present? → `org.nexus.worker` label check → `docker.pull` + `followProgress` → re-check label. Aborts the pull stream on client disconnect. 6 unit tests. - **SSE endpoint** `GET /api/worker-images/pull?tag=…` (`text/event-stream`); auth is the global `/api/*` hook, no extra gate. - **Bundled catalog** `OFFICIAL_WORKER_IMAGES` (Base + Playwright), registry-qualified. - **`pull.ts`** browser `EventSource` wrapper; **`PullProgress.svelte`** progress bar. - **`NewWorker.svelte`**: "Use existing / Pull a new image" mode, catalog + custom-tag, pull-before-spawn. - **`image-tag.ts`**: shared tag regex extracted from the settings validator. ### Guarantees by construction - An image only reaches `done` if it carries `org.nexus.worker=true` — the exact filter `listWorkerImages` / spawn validation use — so a pulled image always passes the existing allowlist. - Anonymous pulls only (v1). Private-registry auth, live catalog, and a `pulling` status were explicitly scoped out. Design spec + plan included under `docs/superpowers/`. ## Test Plan - [x] `pnpm test` — 550 pass (incl. new image-tag / image-pull / worker-images suites) - [x] `pnpm typecheck` — 0 errors - [x] `pnpm lint` — clean - [x] `pnpm build` — success - [ ] Manual: in pull mode, pick a catalog image absent locally → Create shows the progress bar and the workspace appears on completion - [ ] Manual: enter a bogus custom tag → error toast, no workspace created - [ ] Manual: with ≥1 image present, "Use existing" still lists and spawns present images unchanged
lz added 11 commits 2026-06-21 20:08:27 +02:00
Adds async-generator `pullWorkerImage` that checks local image presence,
pulls via dockerode if absent (forwarding progress events), and verifies
the org.nexus.worker label before yielding done/error. Includes `sseFrame`
helper to serialize PullEvents as SSE data frames.
refactor(ui): tidy worker-image label + derive pull presence from arg
Some checks failed
ci / nexus (pull_request) Successful in 2m39s
ci / images (./nexus, agent-nexus) (pull_request) Failing after 3m4s
ci / images (./worker, agent-nexus-worker, base) (pull_request) Successful in 1m14s
ci / images (PLAYWRIGHT_CLI_VERSION=0.1.13, ./worker, agent-nexus-worker, -playwright0.1.13, playwright) (pull_request) Successful in 1m9s
6b3c81eabd
lz merged commit b684398da1 into main 2026-06-23 16:13:56 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus!41
No description provided.