@haikit/client 0.12.0 → 0.14.0

package/README.md

@@ -86,6 +86,43 @@ unmounted, and subscribers hear `{ type: "closed" }`. `mountChat` then removes
 its shell. A page using `renderTranscript` directly calls `closeTranscript(root)`
 when it removes a transcript, so its resize observer and scroll listener let go.
 
+## Notices
+
+When the server sends notices (`hai.notify`), its `hello` says so, and the chat
+keeps `GET /hai/events` open for the conversation. A dropped connection
+reconnects, backing off, and resumes after the last notice it saw, so none is
+missed or shown twice. `reset()` and `close()` end it.
+
+Each notice lands in `state.notices` and as a `notice` block: right after its
+surface's block when it names one, otherwise at the end. Its component comes
+from a `notices` registry, kept apart from the surface registry so the two
+never clash on a name:
+
+```js
+mountChat({
+  root, registry,
+  notices: {
+    hold_confirmed: {
+      mount(el, payload, { seq, handle }) {
+        el.textContent = `Fare held · ${payload.flightId} · ref ${payload.reference}`;
+      },
+    },
+  },
+});
+```
+
+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
+requests. If the events connection drops mid-turn, the turn runs on without
+a way to say when it ends, so the next request keeps trying, backing off, for
+up to two minutes rather than giving up after one retry.
+
+A notice's component gets **no `send`**: nothing in it can reach the server. A
+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)`.
+
 ## 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.12.0",
+  "version": "0.14.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,8 +1,10 @@
-import type { Chat, Registry } from "./index.js";
+import type { Chat, NoticeRegistry, Registry } from "./index.js";
 
 export interface MountChatOptions {
   root: HTMLElement;
   registry: Registry;
+  /** Components for the notices the server sends, by notice name. */
+  notices?: NoticeRegistry;
   /** Base path the server's two routes are mounted at. Default `/hai`. */
   endpoint?: string;
   title?: string;

package/src/app.js

@@ -86,6 +86,7 @@ function dropFavicon() {
  * @param {{
  *   root: HTMLElement,
  *   registry: Record<string, { mount: Function }>,
+ *   notices?: Record<string, { mount: Function }>,
  *   endpoint?: string,
  *   title?: string,
  *   subtitle?: string,
@@ -99,6 +100,7 @@ function dropFavicon() {
 export function mountChat({
   root,
   registry,
+  notices,
   endpoint = "/hai",
   title = "HaiKIT",
   subtitle = "",
@@ -108,7 +110,7 @@ export function mountChat({
   emptyText = "",
   theme,
 }) {
-  const chat = createChat({ endpoint, registry });
+  const chat = createChat({ endpoint, registry, notices });
   const id = `hai-${++shells}`;
 
   // Unset, the page follows the system. A pin goes on the root, where hai.css

package/src/hai.css

@@ -415,6 +415,22 @@
 }
 .hai-shimmer:nth-child(3) { width: 82%; }
 .hai-shimmer:nth-child(4) { width: 60%; }
+/* a notice: something the server said outside of any request */
+.hai-notice {
+  margin-bottom: 18px;
+  overflow: hidden;
+  border: 1px solid var(--hai-line);
+  border-radius: var(--hai-radius);
+  background: var(--hai-panel);
+}
+.hai-notice-label {
+  padding: 6px 12px;
+  border-bottom: 1px solid var(--hai-line);
+  background: var(--hai-panel-2);
+  font: 11px var(--hai-mono);
+  color: var(--hai-dim);
+}
+.hai-notice > .hai-surface-error { margin: 0; border: none; border-radius: 0; }
 .hai-surface-error {
   margin-bottom: 18px;
   padding: 11px 14px;

package/src/index.d.ts

@@ -19,7 +19,17 @@ export interface Progress {
   total?: number;
 }
 
-/** Blocks the server emits, plus the three the client synthesises locally. */
+/** A notice the server sent, as the events stream delivered it. */
+export interface NoticeRecord {
+  seq: number;
+  name: string;
+  version: number;
+  payload: unknown;
+  /** The surface it is shown beside. */
+  handle?: string;
+}
+
+/** Blocks the server emits, plus the four the client synthesises locally. */
 export type Block =
   | { kind: "user"; id: string; text: string }
   | { kind: "assistant"; id: string; text: string }
@@ -40,7 +50,9 @@ export type Block =
   /** synthesised from `error` */
   | { kind: "error"; id: string; message: string }
   /** synthesised from `expired` — the conversation is closed; offer `reset()` */
-  | { kind: "expired"; id: string; message: string };
+  | { kind: "expired"; id: string; message: string }
+  /** synthesised from `notice` — after its surface's block when it names one, else at the end */
+  | ({ kind: "notice"; id: string } & NoticeRecord);
 
 /** The SSE frame shape. Narrow on `type` to get the specific payload. */
 export type WireEvent = { type: string } & Record<string, any>;
@@ -90,6 +102,27 @@ export interface ComponentDef<P = any> {
  */
 export type Registry = Record<string, ComponentDef<any>>;
 
+/** What `mountNotice()` hands your notice component. There is no `send`. */
+export interface NoticeMountCtx {
+  seq: number;
+  version: number;
+  /** The surface it is shown beside, if any. */
+  handle?: string;
+}
+
+/** Returned by a notice's `mount`. `unmount` is called when it goes away. */
+export interface NoticeInstance {
+  unmount?(): void;
+}
+
+/** A notice component. `payload` is whatever the notice's `payload` schema produces. */
+export interface NoticeDef<P = any> {
+  mount(element: HTMLElement, payload: P, ctx: NoticeMountCtx): NoticeInstance | null | void;
+}
+
+/** The notices allowlist, by notice name. Separate from `Registry`, so names never clash. */
+export type NoticeRegistry = Record<string, NoticeDef<any>>;
+
 export interface SurfaceRecord {
   handle: string;
   component: string;
@@ -125,6 +158,8 @@ export interface ChatState {
    * until `reset()` starts a new conversation.
    */
   expired: string | null;
+  /** Notices the server has sent this conversation, in order. */
+  notices: NoticeRecord[];
 }
 
 export interface Chat {
@@ -153,6 +188,12 @@ export interface Chat {
    * instance it had before.
    */
   mount(handle: string, element: HTMLElement): SurfaceInstance | null;
+  /**
+   * Mounts the notice numbered `seq` into `element`, from the `notices`
+   * registry. Null if there is no such notice, or the chat is closed. An
+   * unregistered name renders an error card.
+   */
+  mountNotice(seq: number, element: HTMLElement): NoticeInstance | null;
   /**
    * Start a new conversation on the next send. Anything queued for the old one
    * is never sent, a request still open is aborted — the new conversation
@@ -172,4 +213,9 @@ export interface Chat {
   subscribe(fn: (state: ChatState, event: WireEvent) => void): () => void;
 }
 
-export function createChat(options: { endpoint?: string; registry: Registry }): Chat;
+/**
+ * When the server sends notices (its `hello` says so), the chat also keeps
+ * `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;

package/src/index.js

@@ -10,9 +10,9 @@
  */
 
 /**
- * @param {{endpoint?: string, registry: Record<string, {mount: Function}>}} options
+ * @param {{endpoint?: string, registry: Record<string, {mount: Function}>, notices?: Record<string, {mount: Function}>}} options
  */
-export function createChat({ endpoint = "/hai", registry }) {
+export function createChat({ endpoint = "/hai", registry, notices = {} }) {
   const listeners = new Set();
   const state = {
     conversationId: null,
@@ -31,6 +31,8 @@ export function createChat({ endpoint = "/hai", registry }) {
     expiresAt: null,
     /** The notice, once the conversation is out of date. Final until `reset()`. */
     expired: null,
+    /** Notices the server has sent this conversation, in the order they were sent. */
+    notices: [],
   };
 
   const notify = (event) => listeners.forEach((fn) => fn(state, event));
@@ -67,6 +69,25 @@ export function createChat({ endpoint = "/hai", registry }) {
   /** Set by close(): this chat is done for good, and does nothing more. */
   let shutDown = false;
 
+  /** The events stream's conversation while it is open, and how to stop it. */
+  let listening = null;
+  let listenAborter = null;
+  /**
+   * Settles when the turn a wake notice started, streaming on the events
+   * stream, is done. Until then nothing is posted: the server holds the
+   * conversation for that turn, and a message sent now would only be told 409.
+   */
+  let remote = null;
+  let endRemote = () => {};
+  /**
+   * Set when the events connection dropped while a wake turn ran. That turn
+   * still holds the conversation on the server, and its `released` is lost
+   * with the connection, so the next request is given longer to get in.
+   */
+  let cutOff = false;
+  /** seq → the mounted notice's instance and element */
+  const noticeMounts = new Map();
+
   /**
    * When the request now streaming was sent. The server stamps every surface
    * it renders after that request arrived, so a freshness deadline counted from
@@ -109,6 +130,11 @@ export function createChat({ endpoint = "/hai", registry }) {
     // The deadline is checked again here, not only when queued: a long turn
     // ahead of this request can run past it while it waits.
     if (gen !== generation || closed()) return;
+    // queued behind a wake turn, as behind one of this client's own
+    while (remote) {
+      await remote;
+      if (gen !== generation || closed()) return;
+    }
     sentAt = Date.now();
     let res = await post(path, body, signal);
 
@@ -120,8 +146,26 @@ export function createChat({ endpoint = "/hai", registry }) {
       await new Promise((r) => setTimeout(r, 150));
       // the deadline can pass during the wait, and reset() or close() come
       if (gen !== generation || closed()) return;
+      // A wake turn may be what holds it, and have said so meanwhile: wait it
+      // out, as if it had said so before this request went.
+      while (remote) {
+        await remote;
+        if (gen !== generation || closed()) return;
+      }
       res = await post(path, body, signal); // rejects at once if reset() aborted it meanwhile
     }
+    // A wake turn this client lost sight of holds the conversation until it
+    // ends, which may be a while: keep trying, backing off, for as long as a
+    // turn can hold it before its lease lapses.
+    if (res.status === 409 && cutOff) {
+      const giveUp = Date.now() + CUT_OFF_MS;
+      for (let wait = 250; res.status === 409 && Date.now() < giveUp; wait = Math.min(wait * 2, 2_000)) {
+        await new Promise((r) => setTimeout(r, wait));
+        if (gen !== generation || closed()) return;
+        res = await post(path, body, signal);
+      }
+    }
+    if (res.status !== 409) cutOff = false;
     // Anything but a second 409 means the server took the request up itself —
     // even an error — unless the stream says `expired` below. A 409 means it
     // turned the message away unread.
@@ -172,11 +216,37 @@ export function createChat({ endpoint = "/hai", registry }) {
       case "hello":
         state.conversationId = event.conversationId;
         state.model = event.model;
+        if (event.events) listen(event.conversationId);
+        break;
+
+      // From the events stream, in seq order. A reconnect resumes after the
+      // last one seen, so anything not past it is one already shown, and is
+      // dropped: one comparison, however long the backlog.
+      case "notice": {
+        if (event.seq <= (state.notices.at(-1)?.seq ?? 0)) return;
+        const { type, ...notice } = event;
+        state.notices.push(notice);
+        const block = { kind: "notice", id: `n:${event.seq}`, ...notice };
+        // beside its surface — after any notices already there — or at the end
+        const at = event.handle === undefined ? -1 : state.blocks.findIndex((b) => b.id === `ui:${event.handle}`);
+        if (at < 0) state.blocks.push(block);
+        else {
+          let i = at + 1;
+          while (state.blocks[i]?.kind === "notice" && state.blocks[i].handle === event.handle) i++;
+          state.blocks.splice(i, 0, block);
+        }
         break;
+      }
 
-      case "block_start":
-        state.blocks.push({ ...event.block });
+      // 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.
+      case "block_start": {
+        const known = state.blocks.find((b) => b.id === event.block.id);
+        if (known) Object.assign(known, event.block);
+        else state.blocks.push({ ...event.block });
         break;
+      }
 
       case "text_delta": {
         const block = state.blocks.find((b) => b.id === event.id);
@@ -202,6 +272,7 @@ export function createChat({ endpoint = "/hai", registry }) {
       }
 
       case "ui_open":
+        if (state.surfaces.has(event.handle)) break; // shown already: a rejoin's catch-up
         state.surfaces.set(event.handle, {
           handle: event.handle,
           component: event.component,
@@ -213,6 +284,14 @@ export function createChat({ endpoint = "/hai", registry }) {
           element: null,
         });
         state.blocks.push({ kind: "ui", id: `ui:${event.handle}`, handle: event.handle, toolId: event.toolId });
+        // Notices come on a stream of their own, so one can arrive before the
+        // surface it names: it went to the end then, and moves under it now.
+        // Moved within the same array, which the transcript would otherwise
+        // take for a new conversation's.
+        for (const early of state.blocks.filter((b) => b.kind === "notice" && b.handle === event.handle)) {
+          state.blocks.splice(state.blocks.indexOf(early), 1);
+          state.blocks.push(early);
+        }
         if (typeof event.staleAfterMs === "number") {
           const at = sentAt + event.staleAfterMs;
           if (state.expiresAt === null || at < state.expiresAt) {
@@ -266,6 +345,139 @@ export function createChat({ endpoint = "/hai", registry }) {
     notify(event);
   }
 
+  // ── notices ────────────────────────────────────────────────────────
+  // A GET that stays open, read the same way as a turn's stream. It ends when
+  // the conversation does — reset() or close() — and otherwise reconnects,
+  // resuming after the last notice it saw. An out-of-date conversation keeps
+  // it: a confirmation is still true once fares have gone stale.
+
+  function listen(conversationId) {
+    if (listening === conversationId || shutDown) return;
+    listenAborter?.abort();
+    listenAborter = new AbortController();
+    listening = conversationId;
+    void follow(conversationId, generation, listenAborter.signal);
+  }
+
+  async function follow(conversationId, gen, signal) {
+    let wait = 1_000;
+    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;
+      try {
+        const last = state.notices.at(-1)?.seq ?? 0;
+        const res = await fetch(`${endpoint}/events?conversationId=${encodeURIComponent(conversationId)}`, {
+          headers: last ? { "last-event-id": String(last) } : {},
+          signal,
+        });
+        // the server has no such conversation, or sends no notices: stop
+        if (res.status === 404) return;
+        if (res.ok) {
+          const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+          let buffer = "";
+          for (;;) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            buffer += value;
+            let i;
+            while ((i = buffer.indexOf("\n\n")) >= 0) {
+              if (gen !== generation) return;
+              const frame = buffer.slice(0, i);
+              buffer = buffer.slice(i + 2);
+              const line = frame.split("\n").find((l) => l.startsWith("data: "));
+              if (line) {
+                const event = JSON.parse(line.slice(6));
+                followTurn(event);
+                apply(event);
+                delivered = true;
+              }
+            }
+          }
+        }
+      } catch {
+        if (signal.aborted) return finishRemote();
+      }
+      // 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.
+      if (remote) cutOff = true;
+      finishRemote();
+      if (delivered || Date.now() - opened >= HEALTHY_MS) wait = 1_000;
+      // Dropped, refused, or the network went away: try again, backing off.
+      // reset() or close() ends the wait at once, timer and all.
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          signal.removeEventListener("abort", done);
+          resolve();
+        };
+        const timer = setTimeout(done, wait);
+        signal.addEventListener("abort", done);
+      });
+      wait = Math.min(wait * 2, 30_000);
+    }
+  }
+
+  /**
+   * Track a wake turn on the events stream: it starts with a `streaming`
+   * status, and is done with `released`, which the server sends only once it
+   * has saved the conversation and let it go. Its `idle` status comes before
+   * that save, so a message sent on it would still find the conversation held.
+   */
+  function followTurn(event) {
+    if (event.type === "status" && event.status === "streaming") {
+      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") {
+      finishRemote();
+    }
+  }
+
+  function finishRemote() {
+    remote = null;
+    endRemote();
+  }
+
+  function stopListening() {
+    finishRemote();
+    listenAborter?.abort();
+    listenAborter = null;
+    listening = null;
+  }
+
+  /**
+   * Mount a notice into an element, from the `notices` registry. As with
+   * surfaces, a name the registry doesn't list renders an error card, never
+   * an improvised UI. A notice has no `send`: it cannot reach the server.
+   */
+  function mountNotice(seq, element) {
+    const notice = state.notices.find((n) => n.seq === seq);
+    if (shutDown || !notice) return null;
+    unmountNotice(seq);
+
+    const definition = notices[notice.name];
+    if (!definition) {
+      element.textContent = `unknown notice: ${notice.name}`;
+      element.className = "hai-surface-error";
+      return null;
+    }
+    element.replaceChildren();
+    // a component may return nothing; the promise is an instance or null
+    const instance =
+      definition.mount(element, notice.payload, { seq, version: notice.version, handle: notice.handle }) ?? null;
+    noticeMounts.set(seq, instance);
+    return instance;
+  }
+
+  function unmountNotice(seq) {
+    const instance = noticeMounts.get(seq);
+    noticeMounts.delete(seq);
+    attempt(() => instance?.unmount?.());
+  }
+
   // ── expiry ─────────────────────────────────────────────────────────
   // The server refuses every request on an out-of-date conversation. Knowing
   // the deadline here too means a tab left open greys out on time, rather than
@@ -409,8 +621,11 @@ export function createChat({ endpoint = "/hai", registry }) {
     generation++;
     aborter.abort();
     aborter = new AbortController();
+    stopListening();
+    cutOff = false;
     clearTimeout(timer);
     for (const surface of state.surfaces.values()) unmount(surface);
+    for (const seq of [...noticeMounts.keys()]) unmountNotice(seq);
     Object.assign(state, {
       conversationId: null,
       status: "idle",
@@ -418,6 +633,7 @@ export function createChat({ endpoint = "/hai", registry }) {
       context: { messages: [], modelTokens: 0, uiTokens: 0 },
       expiresAt: null,
       expired: null,
+      notices: [],
     });
     state.surfaces.clear();
     notify({ type: "reset" });
@@ -434,8 +650,10 @@ export function createChat({ endpoint = "/hai", registry }) {
     shutDown = true;
     generation++;
     aborter.abort();
+    stopListening();
     clearTimeout(timer);
     for (const surface of state.surfaces.values()) unmount(surface);
+    for (const seq of [...noticeMounts.keys()]) unmountNotice(seq);
     // Every subscriber hears it, even after one that throws, and none is held
     // on to: they are let go of before they are told.
     const subscribers = [...listeners];
@@ -449,6 +667,7 @@ export function createChat({ endpoint = "/hai", registry }) {
     send,
     interact,
     mount,
+    mountNotice,
     reset,
     close,
     subscribe(fn) {
@@ -460,6 +679,16 @@ export function createChat({ endpoint = "/hai", registry }) {
   };
 }
 
+/**
+ * How long a request keeps trying a conversation held by a wake turn whose
+ * events connection dropped: the default lease, the longest that turn can
+ * hold it.
+ */
+const CUT_OFF_MS = 120_000;
+
+/** An events connection that stays up this long was healthy, whatever it delivered. */
+const HEALTHY_MS = 30_000;
+
 /**
  * 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.

package/src/transcript.js

@@ -376,6 +376,20 @@ function renderBlock(block, chat) {
       return el;
     }
 
+    // Something the server told this conversation outside of any request. The
+    // label says what kind; the app's component, from the notices registry,
+    // draws the rest. A status region, so a screen reader announces it.
+    case "notice": {
+      const el = h("div", "hai-notice");
+      el.setAttribute("role", "status");
+      el.dataset.notice = block.name;
+      el.append(h("div", "hai-notice-label", `notice · ${block.name}`));
+      const body = h("div", "hai-notice-body");
+      el.append(body);
+      queueMicrotask(() => chat.mountNotice(block.seq, body));
+      return el;
+    }
+
     default:
       return h("div", "hai-block", JSON.stringify(block));
   }