@haikit/server 0.17.0 → 0.19.0

package/dist/runtime.js

@@ -1,4 +1,5 @@
 import { estTokens, isConversationBusy, isStaleLease, makeCap, } from "@haikit/core";
+import { Broadcast } from "./signals.js";
 /**
  * Opens the history when init runs before the user has said anything: the
  * Messages API requires the first message to be the user's. Bracketed like
@@ -24,6 +25,15 @@ const WOKEN = "[The user has not said anything. The notifications above arrived
 /** Appended to the init tool's description in what the model sees. */
 const INIT_NOTE = "This ran automatically at the start of the conversation, and its result is already above. " +
     "Calling it again does not run it.";
+/** The longest delay a Node timer keeps; past it, one fires after about a millisecond. */
+const MAX_TIMER_MS = 2_147_483_647;
+/** How long `hai.update` waits for a turn to let the conversation go, by default. */
+const UPDATE_TIMEOUT_MS = 30_000;
+/** How many conversations `hai.update` remembers its surfaces' handles for. */
+const UPDATE_NAMES_KEPT = 10_000;
+/** The first wait before `hai.update` tries a busy conversation again, and the longest. */
+const UPDATE_RETRY_MS = 100;
+const UPDATE_RETRY_MAX_MS = 2_000;
 export class Hai {
     config;
     surfaces = new Map();
@@ -34,6 +44,18 @@ export class Hai {
     queryUi;
     /** Handles each conversation has a revision of in flight, so two calls can't revise one at once. */
     revising = new WeakMap();
+    signals = new Map();
+    /** Signals sent, streams open, and presence, here and on the other servers. */
+    broadcast;
+    /** `hai.update` calls by conversation and surface: one writing, and the newest waiting behind it. */
+    updating = new Map();
+    /**
+     * The surfaces `hai.update` has revised, by conversation: each one's first
+     * handle and its latest, both mapped to the first, so calls naming either
+     * share a queue. Kept for the most recent conversations only; one let go of
+     * costs coalescing, never correctness, since every write revises the latest.
+     */
+    surfaceNames = new Map();
     /** What the model gets as its system prompt: the app's, then the scope. */
     system;
     seq = 0;
@@ -60,6 +82,25 @@ export class Hai {
             throw new RangeError(`maxWakes must be a whole count of at least 1 per a positive, finite number of milliseconds (got ${count} per ${perMs})`);
         }
         this.maxWakes = { count, perMs };
+        for (const s of config.signals ?? []) {
+            if (this.signals.has(s.name))
+                throw new Error(`two signals are named "${s.name}"`);
+            this.signals.set(s.name, s);
+        }
+        const { graceMs = 5_000, heartbeatMs = 10_000 } = config.presence ?? {};
+        for (const [name, ms] of [["graceMs", graceMs], ["heartbeatMs", heartbeatMs]]) {
+            // Past the longest timer Node keeps, it fires after about a millisecond:
+            // a grace would end at once, and a heartbeat would spin.
+            // Whole milliseconds, as timers count them: a fractional one would be
+            // scheduled shorter than the staleness arithmetic assumes.
+            if (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_MS) {
+                throw new RangeError(`presence.${name} must be a whole number of milliseconds, from 1 to ${MAX_TIMER_MS} (got ${String(ms)})`);
+            }
+        }
+        this.broadcast = new Broadcast(config.store, graceMs, heartbeatMs);
+        // hear the other servers' signals from now, so a stream that opens later gets their latest
+        if (this.signals.size)
+            this.broadcast.start();
         // query_ui is DERIVED, never authored. It cannot drift from the surfaces
         // that actually exist, and it always exists.
         const queryUi = this.buildQueryUiTool();
@@ -72,13 +113,27 @@ export class Hai {
             this.tools.set(config.init.name, config.init);
         }
     }
-    /** Whether this app sends notices, so the browser should open the events stream. */
+    /**
+     * Whether this app sends notices, `hai.update`'s included: what the
+     * conversation's history may have unread, and the events stream may have to
+     * deliver.
+     */
     get sendsNotices() {
-        return this.notices.size > 0;
+        return this.notices.size > 0 || this.config.updates === true;
     }
-    /** Whether any of its notices are `wake` notices, which the events route starts turns for. */
+    /**
+     * Whether the browser should open the events stream: for notices, or for
+     * signals, which travel on it too.
+     */
+    get streamsEvents() {
+        return this.sendsNotices || this.signals.size > 0;
+    }
+    /**
+     * Whether any of its notices may be `wake` notices, which the events route
+     * starts turns for: a registered one, or an update sent with `wake`.
+     */
     get wakes() {
-        return [...this.notices.values()].some((n) => n.notice.kind === "wake");
+        return this.config.updates === true || [...this.notices.values()].some((n) => n.notice.kind === "wake");
     }
     /**
      * Send a notice to a conversation: its payload to the browser now, over the
@@ -123,6 +178,278 @@ export class Hai {
         });
         return { seq: record.seq };
     };
+    /**
+     * Send a signal to every open events stream, on this server and, through a
+     * store with `publish` and `subscribe`, on the others. Not stored, not
+     * numbered, never in the model's context or the transcript: the browser
+     * hands it to the app's handler for it. Each signal's latest payload is
+     * kept, and a stream that opens later is sent it first.
+     *
+     * Throws for a signal not listed in `signals`, or a payload that fails its
+     * schema.
+     */
+    signal = (signal, payload) => {
+        const name = signal?.name;
+        if (this.signals.get(name) !== signal) {
+            throw new Error(`signal "${name}" is not registered: list it in createHai({ signals })`);
+        }
+        this.broadcast.send({ type: "signal", name, version: signal.version, payload: signal.payload.parse(payload) });
+    };
+    /**
+     * How many conversations have an events stream open, on every server
+     * sharing the store: a tab with the app open, as near as the server can
+     * tell. `listener` hears the count now and whenever it changes. A stream
+     * that closes still counts for `presence.graceMs`, so a reconnect doesn't
+     * flicker it. Returns a function that stops listening.
+     *
+     * Each server counts its own and the totals are summed, so a conversation
+     * counts once per server it has a stream on: one that reconnects to another
+     * server counts on both until the grace runs out, and one with streams on
+     * two servers at once counts twice. (The client opens one stream per
+     * conversation, so the second doesn't happen with it.)
+     *
+     * Only the number leaves a server: no conversation ids, and nothing the
+     * model sees. An app with no notices, updates or signals opens no events
+     * stream, so counts nothing.
+     */
+    onPresence(listener) {
+        return this.broadcast.onPresence(listener);
+    }
+    /**
+     * An events stream opened for `conversationId`: it hears every signal from
+     * now on, starting with each one's latest payload, and counts toward
+     * presence. The events route calls this; call it too if you serve the
+     * stream yourself, and call what it returns when the stream closes.
+     */
+    streamOpened(conversationId, emit) {
+        return this.broadcast.opened(conversationId, emit);
+    }
+    /**
+     * Revise a surface from outside any turn: a webhook, a job, a price feed.
+     * The revision is stored and attached as `ctx.update` does, under the
+     * conversation's lease, so a click can never act on props the server doesn't
+     * hold. Then an *update notice* tells both sides: the events stream sends
+     * the browser the revision, which it swaps into the component on screen,
+     * and the model hears which handle replaced which, with the new digest, in
+     * the next user message (or at once, with `wake`).
+     *
+     * `handle` may be any handle the surface has had: the revision replaces the
+     * latest. It throws if that one was answered, if the conversation is out of
+     * date, and, after waiting `timeoutMs` for a turn to let the conversation
+     * go, with `ConversationBusy`. A question waiting on the surface waits on
+     * the revision.
+     *
+     * One write per surface is in flight at a time. A call made meanwhile
+     * replaces any still waiting behind it, and every call it replaced resolves
+     * to the handle it writes; a wake any of them asked for still wakes.
+     */
+    update = (conversationId, surface, handle, props, options = {}) => {
+        const impl = surface;
+        const name = impl?.surface?.name;
+        if (this.surfaces.get(name) !== impl) {
+            return Promise.reject(new Error(`surface "${name}" is not registered: list it in createHai({ surfaces })`));
+        }
+        // Required even when notices open the events stream: it is also what has
+        // the events route start the turn an update sent with `wake` asks for.
+        if (this.config.updates !== true) {
+            return Promise.reject(new Error("hai.update is off: set createHai({ updates: true })"));
+        }
+        const { timeoutMs = UPDATE_TIMEOUT_MS, model, wake } = options;
+        if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            return Promise.reject(new RangeError(`timeoutMs must be a finite number of milliseconds, zero or more (got ${String(timeoutMs)})`));
+        }
+        if (model !== undefined && typeof model !== "string")
+            return Promise.reject(new TypeError("model must be a string"));
+        let parsed;
+        try {
+            // Validated before anything waits: props may come from outside this process.
+            parsed = impl.surface.props.parse(props);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        return new Promise((resolve, reject) => {
+            // the surface's first handle, when it is one `hai.update` has revised here
+            const first = this.surfaceNames.get(conversationId)?.get(handle) ?? handle;
+            const key = `${conversationId}\u0000${first}`;
+            const waiter = { resolve, reject };
+            const queue = this.updating.get(key);
+            if (queue) {
+                const behind = queue.next;
+                queue.next = {
+                    props: parsed,
+                    model,
+                    wake: wake === true || behind?.wake === true,
+                    timeoutMs,
+                    waiters: [...(behind?.waiters ?? []), waiter],
+                };
+                return;
+            }
+            const fresh = { next: { props: parsed, model, wake: wake === true, timeoutMs, waiters: [waiter] } };
+            this.updating.set(key, fresh);
+            void (async () => {
+                for (let job = fresh.next; job; job = fresh.next) {
+                    fresh.next = null;
+                    try {
+                        const { replaced, ...written } = await this.revise(conversationId, impl, handle, job);
+                        this.name(conversationId, first, replaced, written.handle);
+                        for (const w of job.waiters)
+                            w.resolve(written);
+                    }
+                    catch (err) {
+                        for (const w of job.waiters)
+                            w.reject(err);
+                    }
+                }
+                this.updating.delete(key);
+            })();
+        });
+    };
+    /** Record that `first`'s surface went from `replaced` to `latest`, for the next call's queue. */
+    name(conversationId, first, replaced, latest) {
+        const names = this.surfaceNames.get(conversationId) ?? new Map();
+        // only the first and the latest are kept: what a caller is likely to hold
+        if (replaced !== first)
+            names.delete(replaced);
+        names.set(first, first).set(latest, first);
+        // most recently revised last, so the oldest conversation goes first
+        this.surfaceNames.delete(conversationId);
+        this.surfaceNames.set(conversationId, names);
+        if (this.surfaceNames.size > UPDATE_NAMES_KEPT)
+            this.surfaceNames.delete(this.surfaceNames.keys().next().value);
+    }
+    /**
+     * Append the update notice this conversation owes, if any, before anything
+     * else is done with it: a revision whose own attempt to append it failed.
+     * One a holder appended before its save failed is not appended again.
+     */
+    async announce(conversation) {
+        const owed = conversation.announcing;
+        if (!owed)
+            return;
+        // The model hasn't taken it in either way: that commits with clearing this.
+        const unread = (await this.config.store.getNotices(conversation.id, conversation.noticedThrough ?? 0)) ?? [];
+        if (!unread.some((n) => n.handle === owed.handle && n.replaces === owed.replaces))
+            await this.config.store.putNotice(owed);
+        conversation.announcing = null;
+    }
+    /** One `hai.update` write: take the lease, revise, let the conversation go. */
+    async revise(conversationId, impl, handle, job) {
+        const { store } = this.config;
+        // Loading an unknown id would start a new conversation, so make sure it
+        // exists first, with the cheapest read there is.
+        if ((await store.getNotices(conversationId, Number.MAX_SAFE_INTEGER, 1)) === null) {
+            throw new Error(`no conversation ${conversationId}`);
+        }
+        // A turn in progress lands first: wait for it, backing off, up to the timeout.
+        const deadline = Date.now() + job.timeoutMs;
+        let conversation = null;
+        for (let wait = UPDATE_RETRY_MS; !conversation; wait = Math.min(wait * 2, UPDATE_RETRY_MAX_MS)) {
+            try {
+                conversation = await store.loadConversation(conversationId);
+            }
+            catch (err) {
+                const left = deadline - Date.now();
+                if (!isConversationBusy(err) || left <= 0)
+                    throw err;
+                await new Promise((r) => setTimeout(r, Math.min(wait, left)));
+                // not another try once the timeout has passed, even if the turn has gone
+                if (Date.now() >= deadline)
+                    throw err;
+            }
+        }
+        let failure = null;
+        let written = null;
+        try {
+            // one an earlier update still owes goes first, in order
+            await this.announce(conversation);
+            written = await this.reviseHeld(conversation, impl, handle, job);
+        }
+        catch (err) {
+            failure = err;
+        }
+        // As a route does at the end of a request: let the conversation go, with
+        // the token kept so the save can prove this is still the rightful holder.
+        conversation.leaseUntil = null;
+        if (!isStaleLease(failure)) {
+            try {
+                await store.saveConversation(conversation);
+            }
+            catch (err) {
+                failure ??= err;
+            }
+        }
+        if (failure)
+            throw failure;
+        return written;
+    }
+    async reviseHeld(conversation, impl, handle, job) {
+        const { store } = this.config;
+        if (!conversation.handles.includes(handle))
+            throw new Error(`no surface ${handle} in conversation ${conversation.id}`);
+        // the surface as it is now: updates queued one behind another each revise the last
+        const current = currentHandle(conversation, handle);
+        if (conversation.frozen.includes(current))
+            throw new Error(`${current} was answered, so it can't be revised`);
+        const record = await store.getPayload(current, conversation.id);
+        if (!record)
+            throw new Error(`no surface ${current} in conversation ${conversation.id}`);
+        if (record.component !== impl.surface.name)
+            throw new Error(`${current} is a ${record.component}, not a ${impl.surface.name}`);
+        // After the reads, right before the write, as for `ctx.update`: a revision
+        // must not bring an out-of-date conversation back by superseding the
+        // surface that closed it.
+        if (await this.refuseIfExpired(conversation, () => { })) {
+            throw new Error("this conversation is out of date; nothing more can be revised in it");
+        }
+        const next = await store.putPayload({
+            conversationId: conversation.id,
+            component: impl.surface.name,
+            version: impl.surface.version,
+            props: job.props,
+            mode: record.mode,
+            staleAfterMs: windowOf(impl),
+        }, conversation.leaseToken);
+        const digest = impl.impl.digest(job.props, { handle: next });
+        // …and once more as it takes effect: the write and the digest take a while too
+        const window = strictest(record.staleAfterMs, windowOf(impl));
+        if (window !== "never" && !(Number.isFinite(record.createdAt) && window !== undefined && record.createdAt + window > Date.now())) {
+            throw new Error("this conversation went out of date while the revision was made; it was not applied");
+        }
+        conversation.handles.push(next);
+        (conversation.superseded ??= {})[current] = next;
+        // A question waiting on the surface waits on its revision. Its digest stays
+        // as the model was shown it: the update's text rides in the same message as
+        // the answer, after it, saying what changed.
+        if (conversation.pending?.handle === current)
+            conversation.pending = { ...conversation.pending, handle: next };
+        // The notice it owes commits with it, in one fenced save, so the revision
+        // and its notice can't come apart. Saved before the notice is appended,
+        // which proves the lease is still held: a notice for a revision the history
+        // lost would show the browser a surface every click on is refused.
+        const notice = {
+            conversationId: conversation.id,
+            name: impl.surface.name,
+            version: impl.surface.version,
+            payload: null,
+            model: `${job.model ? `${job.model} ` : ""}${current} was replaced by ${next}; its earlier digest is out of date. Now: ${digest}`,
+            handle: next,
+            replaces: current,
+            ...(job.wake ? { kind: "wake" } : {}),
+        };
+        conversation.announcing = notice;
+        await store.saveConversation(conversation);
+        try {
+            await store.putNotice(notice);
+        }
+        catch (err) {
+            // Still owed, and appended by whoever holds the conversation next, before
+            // anything else: the model hears of the revision before it runs again.
+            throw new Error(`${next} is saved, but its update notice could not be stored yet: it goes out with the conversation's next request (${err.message})`);
+        }
+        conversation.announcing = null;
+        return { handle: next, replaced: current };
+    }
     /**
      * Start a turn for the `wake` notices this conversation hasn't taken in, if
      * it can take one now. The events route calls this, and streams the turn
@@ -188,6 +515,7 @@ export class Hai {
         return outcome;
     }
     async wakeTurn(conversation, emit) {
+        await this.announce(conversation);
         // a load of an unknown id starts a new conversation, which has not begun either
         if (!conversation.messages.length || conversation.status === "awaiting")
             return "idle";
@@ -280,11 +608,13 @@ export class Hai {
      */
     async unreadNotices(conversation) {
         const through = conversation.noticedThrough ?? 0;
-        if (!this.notices.size)
+        if (!this.sendsNotices)
             return { blocks: [], through, wake: 0 };
         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}` }]),
+            blocks: fresh.flatMap((n) => n.model === null
+                ? []
+                : [{ type: "text", text: n.replaces === undefined ? `[App notification: ${n.name}] ${n.model}` : `[UI update] ${n.model}` }]),
             through: fresh.at(-1)?.seq ?? through,
             // the newest unread wake notice, or 0
             wake: fresh.findLast((n) => n.kind === "wake")?.seq ?? 0,
@@ -364,6 +694,7 @@ export class Hai {
     }
     // ─────────────────────────────────────────────────── public API
     async send(conversation, text, emit) {
+        await this.announce(conversation);
         if (await this.refuseIfExpired(conversation, emit))
             return;
         // The first message is the one that starts the conversation.
@@ -413,6 +744,7 @@ export class Hai {
     async start(conversation, emit) {
         if (!this.config.init || conversation.messages.length > 0)
             return;
+        await this.announce(conversation);
         const unread = await this.unreadNotices(conversation);
         if (await this.runInit(conversation, withText(unread.blocks, STARTED), emit, unread.through))
             return; // parked on its surface
@@ -497,6 +829,7 @@ export class Hai {
         return false;
     }
     async interact(conversation, input, emit) {
+        await this.announce(conversation);
         if (await this.refuseIfExpired(conversation, emit))
             return;
         // The payload row carries a conversation id, but that alone is not enough.
@@ -634,8 +967,9 @@ export class Hai {
     async refuseIfExpired(conversation, emit) {
         if (!conversation.handles.length)
             return false;
-        const now = Date.now();
         const records = await this.config.store.getPayloads(conversation.handles, conversation.id);
+        // after the read, so a window that ran out while it was in flight counts
+        const now = Date.now();
         // the surface that went out of date first is the one that closed it
         let first = null;
         // getPayloads omits handles it cannot find, and the loop below only sees
@@ -734,8 +1068,18 @@ export class Hai {
                 // Hold the resolved siblings too — the API is all-or-nothing per batch.
                 conversation.status = "awaiting";
                 // At the question's latest revision: a later call in this reply may
-                // have revised it.
-                conversation.pending = { ...parked, handle: currentHandle(conversation, parked.handle), results };
+                // have revised it, and then its answer goes out under the revision's
+                // digest, not the original's.
+                // Only the question's part is replaced: anything the asking call said
+                // after it rides along as before.
+                const handle = currentHandle(conversation, parked.handle);
+                const asking = hop.asking;
+                let digest = parked.digest;
+                if (handle !== parked.handle && asking?.handle === handle && asking.digest !== undefined) {
+                    const asked = asking.question;
+                    digest = asked !== undefined && parked.digest.startsWith(asked) ? asking.digest + parked.digest.slice(asked.length) : asking.digest;
+                }
+                conversation.pending = { ...parked, handle, digest, results };
                 emit({ type: "status", status: "awaiting" });
                 await this.emitContext(conversation, emit);
                 return;
@@ -770,7 +1114,10 @@ export class Hai {
         // back to the tool for the model.
         const show = async (impl, props, surfaceMode, 
         // the handle this revises in place, for `update`
-        replaces) => {
+        replaces, 
+        // last word before the surface is attached and sent: throwing leaves the
+        // stored payload unreferenced, inert as an overtaken turn's
+        beforeAttach) => {
             // Validate before storing: props may originate outside this process.
             const parsed = impl.surface.props.parse(props);
             const window = windowOf(impl);
@@ -790,6 +1137,7 @@ export class Hai {
             }, conversation.leaseToken);
             // The split, in two lines. Digest -> model. Payload -> browser.
             const digest = impl.impl.digest(parsed, { handle });
+            beforeAttach?.();
             // Recorded only once the digest is in hand. A surface that fails here is
             // never shown, and a handle in the history counts toward its freshness,
             // so it could otherwise close the conversation over something unseen.
@@ -843,6 +1191,7 @@ export class Hai {
             try {
                 const ret = await show(impl, props, "elicit");
                 claim.handle = ret.handle;
+                claim.question = ret.model;
                 asked = { handle: ret.handle, digest: ret.model };
                 return ret;
             }
@@ -878,13 +1227,35 @@ export class Hai {
                 if (record.component !== impl.surface.name) {
                     throw new Error(`${handle} is a ${record.component}, not a ${impl.surface.name}`);
                 }
-                const ret = await show(impl, props, record.mode, handle);
+                // Freshness again, last, right before the write: a long turn can
+                // outlast a window that was open when it began, and so can the reads
+                // above. A revision must not bring an out-of-date conversation back
+                // by superseding the surface that closed it.
+                if (await this.refuseIfExpired(conversation, () => { })) {
+                    throw new Error("this conversation is out of date; nothing more can be revised in it");
+                }
+                // …and once more as it takes effect: the write and the digest above can
+                // take a while too, and the browser closes the conversation at the old
+                // surface's deadline whether or not a revision is on its way.
+                const window = strictest(record.staleAfterMs, windowOf(impl));
+                const stillFresh = () => {
+                    if (window === "never")
+                        return;
+                    if (!(Number.isFinite(record.createdAt) && window !== undefined && record.createdAt + window > Date.now())) {
+                        throw new Error("this conversation went out of date while the revision was made; it was not applied");
+                    }
+                };
+                const ret = await show(impl, props, record.mode, handle, stillFresh);
                 (conversation.superseded ??= {})[handle] = ret.handle;
-                // a question waiting on the old surface waits on the new one
-                if (asked?.handle === handle)
+                // a question waiting on the old surface waits on the new one; when this
+                // call asked it, its result starts with the revision's digest now, so
+                // that is the part a later call's revision replaces
+                const mine = asked?.handle === handle;
+                if (mine)
                     asked = { handle: ret.handle, digest: ret.model };
-                if (hop.asking?.handle === handle)
-                    hop.asking.handle = ret.handle;
+                if (hop.asking?.handle === handle) {
+                    Object.assign(hop.asking, { handle: ret.handle, digest: ret.model }, mine ? { question: ret.model } : {});
+                }
                 return ret;
             }
             finally {