@haikit/server 0.16.0 → 0.18.0

package/src/runtime.ts

@@ -14,6 +14,8 @@ import {
   type Tool,
   type ToolCtx,
   type ToolReturn,
+  type Update,
+  type UpdateOptions,
   type WireEvent,
 } from "@haikit/core";
 
@@ -65,6 +67,13 @@ export interface HaiConfig {
    * browser still shows it at once.
    */
   maxWakes?: { count: number; perMs: number };
+  /**
+   * Set when app code revises surfaces with `hai.update`, which refuses
+   * without it. The browser then opens the events stream, which is how a
+   * revision reaches it, and the events route starts the turns an update sent
+   * with `wake` asks for.
+   */
+  updates?: boolean;
 }
 
 /**
@@ -111,9 +120,37 @@ interface Hop {
    * so two renders at once cannot both ask; the handle is known once it shows,
    * and `settled` resolves when its render has shown it or failed.
    */
-  asking: { handle: string | null; settled: Promise<void> } | null;
+  asking: {
+    handle: string | null;
+    settled: Promise<void>;
+    /** The digest it was asked under, and its latest, once a later call in the reply has revised it. */
+    question?: string;
+    digest?: string;
+  } | null;
+}
+
+/** A `hai.update` write, and every call it answers. */
+interface UpdateJob {
+  props: unknown;
+  model: string | undefined;
+  wake: boolean;
+  timeoutMs: number;
+  waiters: { resolve: (written: { handle: string }) => void; reject: (err: unknown) => void }[];
 }
 
+/** The `hai.update` calls for one surface: the next to write, once the one writing is done. */
+interface UpdateQueue {
+  next: UpdateJob | null;
+}
+
+/** 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;
+
 /** An elicit surface a tool call showed, and the digest its answer goes out under. */
 interface Question {
   handle: string;
@@ -126,6 +163,19 @@ export class Hai {
   private readonly tools = new Map<string, Tool>();
   private readonly notices = new Map<string, AnyNoticeImpl>();
   private readonly maxWakes: { count: number; perMs: number };
+  /** The derived `query_ui` tool, which answers about superseded surfaces with a note. */
+  private readonly queryUi: Tool;
+  /** Handles each conversation has a revision of in flight, so two calls can't revise one at once. */
+  private readonly revising = new WeakMap<Conversation, Set<string>>();
+  /** `hai.update` calls by conversation and surface: one writing, and the newest waiting behind it. */
+  private readonly updating = new Map<string, UpdateQueue>();
+  /**
+   * 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.
+   */
+  private readonly surfaceNames = new Map<string, Map<string, string>>();
   /** What the model gets as its system prompt: the app's, then the scope. */
   readonly system: string;
   private seq = 0;
@@ -157,6 +207,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)) {
@@ -166,14 +217,20 @@ export class Hai {
     }
   }
 
-  /** 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(): boolean {
-    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(): boolean {
-    return [...this.notices.values()].some((n) => n.notice.kind === "wake");
+    return this.config.updates === true || [...this.notices.values()].some((n) => n.notice.kind === "wake");
   }
 
   /**
@@ -220,6 +277,233 @@ 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.
+   */
+  readonly update: Update = (conversationId, surface, handle, props, options = {}) => {
+    const impl = surface as AnySurfaceImpl;
+    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 as UpdateOptions;
+    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: unknown;
+    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: UpdateQueue = { 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. */
+  private name(conversationId: string, first: string, replaced: string, latest: string) {
+    const names = this.surfaceNames.get(conversationId) ?? new Map<string, string>();
+    // 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.
+   */
+  private async announce(conversation: Conversation): Promise<void> {
+    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. */
+  private async revise(
+    conversationId: string,
+    impl: AnySurfaceImpl,
+    handle: string,
+    job: UpdateJob,
+  ): Promise<{ handle: string; replaced: string }> {
+    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: Conversation | null = 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: unknown = null;
+    let written: { handle: string; replaced: string } | null = 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!;
+  }
+
+  private async reviseHeld(
+    conversation: Conversation,
+    impl: AnySurfaceImpl,
+    handle: string,
+    job: UpdateJob,
+  ): Promise<{ handle: string; replaced: string }> {
+    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" as const } : {}),
+    };
+    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 as Error).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
@@ -274,6 +558,7 @@ export class Hai {
   }
 
   private async wakeTurn(conversation: Conversation, emit: Emit): Promise<WakeOutcome> {
+    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";
     if (await this.refuseIfExpired(conversation, () => {})) return "idle";
@@ -368,11 +653,13 @@ export class Hai {
     conversation: Conversation,
   ): Promise<{ blocks: TextBlock[]; through: number; wake: number }> {
     const through = conversation.noticedThrough ?? 0;
-    if (!this.notices.size) return { blocks: [], through, wake: 0 };
+    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" as const, text: `[App notification: ${n.name}] ${n.model}` }],
+        n.model === null
+          ? []
+          : [{ type: "text" as const, 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
@@ -469,6 +756,7 @@ export class Hai {
   // ─────────────────────────────────────────────────── public API
 
   async send(conversation: Conversation, text: string, emit: Emit): Promise<void> {
+    await this.announce(conversation);
     if (await this.refuseIfExpired(conversation, emit)) return;
 
     // The first message is the one that starts the conversation.
@@ -518,6 +806,7 @@ export class Hai {
    */
   async start(conversation: Conversation, emit: Emit): Promise<void> {
     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
     conversation.status = "idle";
@@ -583,7 +872,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;
@@ -609,6 +903,7 @@ export class Hai {
     input: { handle: string; action: string; value: unknown },
     emit: Emit,
   ): Promise<void> {
+    await this.announce(conversation);
     if (await this.refuseIfExpired(conversation, emit)) return;
 
     // The payload row carries a conversation id, but that alone is not enough.
@@ -618,6 +913,11 @@ 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);
@@ -742,8 +1042,9 @@ export class Hai {
    */
   private async refuseIfExpired(conversation: Conversation, emit: Emit): Promise<boolean> {
     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: { expiredAt: number; age: number; window: number | undefined } | null = null;
@@ -756,6 +1057,12 @@ export class Hai {
     }
 
     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);
@@ -844,7 +1151,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;
@@ -887,7 +1206,16 @@ export class Hai {
 
     // 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: AnySurfaceImpl, props: unknown, surfaceMode: "display" | "elicit") => {
+    const show = async (
+      impl: AnySurfaceImpl,
+      props: unknown,
+      surfaceMode: "display" | "elicit",
+      // the handle this revises in place, for `update`
+      replaces?: string,
+      // last word before the surface is attached and sent: throwing leaves the
+      // stored payload unreferenced, inert as an overtaken turn's
+      beforeAttach?: () => void,
+    ) => {
       // Validate before storing: props may originate outside this process.
       const parsed = impl.surface.props.parse(props);
       const window = windowOf(impl);
@@ -912,6 +1240,7 @@ export class Hai {
 
       // 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.
@@ -928,6 +1257,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 });
 
@@ -970,6 +1300,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;
       } catch (err) {
@@ -980,6 +1311,57 @@ export class Hai {
       }
     };
 
+    // 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: AnySurfaceImpl, handle: string, props: unknown): Promise<ToolReturn> => {
+      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<string>();
+      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
@@ -1033,6 +1415,19 @@ export class Hai {
         );
         return shown;
       }) as ToolCtx["render"],
+      update: ((impl: AnySurfaceImpl, handle: string, props: unknown) => {
+        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;
+      }) as ToolCtx["update"],
     };
 
     let input: unknown;
@@ -1063,7 +1458,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 as { handle?: unknown } | null)?.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.
@@ -1143,6 +1544,17 @@ function strictest(recorded: unknown, current: unknown): number | "never" | unde
 
 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: Conversation, handle: string): string {
+  const seen = new Set<string>();
+  let at = handle;
+  while (conversation.superseded?.[at] && !seen.has(at)) {
+    seen.add(at);
+    at = conversation.superseded[at];
+  }
+  return at;
+}
+
 interface TextBlock {
   type: "text";
   text: string;

package/src/store.ts

@@ -108,6 +108,8 @@ export function memoryStore(options: MemoryStoreOptions = {}): StoreAdapter {
         wakes: [],
         wokeThrough: 0,
         wakeTurns: 0,
+        superseded: {},
+        announcing: null,
       };
       conversations.set(conversation.id, conversation);
       return copy(conversation);