@haikit/server 0.16.0 → 0.18.0

package/dist/runtime.js

@@ -24,12 +24,32 @@ 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.";
+/** 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();
     tools = new Map();
     notices = new Map();
     maxWakes;
+    /** The derived `query_ui` tool, which answers about superseded surfaces with a note. */
+    queryUi;
+    /** Handles each conversation has a revision of in flight, so two calls can't revise one at once. */
+    revising = new WeakMap();
+    /** `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 +80,7 @@ export class Hai {
         // that actually exist, and it always exists.
         const queryUi = this.buildQueryUiTool();
         this.tools.set(queryUi.name, queryUi);
+        this.queryUi = queryUi;
         if (config.init) {
             if (this.tools.has(config.init.name)) {
                 throw new Error(`init tool "${config.init.name}" has the same name as another tool`);
@@ -67,13 +88,19 @@ 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, so the browser
+     * should open the events stream.
+     */
     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 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
@@ -118,6 +145,232 @@ export class Hai {
         });
         return { seq: record.seq };
     };
+    /**
+     * 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
@@ -183,6 +436,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";
@@ -275,11 +529,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,
@@ -359,6 +615,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.
@@ -408,6 +665,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
@@ -468,7 +726,12 @@ export class Hai {
         if (asked) {
             emit({ type: "block_update", id: toolBlockId, status: "awaiting", ms, result: asked.digest });
             conversation.status = "awaiting";
-            conversation.pending = { toolUseId: call.id, handle: asked.handle, digest: asked.digest, results: [] };
+            conversation.pending = {
+                toolUseId: call.id,
+                handle: currentHandle(conversation, asked.handle),
+                digest: asked.digest,
+                results: [],
+            };
             emit({ type: "status", status: "awaiting" });
             await this.emitContext(conversation, emit);
             return true;
@@ -487,6 +750,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.
@@ -496,6 +760,10 @@ export class Hai {
         // Membership of the surviving `handles` is what makes those orphans inert.
         if (!conversation.handles.includes(input.handle))
             throw new Error("unknown handle");
+        // Revised since the user saw it: what they clicked on is no longer there.
+        if (conversation.superseded?.[input.handle]) {
+            throw new Error(`superseded by ${currentHandle(conversation, input.handle)}`);
+        }
         if (conversation.frozen.includes(input.handle))
             throw new Error("component is frozen");
         const record = await this.config.store.getPayload(input.handle, conversation.id);
@@ -620,8 +888,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
@@ -631,6 +900,13 @@ export class Hai {
             first = { expiredAt: Number.NaN, age: Number.NaN, window: undefined };
         }
         for (const record of records) {
+            // A revised surface's window stops counting; its revision's counts. Safe
+            // because the model has heard the revision before it can act: in a turn
+            // as the tool's result, and from outside one in the message this
+            // request is about to record. (An answered surface can't be revised, so
+            // what the user picked from one still counts.)
+            if (conversation.superseded?.[record.handle])
+                continue;
             // a surface the code no longer registers has no current window at all,
             // which is not the same as one registered without a window ("never")
             const impl = this.surfaces.get(record.component);
@@ -712,7 +988,19 @@ export class Hai {
             if (parked) {
                 // Hold the resolved siblings too — the API is all-or-nothing per batch.
                 conversation.status = "awaiting";
-                conversation.pending = { ...parked, results };
+                // At the question's latest revision: a later call in this reply may
+                // 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;
@@ -745,7 +1033,12 @@ export class Hai {
         let asked = null;
         // Store a surface and send it out: the payload to the browser, the digest
         // back to the tool for the model.
-        const show = async (impl, props, surfaceMode) => {
+        const show = async (impl, props, surfaceMode, 
+        // the handle this revises in place, for `update`
+        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);
@@ -765,6 +1058,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.
@@ -781,6 +1075,7 @@ export class Hai {
                 ...(window === "never" ? {} : { staleAfterMs: window }),
                 // how long ago it was stored: the digest's time, and a replay's wait
                 ageMs: Date.now() - storing,
+                ...(replaces === undefined ? {} : { replaces }),
             });
             emit({ type: "ui_props", handle, props: parsed });
             return { model: digest, handle };
@@ -817,6 +1112,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;
             }
@@ -829,6 +1125,64 @@ export class Hai {
                 settle();
             }
         };
+        // Revise a surface this conversation shows: a new surface, with a new
+        // handle, that supersedes the old one. Checked before anything is stored,
+        // and claimed before the first await, so two calls can't both revise it.
+        const update = async (impl, handle, props) => {
+            if (!conversation.handles.includes(handle))
+                throw new Error(`no surface ${handle} in this conversation`);
+            if (conversation.frozen.includes(handle))
+                throw new Error(`${handle} was answered, so it can't be revised`);
+            const after = conversation.superseded?.[handle];
+            if (after)
+                throw new Error(`${handle} was revised already: it is ${currentHandle(conversation, handle)} now`);
+            const revising = this.revising.get(conversation) ?? new Set();
+            if (revising.has(handle))
+                throw new Error(`${handle} is being revised by another call`);
+            revising.add(handle);
+            this.revising.set(conversation, revising);
+            try {
+                const record = await this.config.store.getPayload(handle, conversation.id);
+                if (!record)
+                    throw new Error(`no surface ${handle} in this conversation`);
+                if (record.component !== impl.surface.name) {
+                    throw new Error(`${handle} is a ${record.component}, not a ${impl.surface.name}`);
+                }
+                // 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; 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) {
+                    Object.assign(hop.asking, { handle: ret.handle, digest: ret.model }, mine ? { question: ret.model } : {});
+                }
+                return ret;
+            }
+            finally {
+                revising.delete(handle);
+            }
+        };
         // Renders the tool has started. One can still be storing when the tool
         // returns or throws: a render it didn't await, or one a rejection in a
         // Promise.all overtook. They all finish before this call is decided. Each is
@@ -883,6 +1237,16 @@ export class Hai {
                 }));
                 return shown;
             }),
+            update: ((impl, handle, props) => {
+                if (done)
+                    return Promise.resolve({ model: "Not revised: the tool had already finished." });
+                const revised = update(impl, handle, props);
+                rendering.push(revised.then(() => { }, (err) => {
+                    if (isStaleLease(err))
+                        lost ??= err;
+                }));
+                return revised;
+            }),
         };
         let input;
         try {
@@ -914,7 +1278,13 @@ export class Hai {
         if (lost)
             throw lost;
         if (outcome.ok) {
-            const { ret } = outcome;
+            let { ret } = outcome;
+            // A query on a surface since revised answers from what it was, which is
+            // what the model asked about; it is told the surface has moved on.
+            const queried = input?.handle;
+            if (tool === this.queryUi && typeof queried === "string" && conversation.superseded?.[queried]) {
+                ret = { ...ret, model: `${ret.model}\n(${queried} has since been revised: it is ${currentHandle(conversation, queried)} now.)` };
+            }
             // The answer goes to the model under the digest of the question this call
             // showed. Anything else the tool returned rides along after it, such as a
             // render it was refused, so the model still hears it.
@@ -989,6 +1359,16 @@ function strictest(recorded, current) {
     return finite.length ? Math.min(...finite) : "never";
 }
 const newId = () => globalThis.crypto.randomUUID().replaceAll("-", "").slice(0, 16);
+/** The latest revision of a surface: `handle` itself, or what it was superseded by, all the way along. */
+function currentHandle(conversation, handle) {
+    const seen = new Set();
+    let at = handle;
+    while (conversation.superseded?.[at] && !seen.has(at)) {
+        seen.add(at);
+        at = conversation.superseded[at];
+    }
+    return at;
+}
 /**
  * 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