@haikit/server 0.18.0 → 0.20.0

package/dist/signals.js

@@ -0,0 +1,229 @@
+/**
+ * The channel signals and presence travel on between servers, through the
+ * store's `publish` and `subscribe`. Those are keyed by conversation; this
+ * name has a colon, which no conversation id a store issues has, so it can't
+ * be mistaken for one.
+ */
+export const SIGNAL_CHANNEL = "haikit:signals";
+/**
+ * What one Hai broadcasts, and who is watching: every open events stream in
+ * this process, each signal's latest payload, and how many conversations have
+ * a stream open, here and on the other servers sharing the store.
+ */
+export class Broadcast {
+    store;
+    graceMs;
+    heartbeatMs;
+    /** Every events stream open in this process. */
+    streams = new Set();
+    /** Each signal's latest payload, by name, for a stream that opens later. */
+    latest = new Map();
+    /** Conversations with a stream open here, and how many. */
+    open = new Map();
+    /** Conversations whose last stream closed, still counted until the grace ends. */
+    leaving = new Map();
+    /** The other servers' counts, by origin, with when each was last heard. */
+    peers = new Map();
+    listeners = new Set();
+    total = 0;
+    /** The local count other servers last heard from this one. */
+    told = 0;
+    started = false;
+    /** Settles once this server hears the others: before then, what they send is missed. */
+    hearing = Promise.resolve();
+    /** A publish to the other servers in flight, and what waits behind it: the latest of each kind only. */
+    publishing = false;
+    unsent = new Map();
+    origin = globalThis.crypto.randomUUID();
+    constructor(store, graceMs, heartbeatMs) {
+        this.store = store;
+        this.graceMs = graceMs;
+        this.heartbeatMs = heartbeatMs;
+    }
+    /** Send a signal to every stream, here and on the other servers, and keep it for later ones. */
+    send(event) {
+        this.latest.set(event.name, event);
+        for (const send of this.streams)
+            send(event);
+        this.publish({ kind: "signal", event });
+    }
+    /**
+     * An events stream opened for `conversationId`: it hears signals from now
+     * 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, emit, replay = emit) {
+        this.start();
+        this.streams.add(emit);
+        let closed = false;
+        // Each signal's latest, once this server hears the others, so one they
+        // 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())
+                    replay(event);
+        });
+        const wasLeaving = this.leaving.get(conversationId);
+        if (wasLeaving !== undefined) {
+            // back within the grace: it never stopped counting
+            clearTimeout(wasLeaving);
+            this.leaving.delete(conversationId);
+        }
+        const before = this.open.get(conversationId) ?? 0;
+        this.open.set(conversationId, before + 1);
+        if (before === 0 && wasLeaving === undefined)
+            this.changed();
+        return () => {
+            if (closed)
+                return;
+            closed = true;
+            this.streams.delete(emit);
+            const left = (this.open.get(conversationId) ?? 1) - 1;
+            if (left > 0) {
+                this.open.set(conversationId, left);
+                return;
+            }
+            this.open.delete(conversationId);
+            // A browser that drops its stream reconnects within a second or two:
+            // keep counting it a little longer, so the number doesn't flicker.
+            const timer = setTimeout(() => {
+                this.leaving.delete(conversationId);
+                this.changed();
+            }, this.graceMs);
+            timer.unref?.();
+            this.leaving.set(conversationId, timer);
+        };
+    }
+    /** Hear the total now and whenever it changes. Returns a function that stops. */
+    onPresence(listener) {
+        this.start();
+        this.listeners.add(listener);
+        try {
+            listener(this.total);
+        }
+        catch (err) {
+            // never handed its way to stop, so it must not stay
+            this.listeners.delete(listener);
+            throw err;
+        }
+        return () => void this.listeners.delete(listener);
+    }
+    /** Conversations with a stream open in this process, or within the grace. */
+    get local() {
+        return this.open.size + this.leaving.size;
+    }
+    /**
+     * Start hearing the other servers, and telling them this one's count, once.
+     * A Hai that sends signals starts as it is created, so it has the others'
+     * latest values before its first stream opens; any other, when one does.
+     */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        // For as long as this Hai lives. A store that can't listen still resolves,
+        // and hears nothing: signals and presence then stay on this server.
+        const subscribed = this.store.subscribe?.(SIGNAL_CHANNEL, (message) => this.hear(message), new AbortController().signal);
+        if (subscribed)
+            this.hearing = Promise.resolve(subscribed).catch(() => { });
+        const beat = setInterval(() => this.beat(), this.heartbeatMs);
+        beat.unref?.();
+    }
+    hear(message) {
+        let heard;
+        try {
+            heard = JSON.parse(message);
+        }
+        catch {
+            return;
+        }
+        if (!heard || heard.origin === this.origin || typeof heard.origin !== "string")
+            return;
+        if (heard.kind === "signal" && heard.event?.type === "signal" && typeof heard.event.name === "string") {
+            this.latest.set(heard.event.name, heard.event);
+            for (const send of this.streams)
+                send(heard.event);
+        }
+        else if (heard.kind === "presence" && Number.isSafeInteger(heard.count) && heard.count >= 0) {
+            // a count is a number of conversations: a whole number, never Infinity
+            const known = this.peers.has(heard.origin);
+            const count = heard.count;
+            if (count > 0)
+                this.peers.set(heard.origin, { count, heard: Date.now() });
+            else
+                this.peers.delete(heard.origin);
+            // a server it hadn't heard from yet hasn't heard from it either
+            if (!known && count > 0 && this.local > 0)
+                this.publish({ kind: "presence", count: this.local });
+            this.recount();
+        }
+    }
+    /** This server's count changed: tell the listeners, and the other servers. */
+    changed() {
+        this.recount();
+        if (this.local !== this.told) {
+            this.told = this.local;
+            this.publish({ kind: "presence", count: this.local });
+        }
+    }
+    /** On a timer: drop servers gone quiet, and remind the others this one is here. */
+    beat() {
+        this.recount();
+        if (this.local > 0)
+            this.publish({ kind: "presence", count: this.local });
+    }
+    recount() {
+        // three missed beats and a server's count no longer counts: it has gone
+        const stale = Date.now() - 3 * this.heartbeatMs;
+        let others = 0;
+        for (const [origin, peer] of this.peers) {
+            if (peer.heard < stale)
+                this.peers.delete(origin);
+            else
+                others += peer.count;
+        }
+        // a sum of whole counts, kept a safe integer however large the peers claim to be
+        const total = Math.min(this.local + others, Number.MAX_SAFE_INTEGER);
+        if (total === this.total)
+            return;
+        this.total = total;
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(total);
+            }
+            catch {
+                // one listener's mistake doesn't stop the others hearing
+            }
+        }
+    }
+    /**
+     * Tell the other servers. One publish is in flight at a time, and only the
+     * latest of each signal, and of this server's count, waits behind it: a
+     * burst of signals can't queue every obsolete payload in the store.
+     */
+    publish(body) {
+        if (!this.store.publish)
+            return;
+        this.unsent.delete(body.kind === "signal" ? `signal:${body.event.name}` : "presence");
+        this.unsent.set(body.kind === "signal" ? `signal:${body.event.name}` : "presence", body);
+        if (!this.publishing)
+            void this.flush();
+    }
+    async flush() {
+        this.publishing = true;
+        while (this.unsent.size) {
+            const [key, body] = this.unsent.entries().next().value;
+            this.unsent.delete(key);
+            try {
+                await this.store.publish(SIGNAL_CHANNEL, JSON.stringify({ origin: this.origin, ...body }));
+            }
+            catch {
+                // best effort: the other servers miss this one, and the next beat corrects presence
+            }
+        }
+        this.publishing = false;
+    }
+}
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/server",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The haikit server runtime: agent loop, elicit state machine, derived query_ui, and the interaction security boundary.",
   "keywords": [
     "haikit",
@@ -36,7 +36,7 @@
     "prepack": "npm --prefix ../.. run build"
   },
   "dependencies": {
-    "@haikit/core": "0.18.0",
+    "@haikit/core": "0.20.0",
     "@types/node": ">=22"
   },
   "publishConfig": {

package/src/routes.ts

@@ -22,7 +22,7 @@ export function nodeHandler(hai: Hai, basePath = "/hai") {
     if (!url.pathname.startsWith(basePath)) return false;
     const route = url.pathname.slice(basePath.length);
 
-    if (req.method === "GET" && route === "/events" && hai.sendsNotices) {
+    if (req.method === "GET" && route === "/events" && hai.streamsEvents) {
       await streamNotices(hai, req, res, url);
       return true;
     }
@@ -59,7 +59,7 @@ export function nodeHandler(hai: Hai, basePath = "/hai") {
         type: "hello",
         conversationId: conversation.id,
         model: hai.config.model.id,
-        ...(hai.sendsNotices ? { events: true as const } : {}),
+        ...(hai.streamsEvents ? { events: true as const } : {}),
       });
     }
 
@@ -111,6 +111,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 +153,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 +180,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 +200,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,21 +223,84 @@ 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.
   watchers.streams.add(emit);
+  // Signals from here on, starting with each one's latest; and it counts as
+  // present. A signal only matters as its latest value, so a reader that has
+  // fallen behind is sent just the newest of each once it catches up: a
+  // stalled socket holds at most one per signal, never every one sent.
+  const behind = new Map<string, WireEvent>();
+  let draining = false;
+  const flush = () => {
+    draining = false;
+    const pending = [...behind.values()];
+    behind.clear();
+    for (const event of pending) emitSignal(event);
+  };
+  const emitSignal: Emit = (event) => {
+    if (event.type !== "signal") return emit(event);
+    if (signal.aborted || res.writableEnded) return;
+    if (res.writableNeedDrain || behind.size) {
+      behind.set(event.name, event);
+      if (!draining) {
+        draining = true;
+        res.once("drain", flush);
+      }
+      return;
+    }
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+  };
+  // 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
@@ -273,6 +373,7 @@ 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;
+          markFresh();
           woken ||= n.kind === "wake";
           continue;
         }
@@ -286,6 +387,7 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
         };
         await write(`id: ${n.seq}\ndata: ${JSON.stringify(event)}\n\n`);
         after = n.seq;
+        markFresh();
         woken ||= n.kind === "wake";
       }
       if (records.length < PAGE || signal.aborted) break;
@@ -296,8 +398,15 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
 
   // a heartbeat is only for a stream gone quiet, never one already backed up
   const heartbeat = setInterval(() => res.writableNeedDrain || res.write(": ping\n\n"), HEARTBEAT_MS);
-  const wakes = wakeups(store.watch?.(conversationId, signal), signal)[Symbol.asyncIterator]();
-  try {
+  // 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;
+  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.
@@ -311,12 +420,28 @@ 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))),
+    ]);
+    void run().catch(() => {});
+    await done;
+    clearTimeout(hold);
   } finally {
     clearInterval(heartbeat);
     aborter.abort();
+    closeStream();
     watchers.streams.delete(emit);
     if (!watchers.streams.size) forgetWatchers(hai, conversationId, watchers);
-    await wakes.return?.();
+    await wakes?.return?.();
     res.end();
   }
 }
@@ -335,6 +460,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.
@@ -344,6 +476,14 @@ 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>;
 }
@@ -426,8 +566,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();
     };
@@ -442,12 +583,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 = [];
@@ -457,6 +600,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 = [];
@@ -470,7 +622,20 @@ 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(),
       // 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
@@ -518,8 +683,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. */