@haikit/server 0.19.0 → 0.20.1

package/README.md

@@ -205,6 +205,36 @@ the inspector, the same as a digest. It reads the store every two
 seconds, and a store with `watch` wakes it the moment a notice lands. The
 two-second read stays even then, so a lost wake-up only delays a notice.
 
+**For browsers behind a proxy that holds streams back, the route also
+polls.** Corporate security tools that inspect HTTPS (Netskope, Zscaler and
+the like) often hold a response until it ends, and a stream never ends, so a
+browser behind one hears nothing. The route sends a comment (`: open`) the
+moment a stream opens; a client that hears nothing at all switches to
+polling, with `?poll=1`. A poll sends what's waiting and ends, and responses
+that end get through any proxy:
+
+- **What a poll holds for.** It sends any notices after `Last-Event-ID`, each
+  signal's latest value, and any frames of a wake turn under way. It ends
+  about 250 ms after something new goes out, or after 15 s with nothing new.
+  `wait` asks for a shorter hold.
+- **Signals.** The latest values count as new only when the client lacks
+  them. The poll's `signals` parameter is a fingerprint of the values the
+  client holds.
+- **First poll and wake turns.** `?poll=now` answers at once, for a page's
+  first poll. A wake turn that runs across several polls carries on through
+  the replay of what it has shown so far. One that ends between two polls is
+  kept for a minute (the last five at most): a poll whose `turn` parameter
+  says it hasn't seen a turn end is sent all of each such turn, oldest first,
+  its last text, `idle` and `released` included. A poll that finds no turn running says so with `released`, so
+  the browser never waits for one that has ended.
+- **More than one server.** Each server keeps hearing a conversation for a
+  minute after its last stream or poll closes. A browser whose polls move
+  between servers still gets a turn that ended on another one. A poll that
+  lands on a server that hasn't served that conversation in the past minute
+  can miss it; sticky sessions avoid that.
+- **Presence.** A tab polling back to back stays inside the presence grace,
+  so it keeps counting.
+
 **A `wake` notice starts a turn of its own.** Declare one with `kind: "wake"`,
 and its `model` function must return text, since the turn is the model's
 answer to it:

package/dist/routes.d.ts

@@ -2,7 +2,8 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Hai } 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.
@@ -14,4 +15,10 @@ import type { Hai } from "./runtime.js";
  * conversation, and where to resume.
  */
 export declare function nodeHandler(hai: Hai, basePath?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+/**
+ * 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 declare function signalsDigest(entries: [string, unknown][]): string;
 //# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,SAAS,IACxB,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC,CAuF1F"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAe,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,SAAS,IACxB,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC,CA+B1F;AA8GD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAKlE"}

package/dist/routes.js

@@ -1,7 +1,8 @@
 import { isConversationBusy, isStaleLease } from "@haikit/core";
 /**
  * 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.
@@ -14,99 +15,170 @@ import { isConversationBusy, isStaleLease } from "@haikit/core";
  */
 export function nodeHandler(hai, basePath = "/hai") {
     return async function handle(req, res) {
-        const url = new URL(req.url ?? "/", "http://localhost");
+        let 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.message }));
-            return true;
+            failed(res, err);
         }
-        const emit = openSSE(res);
-        if (route === "/chat" || route === "/start") {
-            emit({
-                type: "hello",
-                conversationId: conversation.id,
-                model: hai.config.model.id,
-                ...(hai.streamsEvents ? { events: true } : {}),
-            });
+        return true;
+    };
+}
+/**
+ * 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, err) {
+    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 })}\n\n`);
+        res.end();
+    }
+}
+/** One of the three POST routes, once the request is known to be one. */
+async function respond(hai, route, req, res) {
+    let body;
+    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;
+    }
+    // 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.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 } : {}),
+        });
+    }
+    let superseded = false;
+    try {
+        if (route === "/chat") {
+            await hai.send(conversation, String(body.message ?? ""), emit);
+        }
+        else if (route === "/start") {
+            await hai.start(conversation, emit);
         }
-        let superseded = false;
+        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.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.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.message });
-            }
-        }
-        res.end();
-        return true;
-    };
+    }
+    res.end();
 }
 /**
  * The longest a notice waits to be read. A store's `watch` makes it sooner;
  * 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) {
+    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;
 /** Notices read from the store at a time, so a long backlog goes out page by page. */
@@ -126,6 +198,18 @@ const PAGE = 100;
 async function streamNotices(hai, req, res, 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;
     const first = await store.getNotices(conversationId, after, PAGE);
@@ -139,6 +223,7 @@ async function streamNotices(hai, req, res, url) {
     // 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;
@@ -159,8 +244,11 @@ async function streamNotices(hai, req, res, url) {
         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());
@@ -178,12 +266,20 @@ async function streamNotices(hai, req, res, url) {
             signal.addEventListener("abort", done);
         });
     };
-    // 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 = (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((resolve) => (markFresh = resolve));
+    // A frame out, and a stream the browser has left takes no more.
+    const send = (event) => {
         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 = (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.
@@ -216,7 +312,23 @@ async function streamNotices(hai, req, res, url) {
         }
         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 = [];
+    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.
@@ -224,16 +336,38 @@ async function streamNotices(hai, req, res, url) {
     // freshness from when the surface was stored, not from now.
     if (watchers.live)
         for (const event of watchers.shown)
-            emit(aged(event));
+            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 = null;
     let again = false;
     const wake = () => {
         if (!hai.wakes || signal.aborted)
             return;
+        if (watchers.wakeRead <= watchers.wakeSettled)
+            return;
         if (waking) {
             again = true;
             return;
@@ -241,12 +375,24 @@ async function streamNotices(hai, req, res, url) {
         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 = "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.message }))
             .finally(() => {
@@ -301,7 +447,11 @@ async function streamNotices(hai, req, res, url) {
                 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 = {
@@ -314,7 +464,11 @@ async function streamNotices(hai, req, res, url) {
                 };
                 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;
@@ -328,16 +482,15 @@ async function streamNotices(hai, req, res, url) {
     // 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((resolve) => {
-                if (signal.aborted)
-                    resolve();
-                else
-                    signal.addEventListener("abort", () => resolve(), { once: true });
-            });
-            return;
-        }
+    const left = new Promise((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.
@@ -352,6 +505,24 @@ async function streamNotices(hai, req, res, url) {
             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;
+        const done = Promise.race([
+            left,
+            freshened.then(() => new Promise((resolve) => setTimeout(resolve, POLL_GATHER_MS))),
+            new Promise((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);
@@ -450,8 +621,9 @@ function watchersOf(hai, conversationId) {
         const origin = originOf(hai);
         // Hearing other processes' wake turns lasts as long as this entry does.
         const hearing = new AbortController();
+        let lingering = null;
         const forget = () => {
-            if (map.get(conversationId) !== fresh || fresh.pending || fresh.streams.size || fresh.live)
+            if (map.get(conversationId) !== fresh || fresh.pending || fresh.streams.size || fresh.live || fresh.ended.length || lingering)
                 return;
             map.delete(conversationId);
             hearing.abort();
@@ -466,6 +638,7 @@ function watchersOf(hai, conversationId) {
         // 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 = null;
+        let currentNumber;
         let newest = 0;
         const deliver = (event, turn, number) => {
             if (event.type === "status" && event.status === "streaming") {
@@ -473,6 +646,7 @@ function watchersOf(hai, conversationId) {
                     if (number !== undefined && number < newest)
                         return; // an older turn's late start
                     current = turn;
+                    currentNumber = number;
                     if (number !== undefined)
                         newest = number;
                     fresh.live = true;
@@ -484,6 +658,15 @@ function watchersOf(hai, conversationId) {
             }
             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 = [];
@@ -498,8 +681,25 @@ function watchersOf(hai, conversationId) {
             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.
@@ -542,8 +742,9 @@ function watchersOf(hai, conversationId) {
 }
 function forgetWatchers(_hai, _conversationId, 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. */
 const WAKE_RETRY_MS = 250;
@@ -607,10 +808,14 @@ function openSSE(res) {
         res.write(`data: ${JSON.stringify(event)}\n\n`);
     };
 }
+/** The request body, as a JSON object; anything else, or a body that fails to arrive, throws. */
 async function readJson(req) {
     const chunks = [];
     for await (const chunk of req)
         chunks.push(chunk);
-    return JSON.parse(Buffer.concat(chunks).toString() || "{}");
+    const body = JSON.parse(Buffer.concat(chunks).toString() || "{}");
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        throw new TypeError("not a JSON object");
+    return body;
 }
 //# sourceMappingURL=routes.js.map