@openparachute/agent 0.1.2 → 0.2.0

package/src/transports/http-ui.test.ts

@@ -0,0 +1,455 @@
+/**
+ * Tier 1 unit + integration tests for the http-ui transport.
+ *
+ * These exercise the transport (and a daemon-shaped Bun.serve harness) WITHOUT a
+ * live Claude session. They cover:
+ *   - inbound routing: a UI `send` reaches the bridge subscribed to that channel;
+ *   - outbound to UI: `transport.reply()` pushes a `reply` event to a connected
+ *     /ui/events SSE client;
+ *   - round-trip through the daemon HTTP server (UI send → bridge, bridge reply
+ *     → UI) with no Claude;
+ *   - channel isolation (a send on A never reaches a UI client on B);
+ *   - registry: an http-ui channel instantiates without a token;
+ *   - reply() with no connected UI client does not throw.
+ */
+
+import { describe, test, expect, mock } from "bun:test";
+
+// Layer 2 gates the http-ui send + SSE routes on `requireScope`, which validates
+// a hub JWT against the hub's JWKS. The no-token path short-circuits to 401
+// before any JWKS fetch (asserted below). To exercise the *delivery* paths
+// (routing, SSE fan-out) without a live hub, stub the JWT validator so a single
+// sentinel token validates with the agent scopes. A request with no token (or
+// any other token) still hits the real no-token / shape-first reject. This keeps
+// the round-trip coverage genuine while staying hub-free.
+const VALID_TOKEN = "test-valid-token";
+// A token carrying ONLY agent:write (a session/bridge token) — must be
+// REJECTED on the UI send endpoint, which requires agent:send. Locks the
+// privilege separation (a session token can't post as a human).
+const WRITE_ONLY_TOKEN = "test-write-only-token";
+mock.module("../hub-jwt.ts", () => ({
+  // New tokens carry aud "agent" (channel→agent rename); CHANNEL_AUDIENCE stays a
+  // deprecated alias. ACCEPTED_AUDIENCES is the dual-accept set the real adapter
+  // checks — included so the mock matches the renamed module surface.
+  AGENT_AUDIENCE: "agent",
+  CHANNEL_AUDIENCE: "channel",
+  ACCEPTED_AUDIENCES: ["agent", "channel"],
+  async validateHubJwt(token: string) {
+    if (token === VALID_TOKEN) {
+      return {
+        sub: "test",
+        scopes: ["agent:read", "agent:send", "agent:write"],
+        aud: "agent",
+        jti: undefined,
+        clientId: undefined,
+        vaultScope: undefined,
+      };
+    }
+    if (token === WRITE_ONLY_TOKEN) {
+      return {
+        sub: "test",
+        scopes: ["agent:write"],
+        aud: "agent",
+        jti: undefined,
+        clientId: undefined,
+        vaultScope: undefined,
+      };
+    }
+    throw new HubJwtError("invalid token");
+  },
+  HubJwtError: class HubJwtError extends Error {},
+  looksLikeJwt: (t: string) => t.split(".").length === 3,
+  resetJwksCache() {},
+  resetRevocationCache() {},
+}));
+class HubJwtError extends Error {}
+
+import { HttpUiTransport } from "./http-ui.ts";
+import type { TransportContext, InboundMessage } from "../transport.ts";
+import { ClientRegistry } from "../routing.ts";
+import { instantiateTransport } from "../registry.ts";
+
+/** Authorization header carrying the sentinel valid token. */
+const AUTH = { authorization: "Bearer " + VALID_TOKEN } as const;
+/** Append the sentinel token as a `?token=` query param (the SSE auth path). */
+function withToken(path: string): string {
+  return path + (path.includes("?") ? "&" : "?") + "token=" + encodeURIComponent(VALID_TOKEN);
+}
+
+/** A test context that records emitted inbound messages + permission verdicts. */
+function fakeCtx(channel: string): TransportContext & {
+  emitted: InboundMessage[];
+  verdicts: { request_id: string; behavior: string }[];
+} {
+  const emitted: InboundMessage[] = [];
+  const verdicts: { request_id: string; behavior: string }[] = [];
+  return {
+    channel,
+    emitted,
+    verdicts,
+    emit(msg) {
+      emitted.push(msg);
+    },
+    emitPermissionVerdict(v) {
+      verdicts.push(v);
+    },
+  };
+}
+
+/**
+ * Read the next non-comment SSE frame from a reader. Handles both the bytes a
+ * `fetch` response body yields and the raw string chunks a directly-read
+ * in-process ReadableStream<string> yields (the transport enqueues strings).
+ */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array | string>,
+  decoder = new TextDecoder(),
+): Promise<string> {
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) return "";
+    const chunk = typeof value === "string" ? value : decoder.decode(value, { stream: true });
+    if (chunk.includes("event:")) return chunk;
+  }
+}
+
+describe("HttpUiTransport — direct", () => {
+  test("ingestHttp send (authed) → ctx.emit on its own channel", async () => {
+    const t = new HttpUiTransport();
+    const ctx = fakeCtx("dev");
+    await t.start(ctx);
+
+    const req = new Request("http://x/api/channels/dev/send", {
+      method: "POST",
+      headers: { "content-type": "application/json", ...AUTH },
+      body: JSON.stringify({ text: "hello session" }),
+    });
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    expect(await res!.json()).toEqual({ ok: true });
+
+    expect(ctx.emitted).toHaveLength(1);
+    expect(ctx.emitted[0]!.content).toBe("hello session");
+    expect(ctx.emitted[0]!.channel).toBe("dev");
+    expect(ctx.emitted[0]!.source).toBe("http-ui");
+  });
+
+  test("ingestHttp send WITHOUT a token → 401, no emit (Layer 2)", async () => {
+    const t = new HttpUiTransport();
+    const ctx = fakeCtx("dev");
+    await t.start(ctx);
+    const req = new Request("http://x/api/channels/dev/send", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ text: "no token" }),
+    });
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(401);
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  test("ingestHttp send with an agent:write-only (session) token → 403, no emit", async () => {
+    // Privilege separation: a session/bridge token (agent:write) must NOT be
+    // usable to post a human message through the UI send endpoint (agent:send).
+    const t = new HttpUiTransport();
+    const ctx = fakeCtx("dev");
+    await t.start(ctx);
+    const req = new Request("http://x/api/channels/dev/send", {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: "Bearer " + WRITE_ONLY_TOKEN },
+      body: JSON.stringify({ text: "trying to send as a session" }),
+    });
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(403);
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  test("ingestHttp SSE WITHOUT a ?token= → 401 (Layer 2)", async () => {
+    const t = new HttpUiTransport();
+    await t.start(fakeCtx("dev"));
+    const req = new Request("http://x/ui/events?channel=dev");
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(401);
+    expect(res!.headers.get("content-type")).toContain("application/json");
+  });
+
+  test("ingestHttp ignores a send for a DIFFERENT channel's path", async () => {
+    const t = new HttpUiTransport();
+    await t.start(fakeCtx("dev"));
+    const req = new Request("http://x/api/channels/other/send", {
+      method: "POST",
+      body: JSON.stringify({ text: "nope" }),
+    });
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res).toBeNull();
+  });
+
+  test("send (authed) with empty/missing text → 400, no emit", async () => {
+    const t = new HttpUiTransport();
+    const ctx = fakeCtx("dev");
+    await t.start(ctx);
+    const req = new Request("http://x/api/channels/dev/send", {
+      method: "POST",
+      headers: { ...AUTH },
+      body: JSON.stringify({ text: "" }),
+    });
+    const res = await t.ingestHttp(req, new URL(req.url));
+    expect(res!.status).toBe(400);
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  test("reply() with no connected UI client does not throw and returns sent:[]", async () => {
+    const t = new HttpUiTransport();
+    await t.start(fakeCtx("dev"));
+    const result = await t.reply({ channel: "dev", text: "ping" });
+    expect(result.sent).toEqual([]);
+  });
+
+  test("reply() pushes a `reply` event to a connected /ui/events SSE client", async () => {
+    const t = new HttpUiTransport();
+    await t.start(fakeCtx("dev"));
+
+    // Open the UI SSE stream via ingestHttp (authed via ?token=).
+    const sseReq = new Request("http://x" + withToken("/ui/events?channel=dev"));
+    const sseRes = await t.ingestHttp(sseReq, new URL(sseReq.url));
+    expect(sseRes).not.toBeNull();
+    const reader = sseRes!.body!.getReader();
+
+    // Drain the ": connected" comment, then reply.
+    const result = await t.reply({ channel: "dev", text: "from session", files: ["/tmp/a.png"] });
+    expect(result.sent).toHaveLength(1);
+
+    const frame = await readFrame(reader);
+    expect(frame).toContain("event: reply");
+    expect(frame).toContain("from session");
+    expect(frame).toContain("/tmp/a.png");
+    reader.cancel().catch(() => {});
+  });
+
+  test("stop() clears UI clients", async () => {
+    const t = new HttpUiTransport();
+    await t.start(fakeCtx("dev"));
+    const sseReq = new Request("http://x" + withToken("/ui/events?channel=dev"));
+    const sseRes = await t.ingestHttp(sseReq, new URL(sseReq.url));
+    sseRes!.body!.getReader();
+    await t.stop();
+    // After stop, a reply reaches nobody.
+    const result = await t.reply({ channel: "dev", text: "x" });
+    expect(result.sent).toEqual([]);
+  });
+});
+
+describe("registry — http-ui", () => {
+  test("an http-ui channel instantiates without a token", () => {
+    const transport = instantiateTransport({ name: "dev", transport: "http-ui" });
+    expect(transport.kind).toBe("http-ui");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Daemon-shaped integration: a Bun.serve harness wiring routing + ingestHttp,
+// mirroring daemon.ts. No Claude.
+// ---------------------------------------------------------------------------
+
+describe("HttpUiTransport — through a daemon-shaped server", () => {
+  /** Build a minimal daemon-shaped server over the given channels. */
+  function buildServer(channelDefs: { name: string }[]) {
+    const registry = new ClientRegistry();
+    const channels = new Map<string, { name: string; transport: HttpUiTransport }>();
+    for (const def of channelDefs) {
+      const transport = new HttpUiTransport();
+      channels.set(def.name, { name: def.name, transport });
+    }
+
+    // Start each transport with a ctx that routes into the bridge registry,
+    // exactly like daemon.ts's contextFor.
+    for (const ch of channels.values()) {
+      const name = ch.name;
+      const ctx: TransportContext = {
+        channel: name,
+        emit(msg) {
+          registry.routeToChannel(name, "message", {
+            content: msg.content,
+            meta: msg.meta,
+            source: msg.source,
+          });
+        },
+        emitPermissionVerdict(v) {
+          registry.routeToChannel(name, "permission_verdict", v);
+        },
+      };
+      ch.transport.start(ctx);
+    }
+
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      idleTimeout: 0,
+      async fetch(req) {
+        const url = new URL(req.url);
+
+        // Bridge SSE subscription (mirrors daemon /events).
+        if (req.method === "GET" && url.pathname === "/events") {
+          const channel = url.searchParams.get("channel") ?? "default";
+          const id = crypto.randomUUID();
+          const stream = new ReadableStream<string>({
+            start(controller) {
+              registry.add(id, { channel, enqueue: (p) => controller.enqueue(p) });
+              controller.enqueue(": connected\n\n");
+            },
+            cancel() {
+              registry.remove(id);
+            },
+          });
+          return new Response(stream, { headers: { "content-type": "text/event-stream" } });
+        }
+
+        // Bridge reply (mirrors daemon /api/reply dispatch).
+        if (req.method === "POST" && url.pathname === "/api/reply") {
+          const body = (await req.json()) as { channel: string; text?: string };
+          const ch = channels.get(body.channel);
+          if (!ch) return new Response(JSON.stringify({ error: "unknown channel" }), { status: 400 });
+          const r = await ch.transport.reply({ channel: body.channel, text: body.text });
+          return new Response(JSON.stringify({ sent: r.sent }), {
+            headers: { "content-type": "application/json" },
+          });
+        }
+
+        // Transport-owned routes (send + /ui/events).
+        for (const ch of channels.values()) {
+          const res = await ch.transport.ingestHttp(req, url);
+          if (res) return res;
+        }
+        return new Response(JSON.stringify({ error: "not found" }), { status: 404 });
+      },
+    });
+
+    return { server, base: `http://127.0.0.1:${server.port}`, registry };
+  }
+
+  /** Open an SSE stream and return a reader + helpers. The http-ui `/ui/events`
+   *  route is Layer-2-gated, so append the sentinel `?token=` for those; the
+   *  bridge `/events` route in this harness is ungated (pass through as-is). */
+  async function openSse(base: string, path: string) {
+    const url = path.startsWith("/ui/events") ? withToken(path) : path;
+    const res = await fetch(`${base}${url}`);
+    const reader = res.body!.getReader();
+    return {
+      read: () => readFrame(reader),
+      cancel: () => reader.cancel().catch(() => {}),
+    };
+  }
+
+  test("inbound routing: UI send reaches the subscribed bridge", async () => {
+    const { server, base, registry } = buildServer([{ name: "dev" }]);
+    try {
+      // A bridge subscribes to channel "dev".
+      const bridge = await openSse(base, "/events?channel=dev");
+      // Wait for registration.
+      const start = Date.now();
+      while (registry.size < 1 && Date.now() - start < 1000) {
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      expect(registry.size).toBe(1);
+
+      // UI POSTs a send (authed — Layer 2).
+      const res = await fetch(`${base}/api/channels/dev/send`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...AUTH },
+        body: JSON.stringify({ text: "hi from UI" }),
+      });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ ok: true });
+
+      const frame = await bridge.read();
+      expect(frame).toContain("event: message");
+      expect(frame).toContain("hi from UI");
+      bridge.cancel();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("round-trip: UI send → bridge AND bridge /api/reply → UI SSE, end to end", async () => {
+    const { server, base, registry } = buildServer([{ name: "dev" }]);
+    try {
+      const bridge = await openSse(base, "/events?channel=dev");
+      const ui = await openSse(base, "/ui/events?channel=dev");
+      const start = Date.now();
+      while (registry.size < 1 && Date.now() - start < 1000) {
+        await new Promise((r) => setTimeout(r, 5));
+      }
+
+      // UI → bridge (authed — Layer 2).
+      await fetch(`${base}/api/channels/dev/send`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...AUTH },
+        body: JSON.stringify({ text: "wake up" }),
+      });
+      const bridgeFrame = await bridge.read();
+      expect(bridgeFrame).toContain("wake up");
+
+      // bridge → UI (the session replied via the reply tool).
+      const replyRes = await fetch(`${base}/api/reply`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ channel: "dev", text: "I am awake" }),
+      });
+      expect((await replyRes.json()).sent).toHaveLength(1);
+
+      const uiFrame = await ui.read();
+      expect(uiFrame).toContain("event: reply");
+      expect(uiFrame).toContain("I am awake");
+
+      bridge.cancel();
+      ui.cancel();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("channel isolation: a send on A reaches A's bridge but NOT a UI client on B", async () => {
+    const { server, base } = buildServer([{ name: "A" }, { name: "B" }]);
+    try {
+      const bridgeA = await openSse(base, "/events?channel=A");
+      const uiB = await openSse(base, "/ui/events?channel=B");
+
+      // Send on channel A, then reply on A (authed — Layer 2).
+      await fetch(`${base}/api/channels/A/send`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...AUTH },
+        body: JSON.stringify({ text: "for-A" }),
+      });
+      // Close the loop: A's bridge MUST receive the inbound (not just "B didn't").
+      const bridgeFrame = await bridgeA.read();
+      expect(bridgeFrame).toContain("for-A");
+
+      await fetch(`${base}/api/reply`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ channel: "A", text: "reply-to-A" }),
+      });
+
+      // Now reply on B so B's stream definitely has a frame, and assert it's B's
+      // only — none of A's traffic leaked across.
+      await fetch(`${base}/api/reply`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ channel: "B", text: "reply-to-B" }),
+      });
+
+      const frame = await uiB.read();
+      expect(frame).toContain("reply-to-B");
+      expect(frame).not.toContain("reply-to-A");
+      expect(frame).not.toContain("for-A");
+      bridgeA.cancel();
+      uiB.cancel();
+    } finally {
+      server.stop(true);
+    }
+  });
+});

package/src/transports/http-ui.ts

@@ -0,0 +1,201 @@
+/**
+ * http-ui transport for parachute-agent.
+ *
+ * The freestanding "make sure message sending works" surface: a human talks to
+ * a Claude Code session through a browser, with NO Telegram and NO vault.
+ *
+ * How it differs from telegram — the "external party" is a browser:
+ *  - Inbound (human → session): the UI POSTs to
+ *    `/api/channels/<name>/send {text}`; this transport calls `ctx.emit(...)`,
+ *    which routes to the bridge subscribed to that channel and wakes the
+ *    session.
+ *  - Outbound (session → human): when the session calls the `reply` tool, the
+ *    bridge POSTs `/api/reply {channel,...}`; the daemon dispatches to this
+ *    transport's `reply()`. Since the browser can't be POSTed to, this transport
+ *    holds its own set of **UI SSE clients** per channel and `reply()` enqueues
+ *    to them (mirroring the daemon's `/events` SSE pattern for bridges).
+ *
+ * It owns two HTTP surfaces via `ingestHttp` (scoped to ITS OWN channel name):
+ *   1. POST /api/channels/<name>/send   — body {text} → ctx.emit(...) → {ok:true}
+ *   2. GET  /ui/events?channel=<name>    — SSE stream the browser subscribes to
+ * The static `/ui` chat page itself is global and served by the daemon, since
+ * it's a channel picker across all http-ui channels.
+ */
+
+import type {
+  Transport,
+  TransportContext,
+  ReplyArgs,
+  EditArgs,
+  PermissionArgs,
+} from "../transport.ts";
+import { sseFrame } from "../routing.ts";
+import { requireScope, json, SCOPE_SEND, SCOPE_READ } from "../auth.ts";
+
+/** A connected browser SSE client (one per open chat page on this channel). */
+interface UiClient {
+  enqueue(payload: string): void;
+}
+
+/** Config for an http-ui transport instance (no secret needed — just a name). */
+export interface HttpUiTransportConfig {
+  /** Optional override for the channel name; normally taken from ctx.channel. */
+  channel?: string;
+}
+
+export class HttpUiTransport implements Transport {
+  readonly kind = "http-ui";
+
+  /** Captured in start() — the channel this instance is bound to. */
+  private ctx: TransportContext | undefined;
+  /** Connected browser SSE clients for this channel, keyed by client id. */
+  private uiClients = new Map<string, UiClient>();
+
+  constructor(_config: HttpUiTransportConfig = {}) {
+    // http-ui needs no secret. Config is accepted for forward-compat.
+  }
+
+  async start(ctx: TransportContext): Promise<void> {
+    this.ctx = ctx;
+  }
+
+  async stop(): Promise<void> {
+    // Close all browser SSE streams. Enqueue can throw on an already-closed
+    // stream; swallow per-client so one bad client doesn't block the rest.
+    for (const client of this.uiClients.values()) {
+      try {
+        client.enqueue(sseFrame("close", {}));
+      } catch {}
+    }
+    this.uiClients.clear();
+  }
+
+  /** The channel name this transport is bound to (after start). */
+  private get channel(): string {
+    if (!this.ctx) throw new Error("http-ui transport: not started");
+    return this.ctx.channel;
+  }
+
+  /** Push an SSE frame to every connected browser client. Returns delivery count. */
+  private pushToUi(event: string, data: unknown): number {
+    const payload = sseFrame(event, data);
+    let delivered = 0;
+    for (const [id, client] of this.uiClients) {
+      try {
+        client.enqueue(payload);
+        delivered++;
+      } catch {
+        this.uiClients.delete(id);
+      }
+    }
+    return delivered;
+  }
+
+  // -------------------------------------------------------------------------
+  // Outbound — the session → browser direction
+  // -------------------------------------------------------------------------
+
+  async reply(args: ReplyArgs): Promise<{ sent: string[] }> {
+    // The browser can't be POSTed to, so we push the reply over the UI SSE
+    // stream(s). A message with no connected UI client still succeeds — it just
+    // has no listener (return an empty sent list).
+    const id = crypto.randomUUID();
+    const delivered = this.pushToUi("reply", {
+      id,
+      text: args.text ?? "",
+      files: args.files ?? [],
+    });
+    return { sent: delivered > 0 ? [id] : [] };
+  }
+
+  async edit(args: EditArgs): Promise<void> {
+    this.pushToUi("edit", { id: args.message_id, text: args.text });
+  }
+
+  async sendPermission(args: PermissionArgs): Promise<{ sent: string[] }> {
+    // Surface the permission prompt in the chat so the human sees it. There's no
+    // verdict affordance wired in the minimal UI yet (Stage 1), but the prompt
+    // is visible — better than the daemon's methodMissing 400.
+    const delivered = this.pushToUi("permission", {
+      request_id: args.request_id,
+      tool_name: args.tool_name,
+      description: args.description,
+      input_preview: args.input_preview,
+    });
+    return { sent: delivered > 0 ? [args.request_id] : [] };
+  }
+
+  // -------------------------------------------------------------------------
+  // HTTP routes this transport owns (only for ITS OWN channel name)
+  // -------------------------------------------------------------------------
+
+  async ingestHttp(req: Request, url: URL): Promise<Response | null> {
+    const channel = this.channel; // getter throws a clear error if not started
+    const ctx = this.ctx!; // safe: the getter above guarantees ctx is set
+
+    // 1. Inbound: POST /api/channels/<channel>/send  body {text}
+    if (
+      req.method === "POST" &&
+      url.pathname === `/api/channels/${channel}/send`
+    ) {
+      // Layer 2 (human→UI): a hub-issued token with `agent:send`. The UI
+      // fetches it from the hub's /admin/agent-token (portal-cookie-gated) and
+      // attaches it as a Bearer header. No-token → 401 (short-circuits pre-JWKS).
+      const denied = await requireScope(req, url, SCOPE_SEND);
+      if (denied) return denied;
+      let text: string;
+      try {
+        const body = (await req.json()) as { text?: unknown };
+        if (typeof body.text !== "string" || body.text.length === 0) {
+          return json({ error: "body must be { text: <non-empty string> }" }, 400);
+        }
+        text = body.text;
+      } catch {
+        return json({ error: "invalid JSON body" }, 400);
+      }
+      ctx.emit({
+        channel,
+        content: text,
+        meta: { source: "http-ui", ts: new Date().toISOString() },
+        source: "http-ui",
+      });
+      return json({ ok: true });
+    }
+
+    // 2. Outbound stream: GET /ui/events?channel=<channel>
+    if (
+      req.method === "GET" &&
+      url.pathname === "/ui/events" &&
+      url.searchParams.get("channel") === channel
+    ) {
+      // Layer 2: gate on `agent:read`. EventSource can't set headers, so the
+      // token rides in as a `?token=` query param — the ONLY endpoint that opts
+      // into the query-param fallback (allowQueryParam: true). No-token → 401
+      // before the stream opens.
+      const denied = await requireScope(req, url, SCOPE_READ, true);
+      if (denied) return denied;
+      const clientId = crypto.randomUUID();
+      const clients = this.uiClients;
+      const stream = new ReadableStream<string>({
+        start(controller) {
+          clients.set(clientId, {
+            enqueue: (payload) => controller.enqueue(payload),
+          });
+          controller.enqueue(": connected\n\n");
+        },
+        cancel() {
+          clients.delete(clientId);
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "content-type": "text/event-stream",
+          "cache-control": "no-cache",
+          connection: "keep-alive",
+        },
+      });
+    }
+
+    return null;
+  }
+}