@haikit/server 0.11.0 → 0.13.0

package/src/routes.ts

@@ -1,23 +1,32 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { isConversationBusy, isStaleLease } from "@haikit/core";
-import type { Emit, WireEvent } from "@haikit/core";
+import type { Emit, NoticeRecord, WireEvent } from "@haikit/core";
 import type { Hai } from "./runtime.js";
 
 /**
- * Node http handler for the three routes. Returns true if it handled the
- * request.
+ * Node http handler for the three routes, and a fourth when the app sends
+ * notices. Returns true if it handled the request.
  *
- * All three stream SSE: chat and interact because both can resume the agent
- * loop, start because the init tool it runs can render surfaces. Note what the
- * interact route accepts: {handle, action, value} and nothing else. The client
- * cannot name a tool, a handler, or an action target.
+ * The three POST routes stream SSE: chat and interact because both can resume
+ * the agent loop, start because the init tool it runs can render surfaces.
+ * Note what the interact route accepts: {handle, action, value} and nothing
+ * else. The client cannot name a tool, a handler, or an action target.
+ *
+ * `GET /events` streams a conversation's notices. It accepts nothing from the
+ * browser beyond which conversation, and where to resume.
  */
 export function nodeHandler(hai: Hai, basePath = "/hai") {
   return async function handle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
     const url = new URL(req.url ?? "/", "http://localhost");
-    if (req.method !== "POST" || !url.pathname.startsWith(basePath)) return false;
-
+    if (!url.pathname.startsWith(basePath)) return false;
     const route = url.pathname.slice(basePath.length);
+
+    if (req.method === "GET" && route === "/events" && hai.sendsNotices) {
+      await streamNotices(hai, req, res, url);
+      return true;
+    }
+
+    if (req.method !== "POST") return false;
     if (route !== "/chat" && route !== "/interact" && route !== "/start") return false;
 
     const body = await readJson(req);
@@ -45,7 +54,12 @@ export function nodeHandler(hai: Hai, basePath = "/hai") {
 
     const emit = openSSE(res);
     if (route === "/chat" || route === "/start") {
-      emit({ type: "hello", conversationId: conversation.id, model: hai.config.model.id });
+      emit({
+        type: "hello",
+        conversationId: conversation.id,
+        model: hai.config.model.id,
+        ...(hai.sendsNotices ? { events: true as const } : {}),
+      });
     }
 
     let superseded = false;
@@ -91,6 +105,149 @@ export function nodeHandler(hai: Hai, basePath = "/hai") {
   };
 }
 
+/**
+ * The longest a notice waits to be read. A store's `watch` makes it sooner;
+ * this is what still finds a notice whose wake-up was lost.
+ */
+const POLL_MS = 2_000;
+/** Proxies drop a stream that says nothing for long; a comment keeps it open. */
+const HEARTBEAT_MS = 25_000;
+
+/** Notices read from the store at a time, so a long backlog goes out page by page. */
+const PAGE = 100;
+
+/**
+ * Stream a conversation's notices: every one after where the browser has got
+ * to (`Last-Event-ID` on a reconnect, else `?after=`), then each as it lands.
+ * Takes no lease and writes nothing. Each notice goes out as its payload; its
+ * model text is not in it: that reaches the browser only as part of the
+ * history, in the `context` event, once a turn has taken it in.
+ *
+ * Bounded both ways. The store is read a page at a time, so a conversation
+ * with years of notices is never held in memory at once, and nothing more is
+ * written while the socket is still taking what was, so a reader that is slow
+ * cannot make the server buffer every notice for it.
+ */
+async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse, url: URL) {
+  const { store } = hai.config;
+  const conversationId = url.searchParams.get("conversationId") ?? "";
+  const resume = Number(req.headers["last-event-id"] ?? url.searchParams.get("after") ?? 0);
+  let after = Number.isSafeInteger(resume) && resume > 0 ? resume : 0;
+
+  const first = await store.getNotices(conversationId, after, PAGE);
+  if (first === null) {
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "unknown conversation" }));
+    return;
+  }
+
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    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.
+  res.flushHeaders();
+  const aborter = new AbortController();
+  const { signal } = aborter;
+  res.on("close", () => aborter.abort());
+
+  // Resolves once the socket has taken what is queued, or the browser has gone.
+  const write = async (chunk: string) => {
+    if (res.write(chunk)) return;
+    await new Promise<void>((resolve) => {
+      const done = () => {
+        res.off("drain", done);
+        signal.removeEventListener("abort", done);
+        resolve();
+      };
+      res.on("drain", done);
+      signal.addEventListener("abort", done);
+    });
+  };
+
+  // Everything after `after`, a page at a time, until a page comes back short.
+  // A conversation deleted since the stream opened ends it: there is nothing
+  // more to wait for, and the browser's reconnect is then refused.
+  const catchUp = async (page: NoticeRecord[] | null = null) => {
+    for (;;) {
+      const records = page ?? (await store.getNotices(conversationId, after, PAGE));
+      if (records === null) return aborter.abort();
+      for (const n of records) {
+        if (signal.aborted) return;
+        if (n.seq <= after) continue;
+        const event: WireEvent = {
+          type: "notice",
+          seq: n.seq,
+          name: n.name,
+          version: n.version,
+          payload: n.payload,
+          ...(n.handle === undefined ? {} : { handle: n.handle }),
+        };
+        await write(`id: ${n.seq}\ndata: ${JSON.stringify(event)}\n\n`);
+        after = n.seq;
+      }
+      if (records.length < PAGE || signal.aborted) return;
+      page = null;
+    }
+  };
+
+  // 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 {
+    await catchUp(first);
+    // Watching starts before the next read, so a notice that landed after the
+    // backlog was read is either in that read or wakes the loop.
+    let next = wakes.next();
+    await catchUp();
+    while (!signal.aborted) {
+      if ((await next).done) break;
+      next = wakes.next();
+      await catchUp();
+    }
+  } finally {
+    clearInterval(heartbeat);
+    aborter.abort();
+    await wakes.return?.();
+    res.end();
+  }
+}
+
+/**
+ * When the events route reads next: every POLL_MS, and sooner whenever the
+ * store's `watch` says a notice may have landed. `watch` alone is not enough.
+ * A wake-up can be lost, and a LISTEN connection can drop, and either would
+ * leave the stream open on heartbeats with a notice it never reads. A `watch`
+ * that ends or fails leaves the reads every POLL_MS to carry on.
+ */
+async function* wakeups(watch: AsyncIterable<void> | undefined, signal: AbortSignal): AsyncIterable<void> {
+  const steps = watch?.[Symbol.asyncIterator]();
+  // started now, so the watch is listening before the caller's next read
+  let step: Promise<unknown> | null = steps?.next().then((r) => !r.done, () => false) ?? null;
+  try {
+    while (!signal.aborted) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let onAbort: (() => void) | undefined;
+      const tick = new Promise<"tick">((resolve) => {
+        onAbort = () => resolve("tick");
+        timer = setTimeout(onAbort, POLL_MS);
+        signal.addEventListener("abort", onAbort);
+      });
+      const woke = await Promise.race(step ? [tick, step] : [tick]);
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort!);
+      if (signal.aborted) return;
+      // the watch stepped: listen for the next; it ended or failed: stop listening
+      if (woke !== "tick") step = woke ? steps!.next().then((r) => !r.done, () => false) : null;
+      yield;
+    }
+  } finally {
+    await steps?.return?.();
+  }
+}
+
 function openSSE(res: ServerResponse): Emit {
   res.writeHead(200, {
     "content-type": "text/event-stream",

package/src/runtime.ts

@@ -1,11 +1,14 @@
 import {
   estTokens,
+  type AnyNoticeImpl,
   isStaleLease,
   makeCap,
   type AnySurfaceImpl,
   type Conversation,
   type Emit,
   type ModelAdapter,
+  type Notify,
+  type Progress,
   type StoreAdapter,
   type Tool,
   type ToolCtx,
@@ -47,6 +50,12 @@ export interface HaiConfig {
    * model gets "already ran" back instead of running it again.
    */
   init?: Tool;
+  /**
+   * The notices this app sends with `hai.notify`. A notice not listed here is
+   * refused, as an unregistered surface is. With any listed, the browser opens
+   * the events stream (`GET {base}/events`) to receive them.
+   */
+  notices?: AnyNoticeImpl[];
 }
 
 /**
@@ -96,6 +105,7 @@ export class Hai {
   readonly config: HaiConfig;
   private readonly surfaces = new Map<string, AnySurfaceImpl>();
   private readonly tools = new Map<string, Tool>();
+  private readonly notices = new Map<string, AnyNoticeImpl>();
   /** What the model gets as its system prompt: the app's, then the scope. */
   readonly system: string;
   private seq = 0;
@@ -109,6 +119,10 @@ export class Hai {
       this.surfaces.set(s.surface.name, s);
     }
     for (const t of config.tools) this.tools.set(t.name, t);
+    for (const n of config.notices ?? []) {
+      if (this.notices.has(n.notice.name)) throw new Error(`two notices are named "${n.notice.name}"`);
+      this.notices.set(n.notice.name, n);
+    }
     // query_ui is DERIVED, never authored. It cannot drift from the surfaces
     // that actually exist, and it always exists.
     const queryUi = this.buildQueryUiTool();
@@ -122,6 +136,68 @@ export class Hai {
     }
   }
 
+  /** Whether this app sends notices, so the browser should open the events stream. */
+  get sendsNotices(): boolean {
+    return this.notices.size > 0;
+  }
+
+  /**
+   * Send a notice to a conversation: its payload to the browser now, over the
+   * events stream, and its model text to the model in the next user message
+   * the conversation records.
+   *
+   * Takes no lease, so it works while a turn is streaming, while one is
+   * parked, and with nobody connected. It never starts a turn.
+   */
+  readonly notify: Notify = async (conversationId, notice, payload, options = {}) => {
+    const name = notice?.notice?.name;
+    if (this.notices.get(name) !== notice) {
+      throw new Error(`notice "${name}" is not registered: list it in createHai({ notices })`);
+    }
+    // Validated before it is stored: notify is called from webhooks and job
+    // queues, whose data comes from outside this process.
+    const parsed = notice.notice.payload.parse(payload);
+    const model: unknown = notice.impl.model(parsed);
+    if (model !== null && typeof model !== "string") {
+      throw new TypeError(`notice "${name}": model() must return a string or null`);
+    }
+    // Checked against the stored surfaces, which needs no lease. One left behind
+    // by an overtaken turn may pass as well, until it is swept, unlike a click
+    // on it: a click changes the history, and the handle here only says where
+    // the browser shows the notice. The model never sees it.
+    const { handle } = options;
+    if (handle !== undefined && !(await this.config.store.getPayload(handle, conversationId))) {
+      throw new Error(`notice "${name}": no surface ${handle} in conversation ${conversationId}`);
+    }
+    const record = await this.config.store.putNotice({
+      conversationId,
+      name,
+      version: notice.notice.version,
+      payload: parsed,
+      model,
+      ...(handle === undefined ? {} : { handle }),
+    });
+    return { seq: record.seq };
+  };
+
+  /**
+   * The notices this conversation's history hasn't taken in yet: their model
+   * text as blocks for the user message this request is about to record, and
+   * the number to set `noticedThrough` to when it does. Set it only where the
+   * message is pushed, so a request refused before then takes nothing in.
+   */
+  private async unreadNotices(conversation: Conversation): Promise<{ blocks: TextBlock[]; through: number }> {
+    const through = conversation.noticedThrough ?? 0;
+    if (!this.notices.size) return { blocks: [], through };
+    const fresh = (await this.config.store.getNotices(conversation.id, through)) ?? [];
+    return {
+      blocks: fresh.flatMap((n) =>
+        n.model === null ? [] : [{ type: "text" as const, text: `[App notification: ${n.name}] ${n.model}` }],
+      ),
+      through: fresh.at(-1)?.seq ?? through,
+    };
+  }
+
   private nid(prefix: string) {
     return `${prefix}_${++this.seq}`;
   }
@@ -215,6 +291,10 @@ export class Hai {
 
     // The first message is the one that starts the conversation.
     const starting = conversation.messages.length === 0;
+    // Notices ride in the user's message, ahead of what they typed: they
+    // arrived before it.
+    const unread = await this.unreadNotices(conversation);
+    const message = withText(unread.blocks, text);
 
     // The user typed while a tool was parked. Every tool_use in a turn must
     // receive a tool_result, so close the pending one out honestly first.
@@ -240,9 +320,10 @@ export class Hai {
 
     emit({ type: "block_start", block: { kind: "user", id: this.nid("b"), text } });
     if (starting && this.config.init) {
-      if (await this.runInit(conversation, text, emit)) return; // parked on its surface
+      if (await this.runInit(conversation, message, emit, unread.through)) return; // parked on its surface
     } else {
-      conversation.messages.push({ role: "user", content: text });
+      conversation.messages.push({ role: "user", content: message });
+      conversation.noticedThrough = unread.through;
     }
     await this.runTurn(conversation, emit);
   }
@@ -255,22 +336,29 @@ export class Hai {
    */
   async start(conversation: Conversation, emit: Emit): Promise<void> {
     if (!this.config.init || conversation.messages.length > 0) return;
-    if (await this.runInit(conversation, STARTED, emit)) return; // parked on its surface
+    const unread = await this.unreadNotices(conversation);
+    if (await this.runInit(conversation, withText(unread.blocks, STARTED), emit, unread.through)) return; // parked on its surface
     conversation.status = "idle";
     emit({ type: "status", status: "idle" });
     await this.emitContext(conversation, emit);
   }
 
   /**
-   * Run the init tool as the conversation's first tool call, after `text` —
-   * the user's first message, or STARTED when it runs before one. Returns
-   * true when it parked the conversation on an elicit surface.
+   * Run the init tool as the conversation's first tool call, after `message` —
+   * the user's first message, or STARTED when it runs before one, with any
+   * unread notices, which take the conversation's notices through `through`.
+   * Returns true when it parked the conversation on an elicit surface.
    *
    * Nothing reaches the history until the tool has succeeded — not even the
    * user's message — so a refused start leaves the conversation exactly as
    * the route found it, and the next message starts it again.
    */
-  private async runInit(conversation: Conversation, text: string, emit: Emit): Promise<boolean> {
+  private async runInit(
+    conversation: Conversation,
+    message: string | TextBlock[],
+    emit: Emit,
+    through: number,
+  ): Promise<boolean> {
     const init = this.config.init!;
     const call = { type: "tool_use", id: `toolu_init_${newId()}`, name: init.name, input: {} };
     const toolBlockId = this.nid("b");
@@ -306,7 +394,8 @@ export class Hai {
     const ms = Date.now() - started;
     for (const e of held) emit(e);
 
-    conversation.messages.push({ role: "user", content: text });
+    conversation.messages.push({ role: "user", content: message });
+    conversation.noticedThrough = through;
     conversation.messages.push({ role: "assistant", content: [call] });
 
     if (asked) {
@@ -388,11 +477,15 @@ export class Hai {
       throw new Error(`action failed: ${(err as Error).message}`);
     }
 
+    // Read after the handler, so a notice its own work sent rides with the click.
+    const unread = await this.unreadNotices(conversation);
+
     // what recording the click changes, so a failed save below can undo it
     const before = {
       messages: conversation.messages.length,
       frozen: conversation.frozen.length,
       status: conversation.status,
+      noticedThrough: conversation.noticedThrough,
     };
     if (pending) {
       // resolve: the gate above let it through only for the waiting surface
@@ -408,14 +501,17 @@ export class Hai {
             // so nothing about the search has reached the model yet.
             content: `${pending.digest}\n${label}`,
           },
+          // after the tool results, which the API requires to come first
+          ...unread.blocks,
         ],
       });
       conversation.pending = null;
       conversation.status = "idle"; // answered; the save below records that
     } else {
       // inform: enriches the conversation without having blocked it
-      conversation.messages.push({ role: "user", content: `[UI interaction] ${label}` });
+      conversation.messages.push({ role: "user", content: withText(unread.blocks, `[UI interaction] ${label}`) });
     }
+    conversation.noticedThrough = unread.through;
 
     // Commit the click before the model runs. The handler may have written,
     // and a model turn can outlast the lease; saved now, the click stays on
@@ -436,6 +532,7 @@ export class Hai {
       conversation.frozen.length = before.frozen;
       conversation.pending = pending;
       conversation.status = before.status;
+      conversation.noticedThrough = before.noticedThrough;
       throw err;
     }
 
@@ -706,9 +803,35 @@ export class Hai {
     // set once the tool has returned or thrown: a render after that shows nothing
     let done = false;
 
+    // Progress is throttled, not queued: a tool that reports every row would
+    // otherwise flood the stream with frames nobody can read. The first goes
+    // out at once, later ones at most every PROGRESS_MS, carrying every field
+    // named since the last, and whatever is still waiting when the tool
+    // returns goes out then.
+    let unsent: Progress | null = null;
+    let lastSent = 0;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const flushProgress = () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (!unsent) return;
+      emit({ type: "progress", toolId: toolBlockId, ...unsent });
+      unsent = null;
+      lastSent = Date.now();
+    };
+
     const ctx: ToolCtx = {
       conversationId: conversation.id,
       text: (model) => ({ model }),
+      progress: (progress) => {
+        if (done) return;
+        const fields = progressFields(progress);
+        if (!fields) return;
+        unsent = { ...unsent, ...fields };
+        const wait = lastSent + PROGRESS_MS - Date.now();
+        if (wait <= 0) flushProgress();
+        else timer ??= setTimeout(flushProgress, wait);
+      },
       render: ((impl: AnySurfaceImpl, props: unknown, options?: { mode?: "display" | "elicit" }) => {
         if (done) return Promise.resolve({ model: "Not shown: the tool had already finished." });
         const shown = render(impl, props, options);
@@ -742,6 +865,8 @@ export class Hai {
     // in while the others finish. They finish before anything is decided or
     // undone, so none can open a question, or record a handle, afterwards.
     done = true;
+    // the last frame goes out before the row says the call has finished
+    flushProgress();
     await Promise.all(rendering);
     // A tool error is information for the model; a lost lease is not. Fencing
     // exists so a superseded turn stops — converting StaleLease into "tool
@@ -830,6 +955,41 @@ function strictest(recorded: unknown, current: unknown): number | "never" | unde
 
 const newId = () => globalThis.crypto.randomUUID().replaceAll("-", "").slice(0, 16);
 
+interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+/**
+ * A user message: `text` after any notice blocks, or `text` alone when there
+ * are none — so a conversation with no notices keeps exactly the history it
+ * always had.
+ */
+const withText = (blocks: TextBlock[], text: string): string | TextBlock[] =>
+  blocks.length ? [...blocks, { type: "text", text }] : text;
+
+/** The least time between two progress frames from one tool call. */
+const PROGRESS_MS = 100;
+
+/**
+ * The fields of a `ctx.progress` call worth sending, or null if none are.
+ * Checked at runtime because JavaScript callers never see the type, and a
+ * progress report is not worth failing a tool over: a field that isn't what
+ * its type says is dropped, not thrown on. `done` must be a finite number,
+ * zero or more, and `total` a finite number more than zero: there is no bar
+ * to draw for a workload of nothing.
+ */
+function progressFields(progress: unknown): Progress | null {
+  if (!progress || typeof progress !== "object") return null;
+  const { message, done, total } = progress as Record<string, unknown>;
+  const finite = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n);
+  const fields: Progress = {};
+  if (typeof message === "string") fields.message = message;
+  if (finite(done) && done >= 0) fields.done = done;
+  if (finite(total) && total > 0) fields.total = total;
+  return Object.keys(fields).length ? fields : null;
+}
+
 /** "2 hours", "15 minutes" — for a sentence a person reads. */
 function duration(ms: number): string {
   const units: [number, string][] = [

package/src/store.ts

@@ -2,6 +2,7 @@ import {
   ConversationBusy,
   StaleLease,
   type Conversation,
+  type NoticeRecord,
   type PayloadRecord,
   type StoreAdapter,
 } from "@haikit/core";
@@ -49,6 +50,11 @@ export function memoryStore(options: MemoryStoreOptions = {}): StoreAdapter {
   }
   const conversations = new Map<string, Conversation>();
   const payloads = new Map<string, PayloadRecord>();
+  // conversation id → its notices in seq order, and who is waiting to hear of
+  // the next one. Numbered per conversation: nothing awaits between taking a
+  // number and appending, so commit order is seq order for free.
+  const notices = new Map<string, NoticeRecord[]>();
+  const waiting = new Map<string, Set<() => void>>();
   let convSeq = 0;
   let handleSeq = 0;
 
@@ -95,6 +101,7 @@ export function memoryStore(options: MemoryStoreOptions = {}): StoreAdapter {
         pending: null,
         leaseUntil: Date.now() + leaseMs,
         leaseToken: newToken(),
+        noticedThrough: 0,
       };
       conversations.set(conversation.id, conversation);
       return copy(conversation);
@@ -129,5 +136,63 @@ export function memoryStore(options: MemoryStoreOptions = {}): StoreAdapter {
       }
       return out;
     },
+
+    /** Unfenced, as the contract says: a notice lands whoever holds the turn. */
+    async putNotice(record) {
+      if (!conversations.has(record.conversationId)) {
+        throw new Error(`conversation ${record.conversationId} does not exist`);
+      }
+      const list = notices.get(record.conversationId) ?? [];
+      const stored: NoticeRecord = copy({ ...record, seq: (list.at(-1)?.seq ?? 0) + 1, createdAt: Date.now() });
+      list.push(stored);
+      notices.set(record.conversationId, list);
+      for (const wake of waiting.get(record.conversationId) ?? []) wake();
+      return copy(stored);
+    },
+
+    async getNotices(conversationId, after, limit = Infinity) {
+      if (!conversations.has(conversationId)) return null;
+      const list = notices.get(conversationId) ?? [];
+      // Seq order, so the first one past `after` is found by halving, and only
+      // the page asked for is copied: reading a long backlog a page at a time
+      // never walks or copies the rest of it.
+      let lo = 0;
+      let hi = list.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (list[mid].seq > after) hi = mid;
+        else lo = mid + 1;
+      }
+      return copy(list.slice(lo, lo + limit));
+    },
+
+    async *watch(conversationId, signal) {
+      // One wake-up stands for any number of notices: a step resolves once
+      // something has landed since the last, and the caller reads them all.
+      let landed = false;
+      let wake: (() => void) | null = null;
+      const listener = () => {
+        landed = true;
+        wake?.();
+      };
+      const onAbort = () => wake?.();
+      const set = waiting.get(conversationId) ?? new Set();
+      set.add(listener);
+      waiting.set(conversationId, set);
+      signal.addEventListener("abort", onAbort);
+      try {
+        while (!signal.aborted) {
+          if (!landed) await new Promise<void>((r) => (wake = r));
+          wake = null;
+          if (signal.aborted) return;
+          landed = false;
+          yield;
+        }
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+        set.delete(listener);
+        if (!set.size) waiting.delete(conversationId);
+      }
+    },
   };
 }