@haikit/client 0.18.0 → 0.20.0

package/README.md

@@ -123,6 +123,17 @@ mountChat({
 });
 ```
 
+If something on the network holds the stream back, as HTTPS-inspecting
+corporate proxies (Netskope, Zscaler) do, the chat polls instead. The server
+greets every stream with a comment the moment it opens. A stream that brings
+no bytes at all within `eventsFallbackMs` (default 8 s, a `createChat`
+option) is dropped for short polls, whose responses end and so get through.
+Notices, signals and wake turns all arrive by polling, a little later than
+they would stream. Each poll asks the server to hold for `pollHoldMs`
+(default 15 s, the server's maximum) when nothing is new; set it lower
+behind a proxy that drops requests sooner. The browser remembers it had to poll, in `localStorage`
+under `hai:events-poll`, for a day, so its next page polls from the start.
+
 A `wake` notice's turn comes down the same stream: its reply appears under the
 notice like any other. While it runs, `send` and `interact` wait for it to
 finish rather than being refused, just as they wait behind this chat's own
@@ -135,6 +146,29 @@ name the registry doesn't list renders an error card. Like a surface, `mount`
 may return `{ unmount }`. With `createChat`, mount one yourself with
 `chat.mountNotice(seq, element)`.
 
+## Signals
+
+A signal (`hai.signal`) is a broadcast to every open browser, such as how many
+people are online. It comes down the same events stream, and goes to a
+handler, never to the transcript:
+
+```js
+mountChat({
+  root, registry,
+  signals: {
+    online(payload, { version }) {
+      badge.textContent = `${payload.count} reading now`;
+    },
+  },
+});
+```
+
+Each signal's latest payload is also in `state.signals`, by name, and
+subscribers hear a `signal` event. A stream that opens is sent each signal's
+latest value first, so the handler runs as soon as the events stream is up.
+Signals carry no id: a reconnect is sent the latest values again rather than
+the ones it missed.
+
 ## Out-of-date conversations
 
 The server closes a conversation once any surface passes its freshness window.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/client",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The haikit browser runtime: streams tool payloads into interactive UI surfaces. Plain ESM, no build step, no dependencies.",
   "keywords": [
     "haikit",

package/src/app.d.ts

@@ -1,10 +1,12 @@
-import type { Chat, NoticeRegistry, Registry } from "./index.js";
+import type { Chat, NoticeRegistry, Registry, SignalRegistry } from "./index.js";
 
 export interface MountChatOptions {
   root: HTMLElement;
   registry: Registry;
   /** Components for the notices the server sends, by notice name. */
   notices?: NoticeRegistry;
+  /** Handlers for the signals the server sends, by signal name. */
+  signals?: SignalRegistry;
   /** Base path the server's two routes are mounted at. Default `/hai`. */
   endpoint?: string;
   title?: string;

package/src/app.js

@@ -101,6 +101,7 @@ export function mountChat({
   root,
   registry,
   notices,
+  signals,
   endpoint = "/hai",
   title = "HaiKIT",
   subtitle = "",
@@ -110,7 +111,7 @@ export function mountChat({
   emptyText = "",
   theme,
 }) {
-  const chat = createChat({ endpoint, registry, notices });
+  const chat = createChat({ endpoint, registry, notices, signals });
   const id = `hai-${++shells}`;
 
   // Unset, the page follows the system. A pin goes on the root, where hai.css

package/src/index.d.ts

@@ -128,6 +128,15 @@ export interface NoticeDef<P = any> {
   mount(element: HTMLElement, payload: P, ctx: NoticeMountCtx): NoticeInstance | null | void;
 }
 
+/**
+ * What the browser does with a signal: a handler, called with its payload each
+ * time one arrives. Signals are never drawn in the transcript.
+ */
+export type SignalHandler<P = any> = (payload: P, ctx: { version: number }) => void;
+
+/** Handlers for the signals the server sends, by signal name. */
+export type SignalRegistry = Record<string, SignalHandler<any>>;
+
 /** The notices allowlist, by notice name. Separate from `Registry`, so names never clash. */
 export type NoticeRegistry = Record<string, NoticeDef<any>>;
 
@@ -171,6 +180,8 @@ export interface ChatState {
   expired: string | null;
   /** Notices the server has sent this conversation, in order. */
   notices: NoticeRecord[];
+  /** Each signal's latest payload, by name, since the events stream opened. */
+  signals: Record<string, unknown>;
 }
 
 export interface Chat {
@@ -229,4 +240,20 @@ export interface Chat {
  * `GET {endpoint}/events` open for the conversation, resuming after the last
  * notice it saw if the connection drops, until `reset()` or `close()`.
  */
-export function createChat(options: { endpoint?: string; registry: Registry; notices?: NoticeRegistry }): Chat;
+export function createChat(options: {
+  endpoint?: string;
+  registry: Registry;
+  notices?: NoticeRegistry;
+  signals?: SignalRegistry;
+  /**
+   * How long the events stream may stay silent as it opens before the client
+   * decides something on the way is holding it back, and polls instead.
+   * Default 8000 ms.
+   */
+  eventsFallbackMs?: number;
+  /**
+   * When polling, how long each poll asks the server to hold if nothing new
+   * has come (the server allows at most 15 s). Default 15000 ms.
+   */
+  pollHoldMs?: number;
+}): Chat;

package/src/index.js

@@ -12,7 +12,14 @@
 /**
  * @param {{endpoint?: string, registry: Record<string, {mount: Function}>, notices?: Record<string, {mount: Function}>}} options
  */
-export function createChat({ endpoint = "/hai", registry, notices = {} }) {
+export function createChat({
+  endpoint = "/hai",
+  registry,
+  notices = {},
+  signals = {},
+  eventsFallbackMs = EVENTS_FALLBACK_MS,
+  pollHoldMs = POLL_HOLD_MS,
+}) {
   const listeners = new Set();
   const state = {
     conversationId: null,
@@ -33,6 +40,11 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     expired: null,
     /** Notices the server has sent this conversation, in the order they were sent. */
     notices: [],
+    /**
+     * Each signal's latest payload, by name, since the events stream opened.
+     * No prototype, so a signal can be named anything, `__proto__` included.
+     */
+    signals: Object.create(null),
   };
 
   const notify = (event) => listeners.forEach((fn) => fn(state, event));
@@ -106,6 +118,15 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
    * so `state.notices` alone would miss them.
    */
   let resumeAfter = 0;
+  /**
+   * Whether the events stream is read by polling: a browser behind something
+   * that holds a stream back until it ends switches to it, and remembers that
+   * for a day, so its next page skips the wait.
+   */
+  let polling = rememberedPolling();
+  /** The wake turn showing, and the last one seen to end, by number: a poll says the latter. */
+  let turnShowing = 0;
+  let turnSeen = 0;
 
   // ── transport: SSE over POST (EventSource cannot POST) ──────────────
   function enqueue(path, body) {
@@ -251,6 +272,16 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         break;
       }
 
+      // A broadcast to every open browser. Never stored, so there is nothing
+      // to resume: its latest value is kept, and its handler hears it.
+      case "signal": {
+        state.signals[event.name] = event.payload;
+        // the app's own handlers only, never one an object inherits, such as `toString`
+        const handler = Object.hasOwn(signals, event.name) ? signals[event.name] : undefined;
+        if (typeof handler === "function") attempt(() => handler(event.payload, { version: event.version }));
+        break;
+      }
+
       // A stream that rejoins a wake turn is sent what the turn has shown so
       // far: a block this client already has is brought up to date, not added
       // again.
@@ -428,17 +459,40 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
 
   async function follow(conversationId, gen, signal) {
     let wait = 1_000;
+    // a poll's first answer comes at once, with the latest of each signal
+    let firstPoll = true;
     while (gen === generation && !signal.aborted) {
       // A connection that delivered a notice, or stayed up a while, was
       // healthy, and the next drop starts the backoff over. One that drops
       // straight after it opens was not, however often the server says 200.
       const opened = Date.now();
       let delivered = false;
+      // This attempt's own abort, so silence can end it without ending the chat.
+      const attempt = new AbortController();
+      const stop = () => attempt.abort();
+      signal.addEventListener("abort", stop, { once: true });
+      // The server sends a comment the moment a stream opens. Nothing at all
+      // within eventsFallbackMs means something on the way, such as a proxy
+      // that inspects traffic, is holding the stream back until it ends,
+      // which it never does: poll instead, with responses that end.
+      let silent = false;
+      const silence = polling
+        ? null
+        : setTimeout(() => {
+            silent = true;
+            attempt.abort();
+          }, eventsFallbackMs);
+
+      let ended = false;
       try {
         const last = Math.max(resumeAfter, state.notices.at(-1)?.seq ?? 0);
-        const res = await fetch(`${endpoint}/events?conversationId=${encodeURIComponent(conversationId)}`, {
+        // with a fingerprint of the signals it has, so a poll knows if their latest are news
+        const query = polling
+          ? `&poll=${firstPoll ? "now" : "1"}&wait=${pollHoldMs}&turn=${turnSeen}&signals=${signalsDigest(Object.entries(state.signals))}`
+          : "";
+        const res = await fetch(`${endpoint}/events?conversationId=${encodeURIComponent(conversationId)}${query}`, {
           headers: last ? { "last-event-id": String(last) } : {},
-          signal,
+          signal: attempt.signal,
         });
         // the server has no such conversation, or sends no notices: stop
         if (res.status === 404) return;
@@ -447,7 +501,11 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
           let buffer = "";
           for (;;) {
             const { value, done } = await reader.read();
-            if (done) break;
+            clearTimeout(silence);
+            if (done) {
+              ended = true;
+              break;
+            }
             buffer += value;
             let i;
             while ((i = buffer.indexOf("\n\n")) >= 0) {
@@ -474,6 +532,22 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
         }
       } catch {
         if (signal.aborted) return finishRemote();
+      } finally {
+        clearTimeout(silence);
+        signal.removeEventListener("abort", stop);
+      }
+      if (silent) {
+        polling = true;
+        rememberPolling();
+        continue;
+      }
+      // A poll that ended as polls do: the next one at once, a moment apart.
+      // A wake turn it was part way through goes on in the next, which is sent
+      // what the turn has shown so far, or that none is running.
+      if (polling && ended && gen === generation && !signal.aborted) {
+        firstPoll = false;
+        await pause(Math.max(0, POLL_GAP_MS - (Date.now() - opened)), signal);
+        continue;
       }
       // A turn cut off with its connection runs on, but nothing will say when
       // it ends: stop waiting for it, and give the next request longer instead.
@@ -503,10 +577,13 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
    */
   function followTurn(event) {
     if (event.type === "status" && event.status === "streaming") {
+      // the turn's number, so a poll can say which turn it last saw end
+      if (typeof event.wake === "number") turnShowing = event.wake;
       if (!remote) remote = new Promise((resolve) => (endRemote = resolve));
       // surfaces it shows are stamped after this, as a request's are after it is sent
       sentAt = Date.now();
     } else if (event.type === "released") {
+      if (turnShowing > turnSeen) turnSeen = turnShowing;
       finishRemote();
     }
   }
@@ -732,6 +809,9 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
     stopListening();
     cutOff = false;
     resumeAfter = 0;
+    // turns are numbered per conversation
+    turnShowing = 0;
+    turnSeen = 0;
     clearTimeout(timer);
     for (const surface of state.surfaces.values()) unmount(surface);
     for (const seq of [...noticeMounts.keys()]) unmountNotice(seq);
@@ -743,6 +823,7 @@ export function createChat({ endpoint = "/hai", registry, notices = {} }) {
       expiresAt: null,
       expired: null,
       notices: [],
+      signals: Object.create(null),
     });
     state.surfaces.clear();
     replacedBy.clear();
@@ -799,6 +880,56 @@ const CUT_OFF_MS = 120_000;
 /** An events connection that stays up this long was healthy, whatever it delivered. */
 const HEALTHY_MS = 30_000;
 
+/** How long the events stream may stay silent as it opens before the client polls instead. */
+const EVENTS_FALLBACK_MS = 8_000;
+/** The least time from one poll's start to the next's. */
+const POLL_GAP_MS = 250;
+/** How long a poll asks the server to hold when nothing new has come: the server allows at most 15 s. */
+const POLL_HOLD_MS = 15_000;
+/** Where a browser remembers it had to poll, and for how long. */
+const POLL_KEY = "hai:events-poll";
+const POLL_REMEMBER_MS = 24 * 60 * 60_000;
+
+/**
+ * A short fingerprint of signal values, by name, as a poll reports what this
+ * browser has. The server computes the same (packages/server/src/routes.ts);
+ * change both together.
+ */
+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);
+}
+
+function rememberedPolling() {
+  try {
+    const at = Number(localStorage.getItem(POLL_KEY));
+    return Number.isFinite(at) && at > 0 && Date.now() - at < POLL_REMEMBER_MS;
+  } catch {
+    return false;
+  }
+}
+
+function rememberPolling() {
+  try {
+    localStorage.setItem(POLL_KEY, String(Date.now()));
+  } catch {}
+}
+
+/** Wait `ms`, or until `signal` aborts. */
+function pause(ms, signal) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done);
+  });
+}
+
 /**
  * Run `fn`, reporting what it throws without letting it stop the caller: the
  * error surfaces as an uncaught one would, after the caller has finished.