mlx-bun 0.0.4

package/src/jobs/db.ts

@@ -0,0 +1,139 @@
+// Job store: every background job (quantize / finetune / dataset) is a row
+// here (bun:sqlite, WAL). The runner streams NDJSON events to a per-job log
+// file and mirrors progress/message back onto the row so a status page can
+// read state without tailing logs. Port of optiq lab db.py's `jobs` table.
+//
+// WAL is load-bearing: the SSE poller reads while the job (or its child
+// process) writes — without WAL the reader and writer fight over the lock.
+
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { JobRow, JobStatus } from "./types";
+
+export const DEFAULT_JOBS_DB = `${process.env.HOME}/.cache/mlx-bun/jobs.sqlite`;
+export const DEFAULT_JOBS_DIR = `${process.env.HOME}/.cache/mlx-bun/jobs`;
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS jobs (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  status TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  progress REAL NOT NULL DEFAULT 0,
+  message TEXT,
+  log_path TEXT NOT NULL,
+  output_path TEXT,
+  error TEXT,
+  started_at TEXT NOT NULL DEFAULT (datetime('now')),
+  ended_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_jobs_status_started
+  ON jobs(status, started_at DESC);
+`;
+
+/** A new job id: `job_` + 16 hex chars from a CSPRNG (matches optiq's
+ *  `job_<uuid4 hex[:16]>` shape; collision-free enough for a local lab). */
+export function newJobId(): string {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return `job_${hex}`;
+}
+
+export class JobStore {
+  readonly db: Database;
+  readonly dbPath: string;
+  readonly logsDir: string;
+
+  constructor(dbPath: string = DEFAULT_JOBS_DB, logsDir: string = DEFAULT_JOBS_DIR) {
+    if (dbPath !== ":memory:") {
+      try { mkdirSync(dbPath.slice(0, dbPath.lastIndexOf("/")), { recursive: true }); } catch {}
+    }
+    try { mkdirSync(logsDir, { recursive: true }); } catch {}
+    this.dbPath = dbPath;
+    this.logsDir = logsDir;
+    this.db = new Database(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(SCHEMA);
+    this.migrate();
+  }
+
+  /** Additive-only migration: job rows are real records (a finished
+   *  quantize output is referenced by `output_path`), never dropped on
+   *  schema drift — unlike the registry cache. Re-opening an existing DB
+   *  is a no-op. */
+  private migrate(): void {
+    const cols = (this.db.query("PRAGMA table_info(jobs)").all() as { name: string }[])
+      .map((c) => c.name);
+    // No columns to add today; the hook stays so future fields are additive.
+    void cols;
+  }
+
+  /** Create a queued job. `log_path` is computed under `logsDir`; the file
+   *  is created so a tail started immediately sees an empty (not missing)
+   *  file. */
+  create(kind: string, config: Record<string, unknown>, outputPath?: string): JobRow {
+    const id = newJobId();
+    const logPath = join(this.logsDir, `${id}.log`);
+    // touch the log so tailJob's first read finds an (empty) file
+    try { Bun.write(logPath, ""); } catch {}
+    this.db.prepare(`
+      INSERT INTO jobs (id, kind, status, config_json, log_path, output_path)
+      VALUES (?, ?, 'queued', ?, ?, ?)
+    `).run(id, kind, JSON.stringify(config), logPath, outputPath ?? null);
+    return this.get(id)!;
+  }
+
+  get(id: string): JobRow | null {
+    return (this.db.query("SELECT * FROM jobs WHERE id = ?").get(id) as JobRow | null) ?? null;
+  }
+
+  recent(limit = 10, kind?: string): JobRow[] {
+    if (kind) {
+      return this.db
+        .query("SELECT * FROM jobs WHERE kind = ? ORDER BY started_at DESC LIMIT ?")
+        .all(kind, limit) as JobRow[];
+    }
+    return this.db
+      .query("SELECT * FROM jobs ORDER BY started_at DESC LIMIT ?")
+      .all(limit) as JobRow[];
+  }
+
+  setStatus(id: string, status: JobStatus, opts: { error?: string; endedAt?: string } = {}): void {
+    const sets = ["status = ?"];
+    const args: (string | null)[] = [status];
+    if (opts.error !== undefined) { sets.push("error = ?"); args.push(opts.error); }
+    if (opts.endedAt !== undefined) { sets.push("ended_at = ?"); args.push(opts.endedAt); }
+    args.push(id);
+    this.db.prepare(`UPDATE jobs SET ${sets.join(", ")} WHERE id = ?`).run(...args);
+  }
+
+  setProgress(id: string, progress: number, message?: string): void {
+    if (message !== undefined) {
+      this.db.prepare("UPDATE jobs SET progress = ?, message = ? WHERE id = ?")
+        .run(progress, message, id);
+    } else {
+      this.db.prepare("UPDATE jobs SET progress = ? WHERE id = ?").run(progress, id);
+    }
+  }
+
+  setOutputPath(id: string, p: string): void {
+    this.db.prepare("UPDATE jobs SET output_path = ? WHERE id = ?").run(p, id);
+  }
+
+  /** Boot recovery: any job left 'queued'/'running' from a previous process
+   *  lifetime is a zombie (its in-process task / child process died with us).
+   *  The UI surfaces these for cleanup. */
+  markZombies(): number {
+    const r = this.db
+      .prepare("UPDATE jobs SET status = 'zombie' WHERE status IN ('queued', 'running')")
+      .run();
+    return r.changes;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/jobs/index.ts

@@ -0,0 +1,29 @@
+// Public API for the background job system. The server imports from here:
+// create/track jobs (JobStore), submit work (in-process or GPU-leased
+// subprocess), gate inference on GPU jobs, and stream a job's log over SSE.
+
+export { JobStore, DEFAULT_JOBS_DB, DEFAULT_JOBS_DIR, newJobId } from "./db";
+export {
+  registerRunner,
+  getRunner,
+  submitInProcess,
+  submitSubprocess,
+  makeEmit,
+  isGpuBusy,
+  currentGpuJob,
+  drainQueue,
+  JOB_ENTRY_PATH,
+} from "./runner";
+export type { SubmitResult, SubprocessOpts } from "./runner";
+export { tailJob, streamJobResponse } from "./sse";
+export type { TailOpts } from "./sse";
+
+// Re-export the shared contract so consumers have one import site.
+export type {
+  JobEvent,
+  Emit,
+  JobRunner,
+  JobKind,
+  JobStatus,
+  JobRow,
+} from "./types";

package/src/jobs/job-entry.ts

@@ -0,0 +1,106 @@
+// Child-process job entry: `bun job-entry.ts <jobId>`.
+//
+// Spawned by submitSubprocess so MLX/GPU state lives in its own address space
+// and an uncatchable crash (segfault / process.exit) dies here without taking
+// the server down. Port of optiq lab jobs.py `_job_main` — opens its OWN
+// JobStore (a SQLite connection MUST NOT cross the process boundary), resolves
+// the runner, runs it with a log-appending emit, sets terminal status, and
+// exits 0 (done) / 1 (failed).
+
+import { JobStore } from "./db";
+import { getRunner, makeEmit } from "./runner";
+import type { JobRunner } from "./types";
+
+/** kind → module to dynamically import so it registers its runner. Real job
+ *  kinds are built by parallel efforts; importing the module is expected to
+ *  call `registerRunner(kind, ...)` at top level. Missing module ⇒ the job
+ *  fails cleanly (see resolveRunner). */
+const KIND_MODULES: Record<string, string> = {
+  quantize: "../quantize/job.ts",
+  finetune: "../train/job.ts",
+};
+
+/** Resolve a runner for `kind`. Test kinds (noop/crash) are pre-registered in
+ *  runner.ts. Real kinds are lazily imported; a missing module is a clean
+ *  failure, not a crash. */
+async function resolveRunner(kind: string): Promise<JobRunner> {
+  const existing = getRunner(kind);
+  if (existing) return existing;
+
+  const modPath = KIND_MODULES[kind];
+  if (modPath) {
+    try {
+      await import(modPath);
+    } catch (e) {
+      throw new Error(
+        `kind "${kind}": failed to load runner module ${modPath} ` +
+          `(${e instanceof Error ? e.message : String(e)})`,
+      );
+    }
+    const loaded = getRunner(kind);
+    if (loaded) return loaded;
+    throw new Error(`kind "${kind}": module ${modPath} did not register a runner`);
+  }
+  throw new Error(`no runner registered for kind "${kind}"`);
+}
+
+function nowIso(): string {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+async function main(): Promise<void> {
+  const jobId = process.argv[2];
+  if (!jobId) {
+    console.error("usage: bun job-entry.ts <jobId>");
+    process.exit(2);
+  }
+
+  // Own fresh connection — overrides come from env so a spawned child finds
+  // the same DB/logs the parent used (tests set these to a tmp dir).
+  const store = new JobStore(
+    process.env.MLX_BUN_JOBS_DB || undefined,
+    process.env.MLX_BUN_JOBS_DIR || undefined,
+  );
+
+  const row = store.get(jobId);
+  if (!row) {
+    console.error(`job ${jobId} not found`);
+    store.close();
+    process.exit(2);
+  }
+
+  const emit = makeEmit(store, jobId, row.log_path);
+  store.setStatus(jobId, "running");
+  emit({ type: "started", ts: Date.now() });
+
+  let config: Record<string, unknown>;
+  try {
+    config = JSON.parse(row.config_json) as Record<string, unknown>;
+  } catch (e) {
+    const error = `bad config_json: ${e instanceof Error ? e.message : String(e)}`;
+    store.setStatus(jobId, "failed", { error, endedAt: nowIso() });
+    emit({ type: "failed", error, ts: Date.now() });
+    store.close();
+    process.exit(1);
+  }
+
+  try {
+    const runner = await resolveRunner(row.kind);
+    const result = await runner(emit, config);
+    const out = result?.outputPath;
+    if (out) store.setOutputPath(jobId, out);
+    store.setProgress(jobId, 1);
+    store.setStatus(jobId, "done", { endedAt: nowIso() });
+    emit({ type: "done", ts: Date.now(), output_dir: out ?? row.output_path ?? undefined });
+    store.close();
+    process.exit(0);
+  } catch (e) {
+    const error = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+    store.setStatus(jobId, "failed", { error, endedAt: nowIso() });
+    emit({ type: "failed", error, ts: Date.now() });
+    store.close();
+    process.exit(1);
+  }
+}
+
+main();

package/src/jobs/runner.ts

@@ -0,0 +1,304 @@
+// Job runner: turns a registered `JobRunner` into a tracked, logged job.
+// Two execution modes — both create a row, both stream NDJSON events to the
+// log, both own terminal status:
+//
+//   submitInProcess   — runs the runner as a fire-and-forget async task in
+//                        THIS process. For pure-JS work (dataset builds) with
+//                        no MLX/GPU state to isolate.
+//   submitSubprocess  — spawns `bun job-entry.ts <jobId>` so MLX state is
+//                        isolated and an uncatchable crash (segfault,
+//                        process.exit) can't take the server down. Gated by a
+//                        single global GPU lease: only one MLX job runs at a
+//                        time; the rest wait 'queued' and drain in order.
+//
+// Port of optiq lab jobs.py `submit` + `_job_main`, split across this file
+// and job-entry.ts.
+
+import { appendFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Emit, JobEvent, JobRunner } from "./types";
+import type { JobStore } from "./db";
+
+/** Absolute path to the child-process entry (`bun job-entry.ts <jobId>`). */
+export const JOB_ENTRY_PATH = fileURLToPath(new URL("./job-entry.ts", import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Runner registry
+// ---------------------------------------------------------------------------
+
+const RUNNERS = new Map<string, JobRunner>();
+
+export function registerRunner(kind: string, run: JobRunner): void {
+  RUNNERS.set(kind, run);
+}
+
+export function getRunner(kind: string): JobRunner | undefined {
+  return RUNNERS.get(kind);
+}
+
+// Built-in test kinds. Real kinds (quantize/finetune) register their runner
+// on import of their module (see job-entry.ts KIND_MODULES).
+
+/** Emits a couple of stage events then resolves — exercises the happy path. */
+const noopRunner: JobRunner = async (emit) => {
+  emit({ type: "stage", stage: "warmup", progress: 0.25, message: "starting up" });
+  emit({ type: "stage", stage: "work", progress: 0.75, message: "doing the thing" });
+  return { outputPath: undefined };
+};
+
+/** Hard-exits the process — simulates an uncatchable crash (segfault-class).
+ *  Only meaningful under submitSubprocess: the child dies, the parent lives. */
+const crashRunner: JobRunner = async (emit) => {
+  emit({ type: "stage", stage: "boom", message: "about to crash" });
+  process.exit(1);
+};
+
+registerRunner("noop", noopRunner);
+registerRunner("crash", crashRunner);
+
+// ---------------------------------------------------------------------------
+// Emit factory
+// ---------------------------------------------------------------------------
+
+/** Build the `emit` sink for a job: appends each event as one NDJSON line
+ *  (line-buffered via appendFileSync for crash durability) and mirrors
+ *  progress/message from stage/metric events onto the row. Never throws — a
+ *  logging failure must not kill a job. The terminal `done`/`failed` status
+ *  is owned by the submit wrapper / job-entry, NOT here. */
+export function makeEmit(store: JobStore, jobId: string, logPath: string): Emit {
+  return (e: JobEvent) => {
+    try {
+      appendFileSync(logPath, JSON.stringify(e) + "\n");
+    } catch {
+      // swallow: a job must survive a logging hiccup
+    }
+    if (e.type === "stage" || e.type === "metric") {
+      const progress = typeof e.progress === "number" ? e.progress : undefined;
+      const message = typeof e.message === "string" ? e.message : undefined;
+      if (progress !== undefined || message !== undefined) {
+        try {
+          if (progress !== undefined) store.setProgress(jobId, progress, message);
+          else if (message !== undefined) {
+            // message-only update preserves current progress
+            store.db.prepare("UPDATE jobs SET message = ? WHERE id = ?").run(message, jobId);
+          }
+        } catch {
+          // swallow: DB contention must not kill a job
+        }
+      }
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// In-process submit
+// ---------------------------------------------------------------------------
+
+export interface SubmitResult {
+  jobId: string;
+  outputPath?: string;
+}
+
+/** Run a registered runner as a fire-and-forget async task in this process.
+ *  Sets 'running' + emits 'started' synchronously, then schedules the runner;
+ *  on success sets 'done'/progress 1/ended_at + emits 'done', on throw sets
+ *  'failed'/error/ended_at + emits 'failed'. Returns once the task is
+ *  scheduled (does not await completion — poll the row / tail the log). */
+export function submitInProcess(
+  store: JobStore,
+  kind: string,
+  config: Record<string, unknown>,
+  outputPath?: string,
+): SubmitResult {
+  const row = store.create(kind, config, outputPath);
+  const emit = makeEmit(store, row.id, row.log_path);
+  store.setStatus(row.id, "running");
+  emit({ type: "started", ts: Date.now() });
+
+  const runner = getRunner(kind);
+  void (async () => {
+    if (!runner) {
+      const error = `no runner registered for kind "${kind}"`;
+      store.setStatus(row.id, "failed", { error, endedAt: nowIso() });
+      emit({ type: "failed", error, ts: Date.now() });
+      return;
+    }
+    try {
+      const result = await runner(emit, JSON.parse(row.config_json));
+      const out = result?.outputPath;
+      if (out) store.setOutputPath(row.id, out);
+      store.setProgress(row.id, 1);
+      store.setStatus(row.id, "done", { endedAt: nowIso() });
+      emit({ type: "done", ts: Date.now(), output_dir: out ?? outputPath });
+    } catch (e) {
+      const error = errString(e);
+      store.setStatus(row.id, "failed", { error, endedAt: nowIso() });
+      emit({ type: "failed", error, ts: Date.now() });
+    }
+  })();
+
+  return { jobId: row.id, outputPath };
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess submit + single global GPU lease
+// ---------------------------------------------------------------------------
+
+interface QueuedSpawn {
+  store: JobStore;
+  jobId: string;
+  entry: string;
+  bin: string;
+}
+
+let gpuLeaseHolder: string | null = null;
+const spawnQueue: QueuedSpawn[] = [];
+
+/** True while a GPU (subprocess) job is running — the server gates token
+ *  generation on this so quantize/finetune don't fight live inference. */
+export function isGpuBusy(): boolean {
+  return gpuLeaseHolder !== null;
+}
+
+/** The job id currently holding the GPU lease, or null. */
+export function currentGpuJob(): string | null {
+  return gpuLeaseHolder;
+}
+
+export interface SubprocessOpts {
+  /** Override the entry script (tests). Defaults to JOB_ENTRY_PATH. */
+  entry?: string;
+  /** Override the runtime binary (tests). Defaults to "bun". */
+  bin?: string;
+}
+
+/** Create a 'queued' row and either spawn it now (lease free) or leave it
+ *  queued to drain when the lease frees. Returns immediately with the job id
+ *  — caller tails the log / polls the row. */
+export function submitSubprocess(
+  store: JobStore,
+  kind: string,
+  config: Record<string, unknown>,
+  outputPath?: string,
+  opts: SubprocessOpts = {},
+): SubmitResult {
+  const row = store.create(kind, config, outputPath);
+  const item: QueuedSpawn = {
+    store,
+    jobId: row.id,
+    entry: opts.entry ?? JOB_ENTRY_PATH,
+    bin: opts.bin ?? "bun",
+  };
+  if (gpuLeaseHolder === null) {
+    spawnNow(item);
+  } else {
+    spawnQueue.push(item);
+  }
+  return { jobId: row.id, outputPath };
+}
+
+/** Spawn the child, acquire the lease, stream stdout/stderr into the log,
+ *  reconcile terminal status on exit, then release the lease and drain. */
+function spawnNow(item: QueuedSpawn): void {
+  const { store, jobId, entry, bin } = item;
+  gpuLeaseHolder = jobId;
+
+  // The child opens its OWN JobStore over the SAME DB/logs — a sqlite
+  // connection can't cross the process boundary, so we hand the paths via
+  // env. A :memory: DB can't be shared with a child; subprocess jobs require
+  // a file-backed DB.
+  const proc = Bun.spawn([bin, entry, jobId], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      MLX_BUN_JOBS_DB: store.dbPath,
+      MLX_BUN_JOBS_DIR: store.logsDir,
+    },
+  });
+
+  const row = store.get(jobId);
+  const logPath = row?.log_path;
+  const logLine = (line: string) => {
+    if (!line || !logPath) return;
+    const ev: JobEvent = { type: "log", line };
+    try { appendFileSync(logPath, JSON.stringify(ev) + "\n"); } catch {}
+  };
+
+  void pumpLines(proc.stdout, logLine);
+  void pumpLines(proc.stderr, logLine);
+
+  void (async () => {
+    const code = await proc.exited;
+    // code 0 ⇒ trust the child's terminal status (it set done/failed itself).
+    // non-zero ⇒ if the row never reached terminal (crash before the wrapper
+    // could write), force it failed.
+    if (code !== 0) {
+      const cur = store.get(jobId);
+      if (cur && (cur.status === "queued" || cur.status === "running")) {
+        store.setStatus(jobId, "failed", {
+          error: `exited ${code}`,
+          endedAt: nowIso(),
+        });
+      }
+    }
+    releaseLease(jobId);
+    drainQueue();
+  })();
+}
+
+function releaseLease(jobId: string): void {
+  if (gpuLeaseHolder === jobId) gpuLeaseHolder = null;
+}
+
+/** Run the next queued subprocess job if the lease is free. */
+export function drainQueue(): void {
+  if (gpuLeaseHolder !== null) return;
+  const next = spawnQueue.shift();
+  if (next) spawnNow(next);
+}
+
+/** Read a child stream line-by-line, buffering partial trailing lines, and
+ *  hand each complete line to `sink`. */
+async function pumpLines(
+  stream: ReadableStream<Uint8Array> | undefined,
+  sink: (line: string) => void,
+): Promise<void> {
+  if (!stream) return;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        sink(buf.slice(0, nl));
+        buf = buf.slice(nl + 1);
+      }
+    }
+    buf += decoder.decode();
+    if (buf) sink(buf);
+  } catch {
+    // stream torn down with the process — nothing actionable
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function nowIso(): string {
+  // SQLite datetime('now') is "YYYY-MM-DD HH:MM:SS" in UTC — match it so the
+  // ended_at column is uniform whether set here or by a column default.
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+function errString(e: unknown): string {
+  if (e instanceof Error) return `${e.name}: ${e.message}`;
+  return String(e);
+}

package/src/jobs/sse.ts

@@ -0,0 +1,114 @@
+// Job log → SSE. `tailJob` is an async generator over a job's NDJSON log
+// (offset-seek read, partial-line tolerant, polls while the row is
+// non-terminal — port of optiq lab jobs.py `tail`). `streamJobResponse`
+// wraps it in a Bun `Response` whose body is an EventSource-compatible SSE
+// stream, matching the writer style in src/server.ts.
+
+import type { JobEvent, JobStatus } from "./types";
+import type { JobStore } from "./db";
+
+const TERMINAL: ReadonlySet<JobStatus> = new Set<JobStatus>(["done", "failed", "zombie"]);
+
+export interface TailOpts {
+  /** Keep polling while the job is non-terminal (SSE use case). When false,
+   *  yield what's currently logged and stop. */
+  follow?: boolean;
+  /** Poll interval in ms while waiting for new lines. */
+  pollMs?: number;
+}
+
+/** Yield each recorded JobEvent from a job's log in order. Reads from a held
+ *  byte offset, buffers a trailing partial line until its newline arrives
+ *  (tolerates a writer mid-line), and — when following — polls until the row
+ *  is terminal, then drains any final lines and stops. */
+export async function* tailJob(
+  store: JobStore,
+  jobId: string,
+  opts: TailOpts = {},
+): AsyncIterable<JobEvent> {
+  const follow = opts.follow ?? true;
+  const pollMs = opts.pollMs ?? 200;
+
+  const row = store.get(jobId);
+  if (!row) throw new Error(`job ${jobId} not found`);
+  const logPath = row.log_path;
+
+  let offset = 0;
+  let buf = "";
+
+  for (;;) {
+    const file = Bun.file(logPath);
+    const size = await file.size;
+    if (size > offset) {
+      const slice = file.slice(offset, size);
+      buf += await slice.text();
+      offset = size;
+
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        try {
+          yield JSON.parse(line) as JobEvent;
+        } catch {
+          // partial / corrupt line: re-buffer it and wait for more bytes
+          buf = line + "\n" + buf;
+          break;
+        }
+      }
+    }
+
+    if (!follow) return;
+
+    const status = store.get(jobId)?.status;
+    if (status && TERMINAL.has(status)) {
+      // Drain any bytes written between the last read and the terminal flip.
+      const f = Bun.file(logPath);
+      const sz = await f.size;
+      if (sz > offset) {
+        buf += await f.slice(offset, sz).text();
+        offset = sz;
+      }
+      for (const line of buf.split("\n")) {
+        const s = line.trim();
+        if (!s) continue;
+        try { yield JSON.parse(s) as JobEvent; } catch { /* drop trailing partial */ }
+      }
+      return;
+    }
+
+    await Bun.sleep(pollMs);
+  }
+}
+
+/** Build an SSE `Response` streaming a job's events. Writes `retry: 1500`
+ *  first (so EventSource fires `onopen`), then one `data:` frame per event,
+ *  and finally an `event: end` marker before closing on terminal. */
+export function streamJobResponse(store: JobStore, jobId: string): Response {
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const enc = new TextEncoder();
+      try {
+        controller.enqueue(enc.encode("retry: 1500\n\n"));
+        for await (const event of tailJob(store, jobId, { follow: true })) {
+          controller.enqueue(enc.encode(`data: ${JSON.stringify(event)}\n\n`));
+        }
+        controller.enqueue(enc.encode("event: end\ndata: {}\n\n"));
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        controller.enqueue(enc.encode(`data: ${JSON.stringify({ type: "failed", error, ts: Date.now() })}\n\n`));
+        controller.enqueue(enc.encode("event: end\ndata: {}\n\n"));
+      } finally {
+        controller.close();
+      }
+    },
+  });
+  return new Response(stream, {
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "keep-alive",
+    },
+  });
+}