handzon-core 0.7.0 → 0.8.0

package/src/lib/progress/remote.ts

@@ -70,6 +70,14 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
   for (const id of Object.keys(prev.checkpoints)) {
     if (!next.checkpoints[id]) {
       out.push({ kind: "checkpoint", scope: "global", key: id, value: null });
+      // Family D: drop the matching kind:"verification" telemetry
+      // row so a re-attempt isn't pre-poisoned by the previous
+      // failure feedback. Scope comes from the feedback entry
+      // populated by SSE.
+      const feedback = prev.verificationFeedback[id];
+      if (feedback) {
+        out.push({ kind: "verification", scope: feedback.scope, key: id, value: null });
+      }
     }
   }
   for (const [k, value] of Object.entries(next.prefs)) {
@@ -95,6 +103,59 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
   return out;
 }
 
+/**
+ * Apply one server-side progress entry to a mutable state object.
+ * Shared by the initial snapshot fetch and the SSE per-event path.
+ * Mutates in place — callers replace the store atom after batching.
+ */
+function applyEntryInto(state: ProgressState, e: ProgressEntry): void {
+  if (e.kind === "step") {
+    state.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
+      | "incomplete"
+      | "complete";
+  } else if (e.kind === "quiz") {
+    state.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
+  } else if (e.kind === "checkpoint") {
+    if (e.value == null) {
+      delete state.checkpoints[e.key];
+      return;
+    }
+    state.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
+  } else if (e.kind === "pref") {
+    (state.prefs as Record<string, unknown>)[e.key] = e.value;
+  } else if (e.kind === "lastVisited") {
+    const v = e.value as unknown;
+    state.lastVisited[e.scope] =
+      typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
+  } else if (e.kind === "tutorial") {
+    const v = (e.value as { ts?: number }) ?? {};
+    const marker = state.tutorials[e.scope] ?? {};
+    if (e.key === "started") marker.started = v.ts;
+    else if (e.key === "completed") marker.completed = v.ts;
+    state.tutorials[e.scope] = marker;
+  } else if (e.kind === "verification") {
+    if (e.value == null) {
+      delete state.verificationFeedback[e.key];
+      return;
+    }
+    const v = e.value as {
+      pass: boolean;
+      failingCheckIndex?: number;
+      reason?: string;
+      hint?: string;
+      ts?: number;
+    };
+    state.verificationFeedback[e.key] = {
+      scope: e.scope as `${string}/${string}`,
+      pass: !!v.pass,
+      failingCheckIndex: v.failingCheckIndex,
+      reason: v.reason,
+      hint: v.hint,
+      ts: v.ts ?? Date.now(),
+    };
+  }
+}
+
 /**
  * Same shape as the local store, but mirrors writes to /api/progress with
  * debounced batching and an offline queue.
@@ -149,31 +210,7 @@ export function createRemoteStore(): ProgressStore {
           entries: Array<{ kind: string; scope: string; key: string; value: unknown }>;
         };
         const merged: ProgressState = { ...emptyState(), ...state };
-        for (const e of entries) {
-          if (e.kind === "step") {
-            merged.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
-              | "incomplete"
-              | "complete";
-          } else if (e.kind === "quiz") {
-            merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
-          } else if (e.kind === "checkpoint") {
-            if (e.value == null) continue;
-            merged.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
-          } else if (e.kind === "pref") {
-            (merged.prefs as Record<string, unknown>)[e.key] = e.value;
-          } else if (e.kind === "lastVisited") {
-            // Tolerate both new ({step, ts}) and legacy (string) shapes.
-            const v = e.value as unknown;
-            merged.lastVisited[e.scope] =
-              typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
-          } else if (e.kind === "tutorial") {
-            const v = (e.value as { ts?: number }) ?? {};
-            const marker = merged.tutorials[e.scope] ?? {};
-            if (e.key === "started") marker.started = v.ts;
-            else if (e.key === "completed") marker.completed = v.ts;
-            merged.tutorials[e.scope] = marker;
-          }
-        }
+        for (const e of entries) applyEntryInto(merged, e);
         state = merged;
         writeStorage(state);
         for (const fn of subscribers) fn(state);
@@ -181,6 +218,30 @@ export function createRemoteStore(): ProgressStore {
         // ignore — local data still drives the UI
       }
     })();
+
+    // Live sync: subscribe to per-learner SSE so MCP-driven writes
+    // (or another tab via the cookie POST) show up immediately. The
+    // standard EventSource auto-reconnects on transient drops.
+    if (typeof EventSource !== "undefined") {
+      try {
+        const es = new EventSource("/api/progress/events", { withCredentials: true });
+        es.addEventListener("message", (ev) => {
+          try {
+            const entry = JSON.parse(ev.data) as ProgressEntry;
+            const next: ProgressState = { ...state };
+            applyEntryInto(next, entry);
+            state = next;
+            writeStorage(state);
+            for (const fn of subscribers) fn(state);
+            channel?.postMessage({ type: "set", state });
+          } catch (e) {
+            console.warn("[handzon] sse parse failed:", e);
+          }
+        });
+      } catch {
+        // ignore — polling-via-mount still keeps things eventually consistent
+      }
+    }
   }
 
   return {

package/src/lib/progress/types.ts

@@ -16,10 +16,32 @@ export interface TutorialMarker {
   completed?: number;
 }
 
+/**
+ * Family D verification feedback delivered via SSE from
+ * `submit_verification` failures. Keyed by the checkpoint id (which
+ * equals `verify.id`). Carries the step scope so the diff can emit
+ * a tombstone with the right scope when the learner unchecks.
+ */
+export interface VerificationFeedbackEntry {
+  scope: StepKey;
+  pass: boolean;
+  failingCheckIndex?: number;
+  reason?: string;
+  hint?: string;
+  ts: number;
+}
+
 export type ProgressState = {
   steps: Record<StepKey, "incomplete" | "complete">;
   quizzes: Record<string, { chosen: number[]; correct: boolean; ts: number }>;
   checkpoints: Record<string, { ts: number }>;
+  /**
+   * Latest verification verdict per checkpoint id. `pass: true`
+   * entries hang around as evidence; the Family D UI only renders
+   * the inline hint block on `pass: false`. Cleared when the
+   * learner unchecks the matching checkpoint.
+   */
+  verificationFeedback: Record<string, VerificationFeedbackEntry>;
   prefs: {
     packageManager?: "npm" | "pnpm" | "yarn" | "bun";
     os?: "macos" | "linux" | "windows";
@@ -50,6 +72,7 @@ export const emptyState = (): ProgressState => ({
   steps: {},
   quizzes: {},
   checkpoints: {},
+  verificationFeedback: {},
   prefs: {},
   lastVisited: {},
   tutorials: {},

package/src/lib/progress/useProgress.ts

@@ -59,10 +59,14 @@ export function useProgress(): ProgressApi {
         })),
       removeCheckpoint: (checkpointId: string) =>
         store.set((s) => {
-          if (!s.checkpoints[checkpointId]) return s;
-          const next = { ...s.checkpoints };
-          delete next[checkpointId];
-          return { ...s, checkpoints: next };
+          const hadCheckpoint = !!s.checkpoints[checkpointId];
+          const hadFeedback = !!s.verificationFeedback[checkpointId];
+          if (!hadCheckpoint && !hadFeedback) return s;
+          const nextCheckpoints = { ...s.checkpoints };
+          delete nextCheckpoints[checkpointId];
+          const nextFeedback = { ...s.verificationFeedback };
+          delete nextFeedback[checkpointId];
+          return { ...s, checkpoints: nextCheckpoints, verificationFeedback: nextFeedback };
         }),
       setPref: <K extends keyof ProgressState["prefs"]>(key: K, value: ProgressState["prefs"][K]) =>
         store.set((s) => ({ ...s, prefs: { ...s.prefs, [key]: value } })),

package/src/pages/TutorialStep.astro

@@ -2,6 +2,9 @@
 import { render } from "astro:content";
 import TutorialLayout from "../layouts/TutorialLayout.astro";
 import ChatButton from "../components/ai/ChatButton.tsx";
+import OpenInAgent from "../components/ai/OpenInAgent.tsx";
+import SelectionAsk from "../components/ai/SelectionAsk.tsx";
+import StepHelp from "../components/ai/StepHelp.tsx";
 import { parseStepId } from "../lib/content.ts";
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
 import { mdxComponents } from "../lib/mdx-components.ts";
@@ -61,7 +64,15 @@ const initialContext = buildContext({
   repoUrl={repoUrl}
 >
   <Content components={components} />
+  {aiConfig.enabled && aiConfig.autoStepHelp && (
+    <StepHelp client:visible stepTitle={currentStep.data.title} />
+  )}
+  <OpenInAgent client:visible />
+
   {aiConfig.enabled && (
-    <ChatButton client:idle config={aiConfig} context={initialContext} />
+    <>
+      <ChatButton client:idle config={aiConfig} context={initialContext} />
+      <SelectionAsk client:idle />
+    </>
   )}
 </TutorialLayout>

package/src/server/auth.ts

@@ -2,7 +2,7 @@ import type { AstroCookieSetOptions, AstroCookies } from "astro";
 import { and, eq, isNull } from "drizzle-orm";
 import { getAuthedUser } from "./auth/session.ts";
 import { getDb } from "./db/client.ts";
-import { learners, progressEntries } from "./db/schema.ts";
+import { learnerApiTokens, learners, progressEntries } from "./db/schema.ts";
 
 const COOKIE = "tt-device";
 const ONE_YEAR = 60 * 60 * 24 * 365;
@@ -121,3 +121,86 @@ async function maybeClaimDeviceProgress(
     await tx.delete(learners).where(eq(learners.id, orphan.id));
   });
 }
+
+const PAT_PREFIX = "hzn_pat_";
+const PAT_RANDOM_BYTES = 32;
+
+/** Hash a raw PAT string to its database form. SHA-256 hex. */
+export async function hashPat(raw: string): Promise<string> {
+  const data = new TextEncoder().encode(raw);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Generate a fresh PAT to show the learner once. The settings page is
+ * the only caller — the API surface never sees the raw token after
+ * mint, and only the hash hits the database.
+ */
+export function generatePat(): string {
+  const bytes = new Uint8Array(PAT_RANDOM_BYTES);
+  crypto.getRandomValues(bytes);
+  // Base64url without padding — agent config files want short, copy/pasteable tokens.
+  const b64 = btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `${PAT_PREFIX}${b64}`;
+}
+
+/**
+ * Resolve a bearer token presented on an incoming request to the
+ * learner that owns it. Returns null when no token, the token is
+ * unknown, or it has expired. `last_used_at` is touched
+ * asynchronously so a slow DB write doesn't add latency to MCP calls.
+ *
+ * Used by the MCP endpoint; the cookie-based progress endpoint stays
+ * on getOrCreateLearner so the same-origin guard remains effective.
+ */
+export async function resolveBearerLearner(
+  request: Request,
+): Promise<{ learnerId: string; scopes: string[] } | null> {
+  const header = request.headers.get("authorization") ?? request.headers.get("Authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  if (!match) return null;
+  const raw = match[1]!;
+  if (!raw.startsWith(PAT_PREFIX)) return null;
+
+  const db = getDb();
+  const hash = await hashPat(raw);
+  const rows = await db
+    .select()
+    .from(learnerApiTokens)
+    .where(eq(learnerApiTokens.tokenHash, hash))
+    .limit(1);
+  const token = rows[0];
+  if (!token) return null;
+  if (token.expiresAt && token.expiresAt.getTime() < Date.now()) return null;
+
+  const learnerRow = await db
+    .select({ id: learners.id })
+    .from(learners)
+    .where(eq(learners.userId, token.userId))
+    .limit(1);
+  const learner = learnerRow[0];
+  if (!learner) return null;
+
+  // Fire-and-forget last-used touch. Failures are logged-but-ignored;
+  // an audit log is more useful than blocking the call.
+  void db
+    .update(learnerApiTokens)
+    .set({ lastUsedAt: new Date() })
+    .where(eq(learnerApiTokens.id, token.id))
+    .catch((e) => {
+      console.warn("[handzon] failed to update PAT last_used_at:", e);
+    });
+
+  const scopes = token.scopes
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return { learnerId: learner.id, scopes };
+}

package/src/server/db/schema.ts

@@ -40,6 +40,59 @@ export const learners = pgTable(
   }),
 );
 
+/**
+ * Personal access tokens for the per-user MCP surface.
+ *
+ * Created by the settings/tokens page in the scaffold template. Stored
+ * as SHA-256 hashes of `hzn_pat_<32 base64url bytes>` strings — the
+ * raw token is shown to the learner once at mint time and never
+ * persisted. The MCP v2 OAuth proxy reuses this table, so the row
+ * shape is forward-compatible with DCR-minted tokens.
+ *
+ * scopes: comma-separated; v1 known values are "progress:read" and
+ * "progress:write". Catalog reads don't require any scope beyond a
+ * valid token.
+ */
+export const learnerApiTokens = pgTable("learner_api_tokens", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  tokenHash: text("token_hash").notNull().unique(),
+  scopes: text("scopes").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+  expiresAt: timestamp("expires_at", { withTimezone: true }),
+});
+
+/**
+ * Help-bridge inbox: pending help requests posted by the agent on
+ * the learner's machine (`request_help` MCP tool). ChatPanel reads
+ * pending rows on open, prepends them as a user turn, and marks
+ * them consumed so the next open doesn't re-replay them.
+ */
+export const helpRequests = pgTable(
+  "help_requests",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    learnerId: uuid("learner_id")
+      .notNull()
+      .references(() => learners.id, { onDelete: "cascade" }),
+    tutorialSlug: text("tutorial_slug").notNull(),
+    stepSlug: text("step_slug").notNull(),
+    query: text("query").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+  },
+  (table) => ({
+    byLearnerPending: index("help_requests_by_learner_pending").on(
+      table.learnerId,
+      table.consumedAt,
+    ),
+  }),
+);
+
 export const progressEntries = pgTable(
   "progress_entries",
   {

package/src/server/handlers/helpInbox.ts

@@ -0,0 +1,45 @@
+import type { APIRoute } from "astro";
+import { and, eq, isNull } from "drizzle-orm";
+import { getOrCreateLearner } from "../auth.ts";
+import { getDb } from "../db/client.ts";
+import { helpRequests } from "../db/schema.ts";
+import { isSameOrigin, json } from "../http.ts";
+
+/**
+ * Returns the learner's pending help-request inbox (rows where
+ * consumed_at IS NULL) and stamps them as consumed in one
+ * round-trip. ChatPanel calls this when it opens; the response
+ * becomes the seed user turns that get auto-streamed.
+ *
+ * Same-origin guarded — only the in-browser ChatPanel reads the
+ * inbox. The MCP-side `request_help` tool produces rows; this
+ * endpoint consumes them.
+ */
+export const GET: APIRoute = async ({ cookies, request }) => {
+  if (!process.env.DATABASE_URL) return json({ requests: [] });
+  if (!isSameOrigin(request)) {
+    return json({ error: "Cross-origin read rejected." }, { status: 403 });
+  }
+  const learner = await getOrCreateLearner(cookies, request);
+  const db = getDb();
+  const rows = await db
+    .select()
+    .from(helpRequests)
+    .where(and(eq(helpRequests.learnerId, learner.id), isNull(helpRequests.consumedAt)));
+  if (rows.length > 0) {
+    const now = new Date();
+    await db
+      .update(helpRequests)
+      .set({ consumedAt: now })
+      .where(and(eq(helpRequests.learnerId, learner.id), isNull(helpRequests.consumedAt)));
+  }
+  return json({
+    requests: rows.map((r) => ({
+      id: r.id,
+      tutorialSlug: r.tutorialSlug,
+      stepSlug: r.stepSlug,
+      query: r.query,
+      createdAt: r.createdAt.toISOString(),
+    })),
+  });
+};

package/src/server/handlers/mcp.ts

@@ -0,0 +1,72 @@
+import type { APIRoute } from "astro";
+import { resolveBearerLearner } from "../auth.ts";
+import type { JsonRpcRequest } from "../mcp/protocol.ts";
+import { type DispatchOptions, dispatchMcp } from "../mcp/server.ts";
+import { defaultTools } from "../mcp/tools.ts";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+/**
+ * Build an Astro POST handler that mounts the MCP JSON-RPC dispatcher
+ * with the given tool set. Scaffold templates re-export this from
+ * `src/pages/api/mcp/index.ts` so updates land for every site
+ * without a code change in the consumer.
+ *
+ * GET /api/mcp returns a tiny capability descriptor that some
+ * clients ping before issuing JSON-RPC.
+ */
+export function createMcpHandler(
+  opts: DispatchOptions = { tools: defaultTools, resolveAuth: resolveBearerLearner },
+): {
+  GET: APIRoute;
+  POST: APIRoute;
+} {
+  const GET: APIRoute = async () =>
+    new Response(
+      JSON.stringify({
+        ok: true,
+        transport: "http+json",
+        message: "POST a JSON-RPC 2.0 request to invoke MCP tools.",
+      }),
+      { headers: { "Content-Type": "application/json" } },
+    );
+
+  const POST: APIRoute = async ({ request }) => {
+    const lengthHeader = request.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_BODY_BYTES) {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Payload too large." },
+      });
+    }
+    const raw = await request.text();
+    if (raw.length > MAX_BODY_BYTES) {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Payload too large." },
+      });
+    }
+    let body: JsonRpcRequest;
+    try {
+      body = JSON.parse(raw) as JsonRpcRequest;
+    } catch {
+      return jsonRpcHttp({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error." },
+      });
+    }
+    const response = await dispatchMcp(request, body, opts);
+    return jsonRpcHttp(response);
+  };
+
+  return { GET, POST };
+}
+
+function jsonRpcHttp(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/src/server/handlers/progress.ts

@@ -1,10 +1,11 @@
 import type { APIRoute } from "astro";
-import { and, eq, sql } from "drizzle-orm";
+import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { getOrCreateLearner } from "../auth.ts";
 import { getDb } from "../db/client.ts";
 import { progressEntries } from "../db/schema.ts";
 import { isSameOrigin, json } from "../http.ts";
+import { writeProgressEntries } from "../progress.ts";
 
 const MAX_BODY_BYTES = 32 * 1024;
 const MAX_ENTRIES = 200;
@@ -59,55 +60,10 @@ export const POST: APIRoute = async ({ cookies, request }) => {
   if (parsed.length === 0) return json({ written: 0 });
 
   const learner = await getOrCreateLearner(cookies, request);
-  const db = getDb();
-  const now = new Date();
-
   // `value: null` is the tombstone signal for "this entry was undone"
-  // (e.g. unchecking a checkpoint). The `value` column is NOT NULL, so
-  // we DELETE these rows instead of upserting them.
-  const deletes = parsed.filter((b) => b.value === null);
-  const upserts = parsed.filter((b) => b.value !== null);
-
-  for (const d of deletes) {
-    await db
-      .delete(progressEntries)
-      .where(
-        and(
-          eq(progressEntries.learnerId, learner.id),
-          eq(progressEntries.kind, d.kind),
-          eq(progressEntries.scope, d.scope),
-          eq(progressEntries.key, d.key),
-        ),
-      );
-  }
-
-  if (upserts.length > 0) {
-    const rows = upserts.map((b) => ({
-      learnerId: learner.id,
-      kind: b.kind,
-      scope: b.scope,
-      key: b.key,
-      value: b.value,
-      updatedAt: now,
-    }));
-    await db
-      .insert(progressEntries)
-      .values(rows)
-      .onConflictDoUpdate({
-        target: [
-          progressEntries.learnerId,
-          progressEntries.kind,
-          progressEntries.scope,
-          progressEntries.key,
-        ],
-        set: {
-          // `excluded` is the row Postgres would have inserted — without
-          // this the SET was a no-op (`value = progress_entries.value`).
-          value: sql`excluded.value`,
-          updatedAt: sql`excluded.updated_at`,
-        },
-      });
-  }
-
-  return json({ written: parsed.length });
+  // (e.g. unchecking a checkpoint). writeProgressEntries handles the
+  // split into deletes + upserts; the same writer is used by the MCP
+  // write tools so behaviour stays consistent across surfaces.
+  const written = await writeProgressEntries(learner.id, parsed);
+  return json({ written });
 };

package/src/server/handlers/progressEvents.ts

@@ -0,0 +1,68 @@
+import type { APIRoute } from "astro";
+import { getOrCreateLearner } from "../auth.ts";
+import { isSameOrigin } from "../http.ts";
+import { subscribeLearner } from "../progressBus.ts";
+
+const HEARTBEAT_MS = 25_000;
+
+/**
+ * Server-Sent Events stream of progress writes for the current
+ * learner. One connection per open browser tab; the in-app store
+ * (`createRemoteStore`) opens an EventSource on first mount and
+ * merges incoming entries through the same reducer as the
+ * POST-response path.
+ *
+ * Each event has the shape:
+ *   data: { "kind": "...", "scope": "...", "key": "...", "value": ..., "ts": ... }
+ *
+ * Heartbeat comments keep proxies (CDN, Render's edge) from
+ * killing the connection on idle.
+ */
+export const GET: APIRoute = async ({ cookies, request }) => {
+  if (!process.env.DATABASE_URL) {
+    return new Response("SSE disabled — no DATABASE_URL.", { status: 503 });
+  }
+  if (!isSameOrigin(request)) {
+    return new Response("Cross-origin SSE rejected.", { status: 403 });
+  }
+  const learner = await getOrCreateLearner(cookies, request);
+  const encoder = new TextEncoder();
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Initial connect comment — clients show "open" only after a
+      // first bit of data, and some proxies need a flush.
+      controller.enqueue(encoder.encode(": connected\n\n"));
+      unsubscribe = subscribeLearner(learner.id, (msg) => {
+        try {
+          const payload = JSON.stringify(msg);
+          controller.enqueue(encoder.encode(`data: ${payload}\n\n`));
+        } catch (e) {
+          console.warn("[handzon] sse encode failed:", e);
+        }
+      });
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": keepalive\n\n"));
+        } catch {
+          /* controller closed — cancel will clean up */
+        }
+      }, HEARTBEAT_MS);
+    },
+    cancel() {
+      unsubscribe?.();
+      if (heartbeat) clearInterval(heartbeat);
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+};