@haikit/server 0.19.0 → 0.20.1

package/src/routes.ts

@@ -1,11 +1,12 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { isConversationBusy, isStaleLease } from "@haikit/core";
 import type { Emit, NoticeRecord, WireEvent } from "@haikit/core";
-import type { Hai } from "./runtime.js";
+import type { Hai, WakeOutcome } from "./runtime.js";
 
 /**
  * Node http handler for the three routes, and a fourth when the app sends
- * notices. Returns true if it handled the request.
+ * notices. Returns true if it handled the request. It never rejects: a request
+ * that fails is answered, ended and logged (see `failed`).
  *
  * The three POST routes stream SSE: chat and interact because both can resume
  * the agent loop, start because the init tool it runs can render surfaces.
@@ -18,92 +19,139 @@ import type { Hai } from "./runtime.js";
  */
 export function nodeHandler(hai: Hai, basePath = "/hai") {
   return async function handle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
-    const url = new URL(req.url ?? "/", "http://localhost");
+    let url: URL;
+    try {
+      url = new URL(req.url ?? "/", "http://localhost");
+    } catch {
+      // Node accepts targets a URL can't parse, such as `//[`. None is under
+      // a base path, which a URL always parses, so it's not ours: the app's.
+      return false;
+    }
     if (!url.pathname.startsWith(basePath)) return false;
     const route = url.pathname.slice(basePath.length);
 
     if (req.method === "GET" && route === "/events" && hai.streamsEvents) {
-      await streamNotices(hai, req, res, url);
+      try {
+        await streamNotices(hai, req, res, url);
+      } catch (err) {
+        failed(res, err);
+      }
       return true;
     }
 
     if (req.method !== "POST") return false;
     if (route !== "/chat" && route !== "/interact" && route !== "/start") return false;
 
-    const body = await readJson(req);
-
-    // Nothing to run before the first message: answer with an empty stream and
-    // create no conversation, so an app without init doesn't get one for every
-    // page view. Its first message starts the conversation, as it always has.
-    if (route === "/start" && !hai.config.init) {
-      openSSE(res);
-      res.end();
-      return true;
-    }
-
-    // Before the SSE stream opens, because a rejected load has no stream to
-    // report into — and an uncaught throw here would take down the request.
-    let conversation;
     try {
-      conversation = await hai.config.store.loadConversation(body.conversationId);
+      await respond(hai, route, req, res);
     } catch (err) {
-      if (!isConversationBusy(err)) throw err;
-      res.writeHead(409, { "content-type": "application/json" });
-      res.end(JSON.stringify({ error: (err as Error).message }));
-      return true;
+      failed(res, err);
     }
+    return true;
+  };
+}
 
-    const emit = openSSE(res);
-    if (route === "/chat" || route === "/start") {
-      emit({
-        type: "hello",
-        conversationId: conversation.id,
-        model: hai.config.model.id,
-        ...(hai.streamsEvents ? { events: true as const } : {}),
-      });
-    }
+/**
+ * A request that failed in a way the route has no event for, such as a store
+ * error: the browser is told, the response ends, and the error is logged. It
+ * is never thrown on to the server, where an unhandled rejection would take
+ * the process down and leave the response open.
+ */
+function failed(res: ServerResponse, err: unknown) {
+  console.error("[haikit] request failed:", err);
+  const message = err instanceof Error ? err.message : String(err);
+  if (!res.headersSent) {
+    res.writeHead(500, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: message }));
+  } else if (!res.writableEnded) {
+    res.write(`data: ${JSON.stringify({ type: "error", message } satisfies WireEvent)}\n\n`);
+    res.end();
+  }
+}
+
+/** One of the three POST routes, once the request is known to be one. */
+async function respond(hai: Hai, route: string, req: IncomingMessage, res: ServerResponse) {
+  let body: Record<string, any>;
+  try {
+    body = await readJson(req);
+  } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "the request body must be a JSON object" }));
+    return;
+  }
 
-    let superseded = false;
+  // Nothing to run before the first message: answer with an empty stream and
+  // create no conversation, so an app without init doesn't get one for every
+  // page view. Its first message starts the conversation, as it always has.
+  if (route === "/start" && !hai.config.init) {
+    openSSE(res);
+    res.end();
+    return;
+  }
+
+  // Before the SSE stream opens, because a rejected load has no stream to
+  // report into: busy is a 409, and anything else a 500 (see `failed`).
+  let conversation;
+  try {
+    conversation = await hai.config.store.loadConversation(body.conversationId);
+  } catch (err) {
+    if (!isConversationBusy(err)) throw err;
+    res.writeHead(409, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: (err as Error).message }));
+    return;
+  }
+
+  const emit = openSSE(res);
+  if (route === "/chat" || route === "/start") {
+    emit({
+      type: "hello",
+      conversationId: conversation.id,
+      model: hai.config.model.id,
+      ...(hai.streamsEvents ? { events: true as const } : {}),
+    });
+  }
+
+  let superseded = false;
+  try {
+    if (route === "/chat") {
+      await hai.send(conversation, String(body.message ?? ""), emit);
+    } else if (route === "/start") {
+      await hai.start(conversation, emit);
+    } else {
+      await hai.interact(
+        conversation,
+        { handle: body.handle, action: body.action, value: body.value },
+        emit,
+      );
+    }
+  } catch (err) {
+    if (isStaleLease(err)) superseded = true;
+    emit({ type: "error", message: (err as Error).message });
+  } finally {
+    // The lease lives exactly as long as the request. Releasing it any
+    // earlier — when a turn parks, say — lets the client's next interaction
+    // arrive before this request has finished writing, and the two turns
+    // interleave on one conversation.
+    //
+    // Only the expiry is cleared. The token has to survive so the save below
+    // can still prove this request is the rightful holder.
+    conversation.leaseUntil = null;
     try {
-      if (route === "/chat") {
-        await hai.send(conversation, String(body.message ?? ""), emit);
-      } else if (route === "/start") {
-        await hai.start(conversation, emit);
-      } else {
-        await hai.interact(
-          conversation,
-          { handle: body.handle, action: body.action, value: body.value },
-          emit,
-        );
-      }
+      // A turn that already hit a fence knows its save would be rejected too;
+      // attempting it only repeats the same error to the client.
+      if (!superseded) await hai.config.store.saveConversation(conversation);
     } catch (err) {
-      if (isStaleLease(err)) superseded = true;
+      // Overtaken while we were slow: another turn already wrote newer state
+      // under a fresh token. Dropping this write is the correct outcome, but
+      // the client asked for something it is not getting, so say so. Any
+      // other failure goes to `failed`, which says so too, ends the response
+      // and logs it: the conversation stays held until its lease lapses.
+      if (!isStaleLease(err)) throw err;
       emit({ type: "error", message: (err as Error).message });
-    } finally {
-      // The lease lives exactly as long as the request. Releasing it any
-      // earlier — when a turn parks, say — lets the client's next interaction
-      // arrive before this request has finished writing, and the two turns
-      // interleave on one conversation.
-      //
-      // Only the expiry is cleared. The token has to survive so the save below
-      // can still prove this request is the rightful holder.
-      conversation.leaseUntil = null;
-      try {
-        // A turn that already hit a fence knows its save would be rejected too;
-        // attempting it only repeats the same error to the client.
-        if (!superseded) await hai.config.store.saveConversation(conversation);
-      } catch (err) {
-        // Overtaken while we were slow: another turn already wrote newer state
-        // under a fresh token. Dropping this write is the correct outcome, but
-        // the client asked for something it is not getting, so say so.
-        if (!isStaleLease(err)) throw err;
-        emit({ type: "error", message: (err as Error).message });
-      }
     }
+  }
 
-    res.end();
-    return true;
-  };
+  res.end();
 }
 
 /**
@@ -111,6 +159,27 @@ export function nodeHandler(hai: Hai, basePath = "/hai") {
  * this is what still finds a notice whose wake-up was lost.
  */
 const POLL_MS = 2_000;
+/**
+ * A short fingerprint of signal values, by name: what a polling browser says it
+ * has, so a poll knows whether the latest values are news to it. The client
+ * computes the same (packages/client/src/index.js); change both together.
+ */
+export function signalsDigest(entries: [string, unknown][]): string {
+  const text = JSON.stringify([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) hash = Math.imul(hash ^ text.charCodeAt(i), 0x01000193);
+  return (hash >>> 0).toString(16);
+}
+
+/** How long a process keeps hearing a conversation's turns after its last stream closes. */
+const WATCH_LINGER_MS = 60_000;
+/** How long a wake turn that has ended is kept, for a poll that missed its end, and how many at most. */
+const ENDED_TURN_KEPT_MS = 60_000;
+const ENDED_TURNS_KEPT = 5;
+/** The longest a poll holds when there is nothing new to send. */
+const POLL_HOLD_MS = 15_000;
+/** How long a poll waits after something new, for what comes with it, before it ends. */
+const POLL_GATHER_MS = 250;
 /** Proxies drop a stream that says nothing for long; a comment keeps it open. */
 const HEARTBEAT_MS = 25_000;
 
@@ -132,6 +201,18 @@ const PAGE = 100;
 async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse, url: URL) {
   const { store } = hai.config;
   const conversationId = url.searchParams.get("conversationId") ?? "";
+  // A poll, for a browser behind a proxy that holds a stream back until it
+  // ends: what's waiting, then the response ends, which any proxy delivers.
+  // `poll=now` answers at once; `poll=1` holds until something new arrives,
+  // or for `wait` ms (at most POLL_HOLD_MS) if nothing does.
+  const poll = url.searchParams.get("poll");
+  const polling = poll === "1" || poll === "now";
+  // a fingerprint of the signal values the browser already has (signalsDigest)
+  const hasSignals = url.searchParams.get("signals");
+  // the last wake turn the browser saw end, by its number
+  const sawTurn = Number(url.searchParams.get("turn") ?? 0);
+  const asked = Number(url.searchParams.get("wait") ?? POLL_HOLD_MS);
+  const holdMs = Number.isFinite(asked) ? Math.min(Math.max(asked, 0), POLL_HOLD_MS) : POLL_HOLD_MS;
   const resume = Number(req.headers["last-event-id"] ?? url.searchParams.get("after") ?? 0);
   let after = Number.isSafeInteger(resume) && resume > 0 ? resume : 0;
 
@@ -147,6 +228,7 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
   // Counted as watching from here, so nothing lets the entry go while this
   // stream is still being set up.
   const watchers = watchersOf(hai, conversationId);
+  watchers.stay();
   watchers.pending++;
   try {
     await watchers.ready;
@@ -166,8 +248,11 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
     connection: "keep-alive",
   });
   // Sent now, not with the first frame: with nothing to catch up on, that is a
-  // heartbeat away, and the browser's request would hang open until then.
+  // heartbeat away, and the browser's request would hang open until then. A
+  // comment with them, so the browser hears its first bytes at once: one that
+  // hears nothing knows something on the way is holding the stream, and polls.
   res.flushHeaders();
+  res.write(": open\n\n");
   const aborter = new AbortController();
   const { signal } = aborter;
   res.on("close", () => aborter.abort());
@@ -186,11 +271,20 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
     });
   };
 
-  // A wake turn's events go out as they come, one frame each, and a stream
-  // the browser has left takes no more.
-  const emit: Emit = (event) => {
+  // Something new for this browser: a poll ends a moment after it, to gather
+  // what comes with it.
+  let markFresh = () => {};
+  const freshened = new Promise<void>((resolve) => (markFresh = resolve));
+
+  // A frame out, and a stream the browser has left takes no more.
+  const send = (event: WireEvent) => {
     if (!signal.aborted && !res.writableEnded) res.write(`data: ${JSON.stringify(event)}\n\n`);
   };
+  // A wake turn's events go out as they come, one frame each.
+  const emit: Emit = (event) => {
+    send(event);
+    markFresh();
+  };
   // Every stream this process has open for the conversation hears a wake
   // turn, not only the one whose attempt won the lease: another tab shows the
   // reply too, and holds its requests until the turn lets go.
@@ -220,22 +314,58 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
     }
     res.write(`data: ${JSON.stringify(event)}\n\n`);
   };
-  const closeStream = hai.streamOpened(conversationId, emitSignal);
+  // A new signal is news. Each one's latest, sent as the stream opens, is
+  // news to a poll only if the browser doesn't have those values yet, such as
+  // one sent between two polls: every poll gets them, and a poll that always
+  // ended on them would never wait.
+  const replayed: [string, unknown][] = [];
+  const closeStream = hai.streamOpened(
+    conversationId,
+    (event) => {
+      emitSignal(event);
+      markFresh();
+    },
+    (event) => {
+      emitSignal(event);
+      if (!polling || event.type !== "signal") return;
+      // the latest are sent one after another, at once: compare once all are in
+      if (!replayed.length) queueMicrotask(() => signalsDigest(replayed) !== hasSignals && markFresh());
+      replayed.push([event.name, event.payload]);
+    },
+  );
   // Joining while a wake turn runs: what it has shown so far, starting with
   // its `streaming` status, so the browser holds requests until it lets go,
   // and the reply's later text has a block to land in.
   // A surface it shows is sent with its age, so the browser counts its
   // freshness from when the surface was stored, not from now.
-  if (watchers.live) for (const event of watchers.shown) emit(aged(event));
+  if (watchers.live) for (const event of watchers.shown) send(aged(event));
+  else if (polling) {
+    // A turn that ended between two polls, unseen: all it showed, its end
+    // included, which is news. Then that no turn is running, which a browser
+    // that saw nothing of one needs too, or it would wait for it for ever.
+    // every one it missed, oldest first, if more than one ended meanwhile
+    const missed = Number.isSafeInteger(sawTurn) ? watchers.ended.filter((turn) => turn.number > sawTurn) : [];
+    for (const turn of missed) for (const event of turn.shown) send(aged(event));
+    if (missed.length) markFresh();
+    send({ type: "released" });
+  }
 
   // Wake turns run beside the notice loop, so a notice never waits behind a
   // turn, nor behind the retries while another request holds the
   // conversation. One attempt at a time; a wake notice that lands meanwhile
   // asks for another once it is done.
+  //
+  // An attempt takes the conversation's lease and saves it, even when it
+  // finds nothing to do, and a request that arrives meanwhile is turned away
+  // busy. So it is made only when there may be something new: a wake notice,
+  // read from the store by any stream here, past the last one an attempt here
+  // settled. A polling browser opens a stream several times a minute; each
+  // would otherwise take the lease.
   let waking: Promise<void> | null = null;
   let again = false;
   const wake = () => {
     if (!hai.wakes || signal.aborted) return;
+    if (watchers.wakeRead <= watchers.wakeSettled) return;
     if (waking) {
       again = true;
       return;
@@ -243,12 +373,22 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
     waking = (async () => {
       do {
         again = false;
+        // every wake notice read here so far: what the attempt settles, unless it fails
+        const through = watchers.wakeRead;
         let wait = WAKE_RETRY_MS;
-        while (!signal.aborted && (await hai.wake(conversationId, watchers.turn())) === "busy") {
+        let outcome: WakeOutcome = "busy";
+        while (!signal.aborted && (outcome = await hai.wake(conversationId, watchers.turn())) === "busy") {
           await pause(wait, signal);
           wait = Math.min(wait * 2, WAKE_RETRY_MAX_MS);
+          // Another stream here may have been the one holding it, with a turn
+          // that settled these notices: taking the lease again finds nothing.
+          if (through <= watchers.wakeSettled) break;
         }
-      } while (again && !signal.aborted);
+        // A failed turn gives its notices back to wake again, so it settles
+        // nothing: the next stream to open tries once more.
+        if (outcome !== "busy" && outcome !== "failed") watchers.wakeSettled = Math.max(watchers.wakeSettled, through);
+        // asked again meanwhile: only if a notice came that this one didn't settle
+      } while (again && !signal.aborted && watchers.wakeRead > watchers.wakeSettled);
     })()
       .catch((err) => emit({ type: "error", message: (err as Error).message }))
       .finally(() => {
@@ -299,7 +439,11 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
         if (n.replaces !== undefined && n.handle !== undefined) {
           await sendRevision(n.handle, n.replaces, n.seq);
           after = n.seq;
-          woken ||= n.kind === "wake";
+          markFresh();
+          if (n.kind === "wake") {
+            woken = true;
+            watchers.wakeRead = Math.max(watchers.wakeRead, n.seq);
+          }
           continue;
         }
         const event: WireEvent = {
@@ -312,7 +456,11 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
         };
         await write(`id: ${n.seq}\ndata: ${JSON.stringify(event)}\n\n`);
         after = n.seq;
-        woken ||= n.kind === "wake";
+        markFresh();
+        if (n.kind === "wake") {
+          woken = true;
+          watchers.wakeRead = Math.max(watchers.wakeRead, n.seq);
+        }
       }
       if (records.length < PAGE || signal.aborted) break;
       page = null;
@@ -325,14 +473,12 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
   // An app that sends no notices has nothing stored to read: the stream is only
   // for signals, and stays open, reading nothing, until the browser leaves.
   const wakes = hai.sendsNotices ? wakeups(store.watch?.(conversationId, signal), signal)[Symbol.asyncIterator]() : null;
-  try {
-    if (!wakes) {
-      await new Promise<void>((resolve) => {
-        if (signal.aborted) resolve();
-        else signal.addEventListener("abort", () => resolve(), { once: true });
-      });
-      return;
-    }
+  const left = new Promise<void>((resolve) => {
+    if (signal.aborted) resolve();
+    else signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+  const run = async () => {
+    if (!wakes) return left;
     await catchUp(first);
     // A wake notice may be waiting from before this browser connected: one
     // that arrived while nobody watched, or while the conversation was busy.
@@ -346,6 +492,22 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
       next = wakes.next();
       await catchUp();
     }
+  };
+  try {
+    if (!polling) return await run();
+    // A poll: the same reading, until something new has gone out and what
+    // came with it has had a moment to follow, or the hold runs out.
+    if (poll === "now") markFresh();
+    let hold: ReturnType<typeof setTimeout> | undefined;
+    const done = Promise.race([
+      left,
+      freshened.then(() => new Promise<void>((resolve) => setTimeout(resolve, POLL_GATHER_MS))),
+      new Promise<void>((resolve) => (hold = setTimeout(resolve, holdMs))),
+    ]);
+    // a read that fails ends nothing early: the poll answers at its hold
+    void run().catch((err) => console.error("[haikit] events poll failed:", err));
+    await done;
+    clearTimeout(hold);
   } finally {
     clearInterval(heartbeat);
     aborter.abort();
@@ -371,6 +533,13 @@ interface Watchers {
    * then everything else in order. A turn's worth, dropped when it ends.
    */
   shown: WireEvent[];
+  /**
+   * The wake turns that ended in the past minute, the last few, oldest first:
+   * each one's number and everything it showed, `released` included. A poll
+   * is sent each one its browser hasn't seen end, since they may have ended
+   * between two polls.
+   */
+  ended: { number: number; shown: WireEvent[] }[];
   /**
    * An emitter for one wake attempt in this process: its frames go to every
    * stream here and to the other processes, marked as one turn.
@@ -380,8 +549,31 @@ interface Watchers {
   pending: number;
   /** Let this entry go, and stop hearing other processes for it. */
   forget: () => void;
+  /**
+   * A stream for the conversation opened: stop lingering. And its last stream
+   * closed: keep hearing other processes a while, then let go. A browser that
+   * polls comes back in moments, perhaps to another server, and a wake turn
+   * that ends meanwhile, wherever it ran, has to be here to replay.
+   */
+  stay: () => void;
+  leave: () => void;
   /** Settles once this process is listening for other processes' turns. */
   ready: Promise<void>;
+  /**
+   * The highest seq of a wake notice any stream here has read from the store,
+   * whether or not an attempt has settled it yet: a stream that resumes past
+   * it, reading nothing, still knows it's there. 0 until one is read.
+   */
+  wakeRead: number;
+  /**
+   * The highest wake notice seq a wake attempt here has settled: it woke,
+   * found nothing to do, or was held back by `maxWakes`. A stream makes an
+   * attempt only while `wakeRead` is past it. -1 until the first, so the first
+   * stream this process opens for the conversation looks once, for an update
+   * notice a revision still owes. Both come from the store, never from what a
+   * browser says it has seen, since every stream here shares them.
+   */
+  wakeSettled: number;
 }
 
 /** Fold a wake turn's frame into what it has shown so far. */
@@ -462,8 +654,9 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
     const origin = originOf(hai);
     // Hearing other processes' wake turns lasts as long as this entry does.
     const hearing = new AbortController();
+    let lingering: ReturnType<typeof setTimeout> | null = null;
     const forget = () => {
-      if (map.get(conversationId) !== fresh || fresh.pending || fresh.streams.size || fresh.live) return;
+      if (map.get(conversationId) !== fresh || fresh.pending || fresh.streams.size || fresh.live || fresh.ended.length || lingering) return;
       map.delete(conversationId);
       hearing.abort();
     };
@@ -478,12 +671,14 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
     // start. A turn takes over only with a number at least as high as any
     // seen; anything but the current turn's frames is dropped.
     let current: string | null = null;
+    let currentNumber: number | undefined;
     let newest = 0;
     const deliver = (event: WireEvent, turn: string, number: number | undefined) => {
       if (event.type === "status" && event.status === "streaming") {
         if (current !== turn) {
           if (number !== undefined && number < newest) return; // an older turn's late start
           current = turn;
+          currentNumber = number;
           if (number !== undefined) newest = number;
           fresh.live = true;
           fresh.shown = [];
@@ -493,6 +688,15 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
       }
       remember(fresh.shown, event);
       if (event.type === "released") {
+        // kept a while for a poll that missed the end, then let go
+        if (currentNumber !== undefined) {
+          const ended = { number: currentNumber, shown: fresh.shown };
+          fresh.ended = [...fresh.ended, ended].slice(-ENDED_TURNS_KEPT);
+          setTimeout(() => {
+            fresh.ended = fresh.ended.filter((turn) => turn !== ended);
+            forget();
+          }, ENDED_TURN_KEPT_MS).unref?.();
+        }
         current = null;
         fresh.live = false;
         fresh.shown = [];
@@ -506,8 +710,23 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
       streams: new Set(),
       live: false,
       shown: [],
+      ended: [],
       forget,
+      stay: () => {
+        if (lingering) clearTimeout(lingering);
+        lingering = null;
+      },
+      leave: () => {
+        if (lingering) clearTimeout(lingering);
+        lingering = setTimeout(() => {
+          lingering = null;
+          forget();
+        }, WATCH_LINGER_MS);
+        lingering.unref?.();
+      },
       ready: Promise.resolve(),
+      wakeRead: 0,
+      wakeSettled: -1,
       // A wake turn running here: its frames to this process's streams, and,
       // through the store, to every other process's. All but `context`, the
       // whole history, which another tab gets with its own next request.
@@ -554,8 +773,9 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
 
 function forgetWatchers(_hai: Hai, _conversationId: string, watchers: Watchers) {
   // Kept while a wake turn runs, so a stream that joins later still hears it,
-  // and while any stream is open or being set up. `forget` checks all three.
-  watchers.forget();
+  // while any stream is open or being set up, while an ended turn is kept, and
+  // for a while after the last stream closes. `forget` checks them all.
+  watchers.leave();
 }
 
 /** The first wait before trying a wake turn again on a busy conversation, and the longest. */
@@ -622,8 +842,11 @@ function openSSE(res: ServerResponse): Emit {
   };
 }
 
-async function readJson(req: IncomingMessage): Promise<any> {
+/** The request body, as a JSON object; anything else, or a body that fails to arrive, throws. */
+async function readJson(req: IncomingMessage): Promise<Record<string, any>> {
   const chunks: Buffer[] = [];
   for await (const chunk of req) chunks.push(chunk as Buffer);
-  return JSON.parse(Buffer.concat(chunks).toString() || "{}");
+  const body: unknown = JSON.parse(Buffer.concat(chunks).toString() || "{}");
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new TypeError("not a JSON object");
+  return body as Record<string, any>;
 }

package/src/runtime.ts

@@ -371,10 +371,12 @@ export class Hai {
    * An events stream opened for `conversationId`: it hears every signal from
    * now on, starting with each one's latest payload, and counts toward
    * presence. The events route calls this; call it too if you serve the
-   * stream yourself, and call what it returns when the stream closes.
+   * stream yourself, and call what it returns when the stream closes. The
+   * latest payloads go through `replay` when given, so a caller can tell them
+   * from new ones.
    */
-  streamOpened(conversationId: string, emit: Emit): () => void {
-    return this.broadcast.opened(conversationId, emit);
+  streamOpened(conversationId: string, emit: Emit, replay?: Emit): () => void {
+    return this.broadcast.opened(conversationId, emit, replay);
   }
 
   /**

package/src/signals.ts

@@ -53,10 +53,11 @@ export class Broadcast {
 
   /**
    * An events stream opened for `conversationId`: it hears signals from now
-   * on, starting with each one's latest payload, and the conversation counts
-   * as present. Call what this returns when the stream closes.
+   * on, through `emit`, starting with each one's latest payload, through
+   * `replay`; and the conversation counts as present. Call what this returns
+   * when the stream closes.
    */
-  opened(conversationId: string, emit: Emit): () => void {
+  opened(conversationId: string, emit: Emit, replay: Emit = emit): () => void {
     this.start();
     this.streams.add(emit);
     let closed = false;
@@ -64,7 +65,7 @@ export class Broadcast {
     // sent is among them. A live one may come first; the latest is still the
     // latest, so at worst one arrives twice.
     void this.hearing.then(() => {
-      if (!closed) for (const event of this.latest.values()) emit(event);
+      if (!closed) for (const event of this.latest.values()) replay(event);
     });
 
     const wasLeaving = this.leaving.get(conversationId);