@haikit/client 0.11.0 → 0.13.0

package/README.md

@@ -86,6 +86,36 @@ 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 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.11.0",
+  "version": "0.13.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

@@ -327,7 +327,26 @@
   font: 12px var(--hai-mono);
   color: var(--hai-dim);
 }
-.hai-tstatus { color: var(--hai-dim); white-space: nowrap; font-variant-numeric: tabular-nums; }
+.hai-tstatus {
+  max-width: 50%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--hai-dim);
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+/* a running tool's progress: the message gives way before the count does */
+.hai-tprogress { display: flex; min-width: 0; white-space: pre; }
+.hai-tmessage { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+.hai-tcount { flex: none; }
+/* …and a bar along the bottom edge of its row */
+.hai-tool summary:has(.hai-tbar) { position: relative; }
+.hai-tbar {
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 2px;
+  background: linear-gradient(to right, var(--hai-accent) var(--hai-progress, 0%), transparent 0);
+}
 .hai-chevron { width: 14px; height: 14px; color: var(--hai-dim); transition: transform .15s; }
 .hai-tool[open] .hai-chevron { transform: rotate(90deg); }
 
@@ -396,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

@@ -12,18 +12,47 @@ export type ConversationStatus = "idle" | "streaming" | "awaiting";
 export type SurfaceMode = "display" | "elicit";
 export type SurfaceState = "live" | "frozen";
 
-/** Blocks the server emits, plus the three the client synthesises locally. */
+/** How far a running tool has got, as its `ctx.progress` calls said. */
+export interface Progress {
+  message?: string;
+  done?: number;
+  total?: number;
+}
+
+/** 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 }
-  | { kind: "tool"; id: string; name: string; input: unknown; status: string; ms?: number; result?: string }
+  | {
+      kind: "tool";
+      id: string;
+      name: string;
+      input: unknown;
+      status: string;
+      ms?: number;
+      result?: string;
+      /** What the tool's `ctx.progress` calls have said so far, merged. */
+      progress?: Progress;
+    }
   | { kind: "interaction"; id: string; handle: string; label: string }
   /** synthesised from `ui_open` — the slot a surface mounts into */
   | { kind: "ui"; id: string; handle: string; toolId: string }
   /** 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>;
@@ -73,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;
@@ -108,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 {
@@ -136,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
@@ -155,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,12 @@ 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;
+  /** 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
@@ -172,8 +180,28 @@ 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 });
         break;
@@ -190,6 +218,17 @@ export function createChat({ endpoint = "/hai", registry }) {
         break;
       }
 
+      // A frame carries only the fields its call named, so it is merged: a
+      // tool says what it is doing once, then counts.
+      case "progress": {
+        const block = state.blocks.find((b) => b.id === event.toolId);
+        if (block?.kind === "tool") {
+          const { type, toolId, ...fields } = event;
+          block.progress = { ...block.progress, ...fields };
+        }
+        break;
+      }
+
       case "ui_open":
         state.surfaces.set(event.handle, {
           handle: event.handle,
@@ -202,6 +241,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) {
@@ -255,6 +302,111 @@ 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) {
+                apply(JSON.parse(line.slice(6)));
+                delivered = true;
+              }
+            }
+          }
+        }
+      } catch {
+        if (signal.aborted) return;
+      }
+      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);
+    }
+  }
+
+  function stopListening() {
+    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
@@ -398,8 +550,10 @@ export function createChat({ endpoint = "/hai", registry }) {
     generation++;
     aborter.abort();
     aborter = new AbortController();
+    stopListening();
     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",
@@ -407,6 +561,7 @@ export function createChat({ endpoint = "/hai", registry }) {
       context: { messages: [], modelTokens: 0, uiTokens: 0 },
       expiresAt: null,
       expired: null,
+      notices: [],
     });
     state.surfaces.clear();
     notify({ type: "reset" });
@@ -423,8 +578,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];
@@ -438,6 +595,7 @@ export function createChat({ endpoint = "/hai", registry }) {
     send,
     interact,
     mount,
+    mountNotice,
     reset,
     close,
     subscribe(fn) {
@@ -449,6 +607,9 @@ export function createChat({ endpoint = "/hai", registry }) {
   };
 }
 
+/** 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

@@ -46,8 +46,13 @@ export function renderTranscript(root, chat) {
       el = renderBlock(block, chat);
       // an expanded tool row stays expanded when its status changes
       if (before?.el.open) el.open = true;
+    } else if (block.progress !== before.progress) {
+      // Progress changes the row in place. Rebuilt for every frame, a row a
+      // keyboard user is on would take their focus up to ten times a second.
+      const parts = rowParts.get(el);
+      if (parts) showStatus(parts, block, toolStatus(block, chat));
     }
-    shown.set(block.id, { el, look });
+    shown.set(block.id, { el, look, progress: block.progress });
     return el;
   });
   follow.shown = shown;
@@ -77,7 +82,8 @@ export function closeTranscript(root) {
 function appearance(block, chat) {
   // a surface shows a skeleton until its props arrive, and then itself for good
   if (block.kind === "ui") return chat.state.surfaces.get(block.handle)?.props ? "mounted" : "loading";
-  if (block.kind === "tool") return JSON.stringify({ ...block, status: toolStatus(block, chat) });
+  // progress is left out: it changes the row in place (see renderTranscript)
+  if (block.kind === "tool") return JSON.stringify({ ...block, progress: undefined, status: toolStatus(block, chat) });
   return JSON.stringify(block);
 }
 
@@ -116,6 +122,46 @@ const STATUS_TEXT = {
   error: (ms) => `failed · ${ms} ms`,
 };
 
+/** "2/4", or "2" when the tool hasn't said how many in all. */
+function progressCount({ done, total }) {
+  return total !== undefined ? `${done ?? 0}/${total}` : done !== undefined ? String(done) : "";
+}
+
+/** A tool row's element → its status text and progress bar, which progress changes in place. */
+const rowParts = new WeakMap();
+
+/**
+ * Fill in what a tool row says of its call. While it runs, that is its
+ * progress once it has reported some: the message gives way first on a narrow
+ * row, so the count stays readable, and the bar fills once there is a total.
+ */
+function showStatus({ status: text, bar }, block, status) {
+  const progress = status === "running" ? block.progress : undefined;
+  const message = progress?.message ?? "";
+  const count = progress ? progressCount(progress) : "";
+  if (message || count) {
+    text.className = "hai-tstatus hai-tprogress";
+    const parts = [];
+    if (message) parts.push(h("span", "hai-tmessage", message));
+    if (message && count) parts.push(h("span", null, " · "));
+    if (count) parts.push(h("span", "hai-tcount", count));
+    text.replaceChildren(...parts);
+  } else {
+    text.className = "hai-tstatus";
+    text.textContent = (STATUS_TEXT[status] ?? ((ms) => `${ms} ms`))(block.ms);
+  }
+
+  if (!bar) return;
+  const total = progress?.total;
+  bar.hidden = !total;
+  if (!total) return;
+  const done = Math.min(progress.done ?? 0, total);
+  bar.setAttribute("aria-valuemax", String(total));
+  bar.setAttribute("aria-valuenow", String(done));
+  bar.setAttribute("aria-valuetext", [message, `${done} of ${total}`].filter(Boolean).join(" · "));
+  bar.style.setProperty("--hai-progress", `${(done / total) * 100}%`);
+}
+
 function statusMark(status) {
   const mark = h("span", "hai-ticon");
   if (status === "running") mark.append(h("span", "hai-spinner"));
@@ -283,13 +329,24 @@ function renderBlock(block, chat) {
       const status = toolStatus(block, chat);
       const el = h("details", `hai-block hai-tool hai-status-${status}`);
       const summary = h("summary");
+      const parts = { status: h("span", "hai-tstatus"), bar: null };
       summary.append(
         statusMark(status),
         h("span", "hai-tname", block.name),
         h("span", "hai-targs", JSON.stringify(block.input)),
-        h("span", "hai-tstatus", (STATUS_TEXT[status] ?? ((ms) => `${ms} ms`))(block.ms)),
+        parts.status,
         icon("chevron", "hai-icon hai-chevron"),
       );
+      // a thin bar along the row's bottom edge, for progress with a total
+      if (status === "running") {
+        parts.bar = h("span", "hai-tbar");
+        parts.bar.setAttribute("role", "progressbar");
+        parts.bar.setAttribute("aria-label", `${block.name} progress`);
+        parts.bar.setAttribute("aria-valuemin", "0");
+        summary.append(parts.bar);
+      }
+      rowParts.set(el, parts);
+      showStatus(parts, block, status);
       el.append(summary);
       const detail = h("div", "hai-tool-detail");
       detail.append(
@@ -319,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));
   }