@haikit/server 0.12.0 → 0.13.0

package/README.md

@@ -113,6 +113,59 @@ tools it was given, and the browser can only send `{handle, action, value}`,
 so put every check with consequences, such as who may book what, inside the
 tool or action handler, where it runs as code.
 
+**The server can tell a conversation something later, with a notice.** A
+webhook confirming a booking, a job finishing: `hai.notify` sends the browser
+the notice's payload now, and the model its `model` text in the next user
+message the conversation records. Declare it once, beside your surfaces:
+
+```ts
+// shared/notices.ts — imported by both halves
+export const holdConfirmed = defineNotice({
+  name: "hold_confirmed",
+  version: 1,
+  payload: z.object({ flightId: z.string(), reference: z.string() }),
+});
+
+// server
+const holdConfirmedServer = holdConfirmed.implement({
+  // required, like a digest: what the model hears, or null for nothing
+  model: (p) => `The airline confirmed the hold on ${p.flightId}, reference ${p.reference}.`,
+});
+const hai = createHai({ model, store, tools, surfaces, system, notices: [holdConfirmedServer] });
+
+// anywhere, whenever: a webhook, a queue, an action handler's follow-up
+await hai.notify(conversationId, holdConfirmedServer, { flightId: "AC832", reference: "QX7P2L" }, { handle: "ui_01" });
+```
+
+The payload is typed from the contract, and checked against its schema before
+it is stored. A notice that isn't listed in `notices`, a payload that fails its
+schema, or a `handle` with no surface stored in the conversation is refused.
+Pass a handle from the conversation's saved history, such as an action
+handler's `ctx.handle`. The check is against the stored surfaces, not that
+history, so a surface left behind by an overtaken turn may also pass, until a
+sweep such as `@haikit/postgres`'s `sweepOrphans` removes it. That is no
+promise, just harmless: the handle only says where the browser shows the
+notice, the model never sees it, and a notice can't change anything.
+
+`notify` takes no lease, so it works while a turn is streaming, while one is
+parked on a question, and with nobody connected. It never touches the history
+itself: the next request that records a user message takes every unread notice
+in. A typed message carries them ahead of what the user typed, and an answer to
+a question carries them after its tool results. Taking them in commits with
+that request's history, so a turn whose save is lost leaves them unread for
+the next one. A notice never starts a turn.
+
+With any notices listed, `hello` tells the browser to open a fourth route,
+`GET /hai/events?conversationId=…`. It streams the conversation's notices,
+each with its sequence number as its SSE `id`, so a browser that reconnects
+with `Last-Event-ID` picks up where it left off. It takes no lease, writes
+nothing, and accepts nothing from the browser but which conversation and where
+to resume. The `model` text never goes out on it. The browser sees that only
+once a turn has taken it in, as part of the history the `context` event shows
+the inspector, the same as a digest. It reads the store every two
+seconds, and a store with `watch` wakes it the moment a notice lands. The
+two-second read stays even then, so a lost wake-up only delays a notice.
+
 **A conversation closes once any of its surfaces passes its `staleAfterMs`.**
 From then on both routes answer with an `expired` event and the model is not
 called, so a picker left open over a weekend cannot resolve against last week's

package/dist/routes.d.ts

@@ -1,13 +1,16 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 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 declare function nodeHandler(hai: Hai, basePath?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,SAAS,IACxB,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC,CA4E1F"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,SAAS,IACxB,KAAK,eAAe,EAAE,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAAC,CAuF1F"}

package/dist/routes.js

@@ -1,19 +1,28 @@
 import { isConversationBusy, isStaleLease } from "@haikit/core";
 /**
- * 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, basePath = "/hai") {
     return async function handle(req, res) {
         const url = new URL(req.url ?? "/", "http://localhost");
-        if (req.method !== "POST" || !url.pathname.startsWith(basePath))
+        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);
@@ -40,7 +49,12 @@ export function nodeHandler(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 } : {}),
+            });
         }
         let superseded = false;
         try {
@@ -87,6 +101,150 @@ export function nodeHandler(hai, basePath = "/hai") {
         return true;
     };
 }
+/**
+ * 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, req, res, 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) => {
+        if (res.write(chunk))
+            return;
+        await new Promise((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 = 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 = {
+                    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, signal) {
+    const steps = watch?.[Symbol.asyncIterator]();
+    // started now, so the watch is listening before the caller's next read
+    let step = steps?.next().then((r) => !r.done, () => false) ?? null;
+    try {
+        while (!signal.aborted) {
+            let timer;
+            let onAbort;
+            const tick = new Promise((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) {
     res.writeHead(200, {
         "content-type": "text/event-stream",

package/dist/routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import { type AnySurfaceImpl, type Conversation, type Emit, type ModelAdapter, type StoreAdapter, type Tool } from "@haikit/core";
+import { type AnyNoticeImpl, type AnySurfaceImpl, type Conversation, type Emit, type ModelAdapter, type Notify, type StoreAdapter, type Tool } from "@haikit/core";
 export interface HaiConfig {
     model: ModelAdapter;
     store: StoreAdapter;
@@ -33,6 +33,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[];
 }
 /**
  * Appended to every app's system prompt unless `scope` says otherwise. Generic
@@ -44,10 +50,29 @@ export declare class Hai {
     readonly config: HaiConfig;
     private readonly surfaces;
     private readonly tools;
+    private readonly notices;
     /** What the model gets as its system prompt: the app's, then the scope. */
     readonly system: string;
     private seq;
     constructor(config: HaiConfig);
+    /** Whether this app sends notices, so the browser should open the events stream. */
+    get sendsNotices(): boolean;
+    /**
+     * 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;
+    /**
+     * 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 unreadNotices;
     private nid;
     private buildQueryUiTool;
     send(conversation: Conversation, text: string, emit: Emit): Promise<void>;
@@ -59,9 +84,10 @@ export declare class Hai {
      */
     start(conversation: Conversation, emit: Emit): Promise<void>;
     /**
-     * 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

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,IAAI,EACT,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,IAAI,EAIV,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AASD;;;;GAIG;AACH,eAAO,MAAM,aAAa,ufAQ+B,CAAC;AAuB1D,qBAAa,GAAG;IACd,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,SAAS;IAsB7B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,gBAAgB;IAkFlB,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC/E;;;;;OAKG;IACG,KAAK,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlE;;;;;;;;OAQG;YACW,OAAO;IA+Df,QAAQ,CACZ,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EACzD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC;IA2GhB;;;;;;;;;;;;;;;;OAgBG;YACW,eAAe;YA4Cf,OAAO;YA0EP,UAAU;YA6NV,WAAW;CAa1B"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,MAAM,EAEX,KAAK,YAAY,EACjB,KAAK,IAAI,EAIV,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AASD;;;;GAIG;AACH,eAAO,MAAM,aAAa,ufAQ+B,CAAC;AAuB1D,qBAAa,GAAG;IACd,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,SAAS;IA0B7B,oFAAoF;IACpF,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CA6BrB;IAEF;;;;;OAKG;YACW,aAAa;IAY3B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,gBAAgB;IAkFlB,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0C/E;;;;;OAKG;IACG,KAAK,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IASlE;;;;;;;;;OASG;YACW,OAAO;IAqEf,QAAQ,CACZ,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EACzD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,IAAI,CAAC;IAmHhB;;;;;;;;;;;;;;;;OAgBG;YACW,eAAe;YA4Cf,OAAO;YA0EP,UAAU;YA6NV,WAAW;CAa1B"}

package/dist/runtime.js

@@ -26,6 +26,7 @@ export class Hai {
     config;
     surfaces = new Map();
     tools = new Map();
+    notices = new Map();
     /** What the model gets as its system prompt: the app's, then the scope. */
     system;
     seq = 0;
@@ -39,6 +40,11 @@ export class Hai {
         }
         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();
@@ -50,6 +56,64 @@ export class Hai {
             this.tools.set(config.init.name, config.init);
         }
     }
+    /** Whether this app sends notices, so the browser should open the events stream. */
+    get sendsNotices() {
+        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.
+     */
+    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 = 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.
+     */
+    async unreadNotices(conversation) {
+        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", text: `[App notification: ${n.name}] ${n.model}` }]),
+            through: fresh.at(-1)?.seq ?? through,
+        };
+    }
     nid(prefix) {
         return `${prefix}_${++this.seq}`;
     }
@@ -128,6 +192,10 @@ export class Hai {
             return;
         // 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.
         if (conversation.status === "awaiting" && conversation.pending) {
@@ -151,11 +219,12 @@ 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))
+            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);
     }
@@ -168,22 +237,24 @@ export class Hai {
     async start(conversation, emit) {
         if (!this.config.init || conversation.messages.length > 0)
             return;
-        if (await this.runInit(conversation, STARTED, emit))
+        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.
      */
-    async runInit(conversation, text, emit) {
+    async runInit(conversation, message, emit, through) {
         const init = this.config.init;
         const call = { type: "tool_use", id: `toolu_init_${newId()}`, name: init.name, input: {} };
         const toolBlockId = this.nid("b");
@@ -220,7 +291,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) {
             emit({ type: "block_update", id: toolBlockId, status: "awaiting", ms, result: asked.digest });
@@ -294,11 +366,14 @@ export class Hai {
         catch (err) {
             throw new Error(`action failed: ${err.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
@@ -314,6 +389,8 @@ 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;
@@ -321,8 +398,9 @@ export class Hai {
         }
         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
         // record however the turn ends, so it cannot be answered — and its handler
@@ -343,6 +421,7 @@ export class Hai {
             conversation.frozen.length = before.frozen;
             conversation.pending = pending;
             conversation.status = before.status;
+            conversation.noticedThrough = before.noticedThrough;
             throw err;
         }
         if (pending)
@@ -733,6 +812,12 @@ function strictest(recorded, current) {
     return finite.length ? Math.min(...finite) : "never";
 }
 const newId = () => globalThis.crypto.randomUUID().replaceAll("-", "").slice(0, 16);
+/**
+ * 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, text) => blocks.length ? [...blocks, { type: "text", text }] : text;
 /** The least time between two progress frames from one tool call. */
 const PROGRESS_MS = 100;
 /**