@haikit/client 0.3.1 → 0.5.0

package/README.md

@@ -18,6 +18,15 @@ not style the inside of your surfaces; your components emit their own class
 names and your stylesheet owns them. Every colour is a `--hai-*` custom
 property, so override what you like.
 
+## Out-of-date conversations
+
+The server closes a conversation once any surface passes its freshness window.
+The client knows each window too, so a tab left open closes on time instead of
+looking live until a click is refused: `state.expired` holds the notice,
+`send` and `interact` stop sending, and each surface's element is made `inert`
+with `data-expired` set. `chat.reset()` starts a new conversation; the default
+transcript renders the notice with a button that calls it.
+
 ## Serving it
 
 This package ships source, not a bundle. With a bundler, import normally. With

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/client",
-  "version": "0.3.1",
+  "version": "0.5.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

@@ -17,7 +17,9 @@ export interface MountChatOptions {
 
 /**
  * Builds the shell, wires the composer, renders the transcript and mounts your
- * surfaces. The ten-line path to a running app.
+ * surfaces. The ten-line path to a running app. It starts the conversation as
+ * soon as it opens, and again after `reset()`, so a server with an init tool
+ * runs it before the user types.
  *
  * It is a convenience, not the API — everything it does is built on `createChat`
  * and `renderTranscript`. Dropping to those when this shell stops fitting is the

package/src/app.js

@@ -83,11 +83,20 @@ export function mountChat({
   const send = () => {
     const text = input.value.trim();
     if (!text) return;
+    const sending = chat.send(text);
+    // send() refuses an out-of-date conversation before its first await, so
+    // this already knows: keep the text for the new conversation instead
+    if (chat.state.expired) return;
     input.value = "";
-    chat.send(text);
+    // A message queued behind a long turn can still be turned away later, if
+    // the conversation goes out of date before its turn comes. Give the text
+    // back then, unless something new has been typed since.
+    sending.then((sent) => {
+      if (!sent && !input.value) input.value = text;
+    });
   };
 
-  function renderEmpty() {
+  function emptyState() {
     const empty = h("div", "hai-empty");
     if (emptyText) empty.append(h("p", null, emptyText));
     if (suggestions.length) {
@@ -99,23 +108,40 @@ export function mountChat({
       }
       empty.append(row);
     }
-    transcript.replaceChildren(empty);
+    return empty;
   }
 
+  const renderEmpty = () => transcript.replaceChildren(emptyState());
+
   // ── wiring ─────────────────────────────────────────────────────────
-  chat.subscribe((state) => {
+  chat.subscribe((state, event) => {
+    // A new conversation starts at once, so the server's init tool — if it
+    // has one — runs before anything is typed.
+    if (event.type === "reset") chat.start();
+
     if (state.blocks.length === 0) renderEmpty();
-    else renderTranscript(transcript, chat);
+    else {
+      renderTranscript(transcript, chat);
+      // what the conversation opened with (an init tool's row, a welcome
+      // surface) doesn't replace the suggestions; the user engaging does —
+      // a first message, or an answer to something init showed
+      if (!state.blocks.some((b) => b.kind === "user" || b.kind === "interaction")) {
+        transcript.append(emptyState());
+      }
+    }
 
     modelEl.textContent = state.model;
-    sendBtn.disabled = state.status === "streaming";
+    input.disabled = state.expired !== null;
+    sendBtn.disabled = state.status === "streaming" || state.expired !== null;
     statusEl.dataset.status = state.status;
     statusEl.textContent =
       state.status === "streaming" ? "thinking…"
       : state.status === "awaiting" ? "awaiting your selection in the component above"
       : "";
     input.placeholder =
-      state.status === "awaiting" ? "pick an option above — or type to override" : placeholder;
+      state.expired ? "start a new conversation to continue"
+      : state.status === "awaiting" ? "pick an option above — or type to override"
+      : placeholder;
 
     if (inspectorBody) renderInspector(inspectorBody, state.context);
   });
@@ -129,6 +155,7 @@ export function mountChat({
   };
 
   renderEmpty();
+  chat.start();
   return chat;
 }
 

package/src/hai.css

@@ -141,6 +141,30 @@
 .hai-skeleton, .hai-surface-error { padding: 14px; font: 12px var(--hai-mono); color: var(--hai-dim); }
 .hai-surface-error { color: var(--hai-bad); }
 
+/* out of date — the runtime has made the surface inert; this only shows it */
+.hai-surface[data-expired] { opacity: .45; filter: grayscale(.7); }
+.hai-expired {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px 14px;
+  padding: 10px 12px;
+  border: 1px solid var(--hai-warn);
+  border-radius: var(--hai-radius);
+  color: var(--hai-warn);
+}
+.hai-expired .hai-body { flex: 1 1 30ch; }
+.hai-new {
+  background: var(--hai-warn);
+  color: var(--hai-bg);
+  border: none;
+  border-radius: 8px;
+  padding: 6px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
 /* ── status + composer ──────────────────────────────────────────────── */
 .hai-status { padding: 0 20px 4px; font-size: 12px; min-height: 18px; color: var(--hai-dim); }
 .hai-status[data-status="awaiting"] { color: var(--hai-warn); }
@@ -158,6 +182,7 @@
   max-height: 180px;
 }
 .hai-input:focus { outline: none; border-color: var(--hai-accent); }
+.hai-input:disabled { opacity: .5; }
 .hai-send {
   background: var(--hai-accent);
   color: var(--hai-bg);

package/src/index.d.ts

@@ -12,7 +12,7 @@ export type ConversationStatus = "idle" | "streaming" | "awaiting";
 export type SurfaceMode = "display" | "elicit";
 export type SurfaceState = "live" | "frozen";
 
-/** Blocks the server emits, plus the two the client synthesises locally. */
+/** Blocks the server emits, plus the three the client synthesises locally. */
 export type Block =
   | { kind: "user"; id: string; text: string }
   | { kind: "assistant"; id: string; text: string }
@@ -21,7 +21,9 @@ export type Block =
   /** 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 };
+  | { kind: "error"; id: string; message: string }
+  /** synthesised from `expired` — the conversation is closed; offer `reset()` */
+  | { kind: "expired"; id: string; message: string };
 
 /** The SSE frame shape. Narrow on `type` to get the specific payload. */
 export type WireEvent = { type: string } & Record<string, any>;
@@ -42,9 +44,14 @@ export interface MountCtx {
  * Returned by `mount`. `freeze` is called when the server marks the surface
  * frozen — a resolved elicit turn cannot be replayed, and the component should
  * reflect that.
+ *
+ * `expire` is called when the conversation goes out of date. By then the
+ * runtime has already made the element `inert` and set `data-expired` on it,
+ * so nothing inside can reach the server; this hook is only for looks.
  */
 export interface SurfaceInstance {
   freeze?(selection?: unknown): void;
+  expire?(): void;
 }
 
 /** Your component. `props` is whatever the surface's `props` schema produces. */
@@ -66,6 +73,8 @@ export interface SurfaceRecord {
   state: SurfaceState;
   props: unknown | null;
   instance: SurfaceInstance | null;
+  /** The element it was last mounted into. */
+  element: HTMLElement | null;
 }
 
 export interface ChatState {
@@ -76,15 +85,48 @@ export interface ChatState {
   /** handle → surface record */
   surfaces: Map<string, SurfaceRecord>;
   context: { messages: any[]; modelTokens: number; uiTokens: number };
+  /**
+   * When this conversation goes out of date, in this browser's clock (epoch
+   * ms): the earliest freshness window among its surfaces, each counted from
+   * when the request that rendered it was sent — so never later than the
+   * server's own deadline. Null while nothing it shows can go stale.
+   */
+  expiresAt: number | null;
+  /**
+   * The notice to show once the conversation is out of date, else null. From
+   * then on `send` and `interact` do nothing — the server would refuse them —
+   * until `reset()` starts a new conversation.
+   */
+  expired: string | null;
 }
 
 export interface Chat {
   /** Mutable — read it in a subscriber, do not hold references across events. */
   state: ChatState;
-  send(text: string): Promise<void>;
+  /**
+   * Queue a message. Resolves `true` once the server has taken it, `false` if
+   * it never did: the conversation went out of date first (at the call, or
+   * while it waited behind a long turn), `reset()` started a new conversation
+   * before its turn, or the server was still busy after one retry. A UI that
+   * cleared its input can then put the text back.
+   */
+  send(text: string): Promise<boolean>;
+  /**
+   * Start the conversation before the user types, so a server with an init
+   * tool runs it now and anything it shows is already there. Does nothing once
+   * this chat has a conversation, and a server without an init tool creates
+   * nothing. `mountChat` calls it when it opens and after `reset()`.
+   */
+  start(): Promise<boolean>;
   interact(handle: string, action: string, value: unknown): Promise<void>;
   /** Mounts the surface for `handle` into `element`. Null if props have not arrived. */
   mount(handle: string, element: HTMLElement): SurfaceInstance | null;
+  /**
+   * Start a new conversation on the next send. Anything queued for the old one
+   * is never sent, and a request still open is aborted — the new conversation
+   * never waits behind it. Subscribers are notified with `{ type: "reset" }`.
+   */
+  reset(): void;
   /** Returns an unsubscribe function. */
   subscribe(fn: (state: ChatState, event: WireEvent) => void): () => void;
 }

package/src/index.js

@@ -19,9 +19,18 @@ export function createChat({ endpoint = "/hai", registry }) {
     model: "",
     status: "idle",
     blocks: [],
-    /** handle -> { component, version, mode, props, state, instance } */
+    /** handle -> { component, version, mode, props, state, instance, element } */
     surfaces: new Map(),
     context: { messages: [], modelTokens: 0, uiTokens: 0 },
+    /**
+     * When this conversation goes out of date, by this browser's clock: the
+     * earliest freshness window among its surfaces, each counted from when the
+     * request that rendered it was sent — so never later than the server's own
+     * deadline. Null while nothing it shows can go stale.
+     */
+    expiresAt: null,
+    /** The notice, once the conversation is out of date. Final until `reset()`. */
+    expired: null,
   };
 
   const notify = (event) => listeners.forEach((fn) => fn(state, event));
@@ -43,25 +52,60 @@ export function createChat({ endpoint = "/hai", registry }) {
   let busy = 0;
   let chain = Promise.resolve();
 
+  /**
+   * Bumped by `reset()`. A request belongs to the conversation that was current
+   * when it was made, and carries that conversation's abort signal: reset()
+   * aborts it, so one still queued is refused by fetch before anything is sent,
+   * and one already open stops. Waiting instead would queue the new
+   * conversation's first request behind a stream that can stay open for a whole
+   * model turn. Events already read are dropped too, so a stray `hello` cannot
+   * pull this client back into the conversation it just left.
+   */
+  let generation = 0;
+  let aborter = new AbortController();
+
+  /**
+   * When the request now streaming was sent. The server stamps every surface
+   * it renders after that request arrived, so a freshness deadline counted from
+   * here is never later than the server's — however long the model takes, or
+   * a buffering proxy holds the stream back.
+   */
+  let sentAt = 0;
+
   // ── transport: SSE over POST (EventSource cannot POST) ──────────────
   function enqueue(path, body) {
+    const gen = generation;
+    const { signal } = aborter;
+    // set by pump once the server has answered this request itself
+    const outcome = { sent: false };
     busy++;
-    const run = chain.then(() => pump(path, body)).finally(() => {
-      busy--;
-    });
+    const run = chain
+      .then(() => pump(path, body, gen, signal, outcome))
+      .catch((err) => {
+        // aborted by reset(): it belonged to a conversation the user has left
+        if (gen === generation) throw err;
+      })
+      .finally(() => {
+        busy--;
+      });
     chain = run.catch(() => {});
-    return run;
+    return run.then(() => outcome.sent);
   }
 
-  const post = (path, body) =>
+  const post = (path, body, signal) =>
     fetch(endpoint + path, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ conversationId: state.conversationId, ...body }),
+      signal,
     });
 
-  async function pump(path, body) {
-    let res = await post(path, body);
+  async function pump(path, body, gen, signal, outcome) {
+    // Checked again here, not only when queued: a long turn ahead of this
+    // request can run past the deadline while it waits.
+    if (closed()) return;
+    sentAt = Date.now();
+    let res = await post(path, body, signal);
 
     // 409 means someone else holds this conversation's turn. Almost always that
     // is the previous request's own tail, milliseconds from finishing — but it
@@ -69,13 +113,21 @@ export function createChat({ endpoint = "/hai", registry }) {
     // retry covers the first and gives up honestly on the second.
     if (res.status === 409) {
       await new Promise((r) => setTimeout(r, 150));
-      res = await post(path, body);
+      // the deadline can pass during the wait, like any other queued request
+      if (closed()) return;
+      res = await post(path, body, signal); // rejects at once if reset() aborted it meanwhile
     }
+    // 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.
+    outcome.sent = res.status !== 409;
 
     // A non-SSE response carries no `data:` frames, so parsing it as a stream
     // would fail silently and the UI would just sit there.
     if (!res.ok) {
       const detail = await res.json().catch(() => ({}));
+      // an abort during that read is swallowed by the catch, so check here
+      if (gen !== generation) return;
       apply({
         type: "error",
         message:
@@ -93,10 +145,19 @@ export function createChat({ endpoint = "/hai", registry }) {
       buffer += value;
       let i;
       while ((i = buffer.indexOf("\n\n")) >= 0) {
+        // Per frame, not per chunk: a subscriber may call reset() from inside
+        // apply(), and the rest of this chunk belongs to the old conversation.
+        // The abort stops later reads; it cannot recall what is already here.
+        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)));
+        if (!line) continue;
+        const event = JSON.parse(line.slice(6));
+        // refused inside a 200: the server recorded nothing, so it did not
+        // take the message, whatever the status said
+        if (event.type === "expired") outcome.sent = false;
+        apply(event);
       }
     }
   }
@@ -133,8 +194,17 @@ export function createChat({ endpoint = "/hai", registry }) {
           state: "live",
           props: null,
           instance: null,
+          element: null,
         });
         state.blocks.push({ kind: "ui", id: `ui:${event.handle}`, handle: event.handle, toolId: event.toolId });
+        if (typeof event.staleAfterMs === "number") {
+          const at = sentAt + event.staleAfterMs;
+          if (state.expiresAt === null || at < state.expiresAt) {
+            state.expiresAt = at;
+            closingWindow = event.staleAfterMs;
+            schedule();
+          }
+        }
         break;
 
       case "ui_props": {
@@ -164,10 +234,62 @@ export function createChat({ endpoint = "/hai", registry }) {
         state.blocks.push({ kind: "error", id: `e${state.blocks.length}`, message: event.message });
         state.status = "idle";
         break;
+
+      // The local timer and the server can both report this; once is enough.
+      case "expired":
+        if (state.expired) return;
+        state.expired = event.message;
+        state.status = "idle";
+        clearTimeout(timer);
+        state.blocks.push({ kind: "expired", id: `x${state.blocks.length}`, message: event.message });
+        for (const surface of state.surfaces.values()) seal(surface);
+        break;
     }
     notify(event);
   }
 
+  // ── 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
+  // looking live until a click comes back refused.
+
+  let timer = null;
+  let closingWindow = 0;
+
+  const outOfDate = () => state.expiresAt !== null && Date.now() >= state.expiresAt;
+
+  const expireHere = () =>
+    apply({
+      type: "expired",
+      message:
+        `This conversation is out of date — results shown here were only valid for ` +
+        `${duration(closingWindow)}. Start a new conversation for current results.`,
+    });
+
+  // One timer, for the earliest deadline. setTimeout fires at once for delays
+  // past about 24.8 days, so a long wait is taken in steps.
+  function schedule() {
+    clearTimeout(timer);
+    if (state.expiresAt === null || state.expired) return;
+    const wait = Math.min(Math.max(state.expiresAt - Date.now(), 0), 2_147_483_647);
+    timer = setTimeout(() => (outOfDate() ? expireHere() : schedule()), wait);
+  }
+
+  /** Checked against the clock as well as the flag: a laptop that slept
+   *  through the deadline may not have run the timer yet. */
+  function closed() {
+    if (!state.expired && outOfDate()) expireHere();
+    return state.expired !== null;
+  }
+
+  /** Nothing inside an out-of-date surface may reach the server again. */
+  function seal(surface) {
+    if (!surface.element) return;
+    surface.element.inert = true;
+    surface.element.dataset.expired = "";
+    surface.instance?.expire?.();
+  }
+
   /**
    * Mount a surface into an element. Strict allowlist: an unregistered
    * component renders an error card, never an improvised UI.
@@ -184,6 +306,7 @@ export function createChat({ endpoint = "/hai", registry }) {
     }
 
     element.replaceChildren();
+    surface.element = element;
     surface.instance = definition.mount(element, surface.props, {
       handle,
       mode: surface.mode,
@@ -192,35 +315,93 @@ export function createChat({ endpoint = "/hai", registry }) {
       // name declared in the contract — never a tool, never a handler.
       send: (action, value) => interact(handle, action, value),
     });
+    if (state.expired) seal(surface);
     return surface.instance;
   }
 
-  // A message is queued, never dropped. mountChat has already cleared the
-  // textarea by the time this runs, so refusing a send here does not decline
-  // it — it deletes what the user typed. That was true under the old
-  // `status === "streaming"` gate too, via the Enter key, which ignores the
-  // disabled send button.
+  // A message is queued, never refused for being busy. It resolves to whether
+  // the server took it: false if the conversation went out of date first —
+  // at the call, or while it waited behind a long turn — if reset() started
+  // a new one before its turn, or if the server was still busy after the
+  // retry. A caller that cleared its input can then give the text back. The
+  // out-of-date refusal at the call happens before the first await, so such a
+  // caller can also check `state.expired` straight after calling and never
+  // clear the input at all.
   async function send(text) {
-    if (!text.trim()) return;
-    await enqueue("/chat", { message: text });
+    if (!text.trim() || closed()) return false;
+    return enqueue("/chat", { message: text });
+  }
+
+  /**
+   * Start the conversation before the user types, so a server with an init
+   * tool runs it now and whatever it shows is there first. Does nothing once
+   * this chat has a conversation. A server without an init tool answers with
+   * an empty stream and creates nothing; the first message starts the
+   * conversation, as it always has. Resolves like send().
+   */
+  async function start() {
+    if (state.conversationId || closed()) return false;
+    return enqueue("/start", {});
   }
 
   // A click carries nothing the user authored, and stacking them is worse than
   // dropping them: a double-click on a picker row would resolve it and then
-  // queue a second resolution into "component is frozen".
+  // queue a second resolution into "component is frozen". The deadline is
+  // checked first, so a click that cannot be sent still closes a conversation
+  // whose timer slept through its deadline.
   async function interact(handle, action, value) {
-    if (busy) return;
+    if (closed() || busy) return;
     await enqueue("/interact", { handle, action, value });
   }
 
+  /**
+   * Start over. The next send begins a new conversation. Anything queued for
+   * the old one is never sent, and anything still open is aborted.
+   */
+  function reset() {
+    generation++;
+    aborter.abort();
+    aborter = new AbortController();
+    clearTimeout(timer);
+    Object.assign(state, {
+      conversationId: null,
+      status: "idle",
+      blocks: [],
+      context: { messages: [], modelTokens: 0, uiTokens: 0 },
+      expiresAt: null,
+      expired: null,
+    });
+    state.surfaces.clear();
+    notify({ type: "reset" });
+  }
+
   return {
     state,
+    start,
     send,
     interact,
     mount,
+    reset,
     subscribe(fn) {
       listeners.add(fn);
       return () => listeners.delete(fn);
     },
   };
 }
+
+/** "2 hours", "15 minutes" — for a sentence a person reads. */
+function duration(ms) {
+  const units = [
+    [86_400_000, "day"],
+    [3_600_000, "hour"],
+    [60_000, "minute"],
+    [1_000, "second"],
+  ];
+  for (const [size, name] of units) {
+    if (ms >= size) {
+      const n = Math.floor(ms / size);
+      return `${n} ${name}${n === 1 ? "" : "s"}`;
+    }
+  }
+  return "under a second";
+}

package/src/transcript.js

@@ -46,6 +46,15 @@ function renderBlock(block, chat) {
     case "error":
       return h("div", "hai-block hai-error", `error: ${block.message}`);
 
+    // The conversation is closed, so the notice carries the only way forward.
+    case "expired": {
+      const el = h("div", "hai-block hai-expired");
+      const again = h("button", "hai-new", "Start a new conversation");
+      again.onclick = () => chat.reset();
+      el.append(h("div", "hai-body", block.message), again);
+      return el;
+    }
+
     // Provenance chrome. The tool row and its surface are one visual unit:
     // what produced this, with what arguments, and what the model got back.
     case "tool": {