@jxsuite/studio 5.3.0 → 5.4.0

package/src/services/ai-settings.ts

@@ -20,9 +20,11 @@
  */
 
 import { SETTINGS } from "./settings/definitions";
+import type { SettingDefinition } from "./settings/definitions";
 import {
   clearSettings,
   hasSetting,
+  normalizeSetting,
   readStoredSetting,
   setSetting,
   setSettings,
@@ -82,6 +84,13 @@ export function setModel(modelId: string) {
   setSetting(SETTINGS.aiModel, modelId || "");
 }
 
+/** The provider's three values together — what a credentials form drafts and what Save stores. */
+export interface AiProvider {
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+}
+
 /**
  * Store the provider's key, endpoint and model as ONE change.
  *
@@ -89,9 +98,9 @@ export function setModel(modelId: string) {
  * anyway, but they announce three times, and each intermediate announcement describes a provider
  * the user never asked for — a new key against the old endpoint, then against no model.
  *
- * @param {{ apiKey: string; baseUrl: string; model: string }} provider
+ * @param {AiProvider} provider
  */
-export function saveAiProvider(provider: { apiKey: string; baseUrl: string; model: string }) {
+export function saveAiProvider(provider: AiProvider) {
   setSettings([
     [SETTINGS.aiOpenAiKey, provider.apiKey],
     [SETTINGS.aiBaseUrl, provider.baseUrl],
@@ -99,6 +108,50 @@ export function saveAiProvider(provider: { apiKey: string; baseUrl: string; mode
   ]);
 }
 
+/**
+ * Whether {@link saveAiProvider} with these values would change what is stored.
+ *
+ * What a credentials form's Save and Cancel are drawn from: at rest there is nothing to keep and
+ * nothing to abandon. Each value is compared as the store WOULD hold it — through its definition's
+ * own `normalize` — so a pasted key's whitespace or an endpoint's trailing slash is not an edit,
+ * because Save would store exactly what is already there. An absent setting reads as `""`, as every
+ * getter here does, so a blank draft over nothing is no change either.
+ *
+ * **BOTH sides are normalised, not just the draft.** Only the setters normalise on the way in;
+ * `hydrateSettings` and `adoptRemoteSettings` put a backend's or another window's values into the
+ * cache as they found them, and a hand-edited `settings.json` carries whatever was typed. So the
+ * store legitimately holds `http://localhost:11434/v1/` with the trailing slash the docs print, and
+ * comparing a normalised draft against that raw value reported an edit nobody had made: Save and
+ * Cancel appeared on a form at rest, and Cancel could not clear them, because reloading the drafts
+ * loaded the same unnormalised value again. Normalising the stored side is the comparison the
+ * sentence above always claimed to be making.
+ *
+ * @param {AiProvider} provider The drafts.
+ * @returns {boolean} `true` when at least one of the three would move.
+ */
+export function aiProviderDiffers(provider: AiProvider): boolean {
+  return (
+    !storedEquals(SETTINGS.aiOpenAiKey, provider.apiKey, getOpenAiKey()) ||
+    !storedEquals(SETTINGS.aiBaseUrl, provider.baseUrl, getBaseUrl()) ||
+    !storedEquals(SETTINGS.aiModel, provider.model, storedModel())
+  );
+}
+
+/**
+ * Whether a draft and a stored value are the same setting, judged as the store would hold each.
+ *
+ * Exported because a form's "has the user touched this field?" has to ask the same question as
+ * {@link aiProviderDiffers}, or the two disagree about a whitespace-only draft — which is how a
+ * revoked key survived a Disconnect (`ui/ai-credentials-form.ts`).
+ */
+export function storedEquals(
+  definition: SettingDefinition,
+  draft: string,
+  stored: string,
+): boolean {
+  return normalizeSetting(definition, draft) === normalizeSetting(definition, stored);
+}
+
 /**
  * Forget the provider entirely — key, endpoint and model.
  *

package/src/services/ai-tools.ts

@@ -3,27 +3,30 @@
  *
  * Concrete `.jx` AST tools registered into a `@jxsuite/ai` ToolRegistry. Each tool wraps an
  * existing `transactDoc()` mutation helper so AI edits get the same undo/redo history as manual
- * edits (ADR docs/ai-assistant-decision.md §5 — optimistic apply + undo).
+ * edits (specs/ai.md §3.1 and §3.2 — optimistic apply, undo as the backstop).
  *
  * @license MIT
  */
 
 import { createToolDefinition } from "@jxsuite/ai/tools";
-import type { ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
+import type { ToolRegistry, ToolResult, WriteLedger } from "@jxsuite/ai/tools";
 import type { JxMutableNode, JxPath, JxStateDefinition } from "@jxsuite/schema/types";
 import { getNodeAtPath } from "../state";
 import type { Tab } from "../tabs/tab";
 import {
+  mutateAddDef,
   mutateInsertNode,
   mutateMoveNode,
+  mutateRemoveDef,
   mutateUpdateProperty,
   mutateUpdateStyle,
   transactDoc,
 } from "../tabs/transact";
 import type { JxNodeValue } from "../tabs/transact";
+import type { JsonValue } from "../types";
 import { validateDoc } from "./jx-validate";
-import { recordWrite } from "./ai-writes";
-import { serializeJson } from "../files/json-layout";
+import { invalidPathResult, normalizeRelPath } from "./project-path";
+import { serializeJson } from "@jxsuite/schema/json-layout";
 import {
   reportDocumentWrite,
   snapshotBeforeWrite,
@@ -52,11 +55,12 @@ function noDocError(): ToolResult {
 
 /**
  * Apply a mutation, then hand the verdict to `ai-write-report.ts`: only the schema errors the edit
- * NEWLY introduced are reported (the eval signal — ADR §6b), the render check runs when a
- * renderCheck was provided and rendering worked before, and a success carries the token hints. The
- * change stays applied either way (optimistic apply + undo, ADR §5); reporting the errors lets the
- * agent loop self-correct on the next round.
+ * NEWLY introduced are reported, the render check runs when a renderCheck was provided and
+ * rendering worked before, and a success carries the token hints. The change stays applied either
+ * way (optimistic apply + undo); reporting the errors lets the agent loop self-correct on the next
+ * round. Both rules are specs/ai.md §3.1.
  *
+ * @param {WriteLedger} ledger - The call's ledger (`ctx.ledger`)
  * @param {import("../tabs/tab").Tab} tab
  * @param {(t: import("../tabs/tab").Tab) => void} mutationFn
  * @param {string} summary
@@ -66,6 +70,7 @@ function noDocError(): ToolResult {
  * @returns {Promise<import("@jxsuite/ai/tools").ToolResult>}
  */
 async function applyAndValidate(
+  ledger: WriteLedger,
   tab: Tab,
   mutationFn: (t: Tab) => void,
   summary: string,
@@ -91,9 +96,9 @@ async function applyAndValidate(
     };
   }
   /* One ledger entry per mutation, so the panel's "Changed N files" counts documents the model
-     touched rather than sentences it wrote (§7.4). `disk: false` is the load-bearing half: this
-     went through transactDoc, so the tab's history — and "Restore to here" — can reach it. */
-  recordWrite({ disk: false, ok: true, path: tab.documentPath ?? "(untitled)", tool: summary });
+     touched rather than sentences it wrote (`ai.md` §3.2). `disk: false` is the load-bearing half:
+     this went through transactDoc, so the tab's history — and "Restore to here" — can reach it. */
+  ledger.record({ disk: false, ok: true, path: tab.documentPath ?? "(untitled)", tool: summary });
 
   return reportDocumentWrite(tab, before, summary, deps);
 }
@@ -225,11 +230,11 @@ export function registerAiTools(
         },
         /*
          * "value" omitted from required: passing null / omitting it means "remove the property",
-         * but the registry rejects null on required args (tools.js:181). See §14.
+         * but the registry rejects null on required args (tools.js:181). See `ai.md` §3.6.
          */
         required: ["path", "key"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -240,6 +245,7 @@ export function registerAiTools(
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
           (t) => mutateUpdateProperty(t, path, key, value ?? undefined),
           `Set "${key}" at ${JSON.stringify(path)}.`,
@@ -275,7 +281,7 @@ export function registerAiTools(
         },
         required: ["parentPath", "index", "node"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -318,6 +324,7 @@ export function registerAiTools(
           };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
           (t) => mutateInsertNode(t, parentPath, index, childNode),
           `Inserted node at ${JSON.stringify([...parentPath, "children", index])}.`,
@@ -357,11 +364,11 @@ export function registerAiTools(
         },
         /*
          * "value" omitted from required so null / omitted = remove (registry rejects null on
-         * required args, tools.js:181). See §14.
+         * required args, tools.js:181). See `ai.md` §3.6.
          */
         required: ["path", "property"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -377,6 +384,7 @@ export function registerAiTools(
         const prop = property;
         const val = value == null ? undefined : String(value);
         return applyAndValidate(
+          ctx.ledger,
           tab,
           (t) => mutateUpdateStyle(t, path, prop, val),
           `Set style "${prop}" at ${JSON.stringify(path)}.`,
@@ -407,7 +415,7 @@ export function registerAiTools(
         },
         required: ["path", "value"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -417,11 +425,14 @@ export function registerAiTools(
           return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
+          /* Through the recording mutators, as two `set-key` ops, rather than by writing the node
+             directly. An unrecorded write reaches the canvas only as a full re-render, history only
+             as a whole-document snapshot, and collaborators only as a diff. */
           (t) => {
-            const node = getNodeAtPath(t.doc.document, path);
-            delete node.textContent;
-            node.children = [value];
+            mutateUpdateProperty(t, path, "textContent");
+            mutateUpdateProperty(t, path, "children", [value]);
           },
           `Set text at ${JSON.stringify(path)}.`,
           validate,
@@ -453,7 +464,7 @@ export function registerAiTools(
         },
         required: ["key", "value"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -466,18 +477,12 @@ export function registerAiTools(
           };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
-          (t) => {
-            // Ensure the state object exists before setting a key on it.
-            if (!t.doc.document.state) {
-              t.doc.document.state = {};
-            }
-            /*
-             * Directly mutate — bypass mutateUpdateProperty because its "" → delete behaviour
-             * (transact.ts:248) is wrong for state defaults (e.g. "title": "").
-             */
-            t.doc.document.state[key] = value;
-          },
+          /* `mutateAddDef` rather than `mutateUpdateProperty`: the latter deletes on "", which is
+             wrong for a state default (`"title": ""`). It also records the op, so the canvas, the
+             history and collaborators each get the edit as an edit. */
+          (t) => mutateAddDef(t, key, value as Record<string, JsonValue>),
           `Added state "${key}".`,
           validate,
           renderCheck,
@@ -505,11 +510,11 @@ export function registerAiTools(
         },
         /*
          * "value" omitted from required so null = remove (registry rejects null on required
-         * args, tools.js:181). See §14.
+         * args, tools.js:181). See `ai.md` §3.6.
          */
         required: ["key"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -522,20 +527,15 @@ export function registerAiTools(
           };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
+          /* The recording def mutators, for the reason `add_state` gives. Removing the last key
+             drops the empty `state` object, as the Inspector's own removal does. */
           (t) => {
-            /*
-             * Directly mutate — bypass mutateUpdateProperty because its "" → delete behaviour
-             * (transact.ts:248) is wrong for state defaults (e.g. "title": "").
-             */
-            const { state } = t.doc.document;
-            if (!state) {
-              return;
-            }
             if (value == null) {
-              delete state[key];
+              mutateRemoveDef(t, key);
             } else {
-              state[key] = value;
+              mutateAddDef(t, key, value as Record<string, JsonValue>);
             }
           },
           value == null ? `Removed state "${key}".` : `Updated state "${key}".`,
@@ -575,7 +575,7 @@ export function registerAiTools(
         },
         required: ["fromPath", "toParentPath", "toIndex"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         const tab = getTab();
         if (!tab) {
           return noDocError();
@@ -601,6 +601,7 @@ export function registerAiTools(
           };
         }
         return applyAndValidate(
+          ctx.ledger,
           tab,
           (t) => mutateMoveNode(t, fromPath, toParentPath, toIndex),
           `Moved node from ${JSON.stringify(fromPath)} to ${JSON.stringify([...toParentPath, "children", toIndex])}.`,
@@ -636,14 +637,19 @@ export function registerAiTools(
         },
         required: ["path", "content"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         if (!saveFile) {
           return {
             success: false,
             error: "File operations are not available in this environment.",
           };
         }
-        const { path: relPath, content } = args as { path: string; content: object };
+        const { path, content } = args as { path: string; content: object };
+        // Inside the project or not at all (ai.md §4): the platform write is given this path.
+        const relPath = normalizeRelPath(path);
+        if (relPath === null) {
+          return invalidPathResult(path);
+        }
         const dirtyError = dirtyTabError(relPath);
         if (dirtyError) {
           return dirtyError;
@@ -666,17 +672,17 @@ export function registerAiTools(
           }
         }
         try {
-          // The save serializer, layout-less (`files/json-layout.ts`): the assistant supplied a
+          // The save serializer, layout-less (`@jxsuite/schema/json-layout`): the assistant supplied a
           // Value, not a text, so the formatter's layout for fresh output is the right one.
           await saveFile(relPath, serializeJson(content, null));
-          recordWrite({ disk: true, ok: true, path: relPath, tool: "create_component" });
+          ctx.ledger.record({ disk: true, ok: true, path: relPath, tool: "create_component" });
           return {
             success: true,
             summary: await reconcileAfterWrite(relPath, `Created component at "${relPath}".`),
           };
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          recordWrite({
+          ctx.ledger.record({
             disk: true,
             error: message,
             ok: false,
@@ -715,14 +721,18 @@ export function registerAiTools(
         },
         required: ["path", "content"],
       },
-      async execute(args) {
+      async execute(args, ctx) {
         if (!saveFile) {
           return {
             success: false,
             error: "File operations are not available in this environment.",
           };
         }
-        const { path: relPath, content } = args as { path: string; content: object };
+        const { path, content } = args as { path: string; content: object };
+        const relPath = normalizeRelPath(path);
+        if (relPath === null) {
+          return invalidPathResult(path);
+        }
         const dirtyError = dirtyTabError(relPath);
         if (dirtyError) {
           return dirtyError;
@@ -747,14 +757,14 @@ export function registerAiTools(
         try {
           // As `create_component`: a value the assistant supplied, written in the formatter's layout.
           await saveFile(relPath, serializeJson(content, null));
-          recordWrite({ disk: true, ok: true, path: relPath, tool: "create_page" });
+          ctx.ledger.record({ disk: true, ok: true, path: relPath, tool: "create_page" });
           return {
             success: true,
             summary: await reconcileAfterWrite(relPath, `Created page at "${relPath}".`),
           };
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          recordWrite({
+          ctx.ledger.record({
             disk: true,
             error: message,
             ok: false,
@@ -773,9 +783,10 @@ export function registerAiTools(
   /*
    * `open_document` is NOT here any more. It is the projection of the `document.open` record
    * (`workspace/workspace.ts`'s `tabCommands`), so the person's palette row and the model's tool
-   * are one `run` and one gate (§12.4). The hand tool read `getTab()` after the open and called
-   * whatever it found a success — a missing file left the previous document active and reported
-   * "Switched to" — and it re-anchored the undo batch itself, which `tool-executor.ts` has done
-   * after EVERY tool since project adoption started replacing tabs mid-loop.
+   * are one `run` and one gate (`studio-ui-guidelines.md` §12.4). The hand tool read `getTab()`
+   * after the open and called whatever it found a success — a missing file left the previous
+   * document active and reported "Switched to" — and it re-anchored the undo batch itself, which
+   * `tool-executor.ts` has done after EVERY tool since project adoption started replacing tabs
+   * mid-loop.
    */
 }

package/src/services/ai-write-report.ts

@@ -8,14 +8,14 @@
  * with:
  *
  * 1. {@link snapshotBeforeWrite} reads the document's schema errors and render state BEFORE the
- *    write, because the eval signal (ADR docs/ai-assistant-decision.md §6b) is "what did this edit
- *    newly introduce", not "is the document valid": a page that was already broken must not make
- *    every subsequent edit read as the culprit.
+ *    write, because the loop's signal (specs/ai.md §3.1) is "what did this edit newly introduce",
+ *    not "is the document valid": a page that was already broken must not make every subsequent
+ *    edit read as the culprit.
  * 2. {@link reportDocumentWrite} compares AFTER the write, translating each new schema error into a
  *    fix hint the model can act on, running the render check only when rendering worked before,
  *    and appending the soft token-discipline hints to a success.
  *
- * The change stays applied either way (optimistic apply + undo, ADR §5); reporting the errors lets
+ * The change stays applied either way (optimistic apply + undo, specs/ai.md §3.1); reporting the errors lets
  * the agent loop self-correct on the next round.
  *
  * @license MIT

package/src/services/ai-writes.ts

@@ -1,7 +1,8 @@
 /**
  * Ai-writes.ts — what the assistant changed, per turn, and whether you can take it back.
  *
- * §7.4 (AI honesty). Two facts about an assistant turn were legible only to the model:
+ * `ai.md` §3.2 (the accountable turn). Two facts about an assistant turn were legible only to the
+ * model:
  *
  * 1. **Which files it changed.** The loop collected `result.summary` strings and fed them back into
  *    the conversation; the human got a paragraph of prose in which "I updated the hero" and "I
@@ -17,27 +18,15 @@
  *
  * The tools record; the loop bounds the turn; the panel renders. Nothing here knows about lit, and
  * nothing here imports the loop, so a tool can be honest without either.
+ *
+ * @docs studio/ai/chat
  */
 
-/** One change the assistant made, as recorded by the tool that made it. */
-export interface AiWrite {
-  /** Project-relative path, or the document path for an in-editor mutation. */
-  path: string;
-  /** The tool that did it — the command title the chip renders. */
-  tool: string;
-  /**
-   * True when the change went to disk with no transaction behind it.
-   *
-   * This is the undo caveat, as a fact rather than a sentence: a `disk` write is NOT reachable by
-   * ⌘Z, by the tab's history, or by "Restore to here". The panel says so, in those words, to the
-   * person who would otherwise press ⌘Z and believe it worked.
-   */
-  disk: boolean;
-  /** False when the tool reported a failure — a listed attempt that changed nothing. */
-  ok: boolean;
-  /** Why it failed, when it did. */
-  error?: string;
-}
+import type { Message } from "@jxsuite/ai/chat-state";
+import { createLedger } from "@jxsuite/ai/tools";
+import type { AiWrite, WriteLedger } from "@jxsuite/ai/tools";
+
+export type { AiWrite } from "@jxsuite/ai/tools";
 
 /** Every write recorded during one assistant turn, in the order the tools made them. */
 export interface AiTurn {
@@ -52,52 +41,42 @@ const turns: AiTurn[] = [];
 /** How many turns of ledger are kept. Older ones drop their summary; the messages remain. */
 export const MAX_TURNS = 50;
 
-let open: AiTurn | null = null;
-
-/**
- * Start recording. Called by the agent loop once per user turn.
- *
- * Idempotent on the same id so a nested or re-entered loop cannot split one turn's writes across
- * two ledgers — which is the same class of bug as the batch that was opened against whichever tab
- * happened to be active.
- *
- * @param {string} id
- */
-export function beginTurn(id: string): void {
-  if (open?.id === id) {
-    return;
-  }
-  open = { id, writes: [] };
+/** One turn's ledger, named for the turn it records. */
+export interface TurnLedger extends WriteLedger {
+  readonly turnId: string;
 }
 
 /**
- * Record one change. A no-op when no turn is open, so a tool invoked outside the loop — a command,
- * a test — costs nothing and reports nothing.
+ * A fresh ledger for one turn. The loop opens it when the turn starts, hands it to every call as
+ * `ctx.ledger`, and files it with {@link fileTurn} when the turn ends.
+ *
+ * Per turn, not a module slot: the slot this replaced was one ledger for the whole window, so a
+ * tool run outside the loop recorded into whichever turn happened to be open, and two turns could
+ * not each keep their own.
  *
- * @param {AiWrite} write
+ * @param {string} turnId - The turn it records, which also names the actor its calls run as
+ * @returns {TurnLedger}
  */
-export function recordWrite(write: AiWrite): void {
-  open?.writes.push(write);
+export function openTurnLedger(turnId: string): TurnLedger {
+  return Object.assign(createLedger(), { turnId });
 }
 
 /**
- * Close the open turn and file it under `id`.
+ * File a finished turn's writes under `anchor`, the message the transcript draws its summary under.
  *
- * The id arrives at the END because it is the assistant message's id, which does not exist when the
- * turn starts — the loop opens the turn before it knows what the model will say.
+ * The anchor arrives at the END because it is an assistant message's id, which does not exist when
+ * the turn starts. A turn with no drawn message is filed under `""`, which no message has, so the
+ * transcript draws its changes nowhere. A turn that wrote nothing files nothing.
  *
- * @param {string} id - The assistant message the turn produced
- * @returns {AiWrite[]} What was recorded
+ * @param {string} anchor - The message the turn's changes are drawn under
+ * @param {readonly AiWrite[]} writes - The turn's ledger
+ * @returns {AiWrite[]} What was filed
  */
-export function endTurn(id: string): AiWrite[] {
-  if (!open) {
-    return [];
-  }
-  const turn: AiTurn = { id, writes: open.writes };
-  open = null;
-  if (turn.writes.length === 0) {
+export function fileTurn(anchor: string, writes: readonly AiWrite[]): AiWrite[] {
+  if (writes.length === 0) {
     return [];
   }
+  const turn: AiTurn = { id: anchor, writes: [...writes] };
   turns.push(turn);
   while (turns.length > MAX_TURNS) {
     turns.shift();
@@ -147,8 +126,48 @@ export function summarizeWrites(writes: AiWrite[]): string {
   return parts.join(" · ");
 }
 
-/** Drop every ledger. For tests and for the "new chat" / "close project" paths. */
+/**
+ * Drop every ledger: New Chat (the messages they are drawn under are gone), leaving a project
+ * (their paths name the project left behind; `setWorkspaceProject`), and tests.
+ */
 export function resetAiWrites(): void {
   turns.splice(0);
-  open = null;
+}
+
+/**
+ * The message a turn's changes are filed under: its last DRAWN assistant message, which is the one
+ * the transcript renders the changed-files summary beneath (panels/ai-chat/chat-view.ts), and so
+ * the id {@link fileTurn} is given.
+ *
+ * Not simply the last message. A turn can end on a `tool` reply (a Stop during the last call, or a
+ * cap reached with nothing applied), on a final round that said nothing, or after a stream error
+ * removed its round's partial; filed under any of those, the summary and Restore were drawn under
+ * nothing and the author never saw what the turn changed. The cap message counts: it is drawn.
+ *
+ * **An anchor is only ever this turn's.** The scan must MEET the message the turn answers, and only
+ * what it passed on the way counts. A transcript that no longer holds that message was replaced
+ * under the turn (another chat opened from Chat History while it waited on a tool), and every
+ * message in it belongs to some other conversation: filing there would draw "Changed 1 file", and
+ * Restore, under a reply that changed nothing.
+ *
+ * @param {readonly Message[]} messages
+ * @param {string} [userId] - The id of the user message this turn answers; without one, the whole
+ *   transcript is the turn
+ * @returns {string | null} Null when the turn drew nothing (so it ran no tool either), or when its
+ *   user message has left the transcript
+ */
+export function turnAnchor(messages: readonly Message[], userId?: string): string | null {
+  let anchor: string | null = null;
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index]!;
+    if (message.id === userId) {
+      return anchor;
+    }
+    const drawn =
+      message.role === "assistant" && (message.content || (message.toolCalls?.length ?? 0) > 0);
+    if (anchor === null && drawn) {
+      anchor = message.id;
+    }
+  }
+  return userId === undefined ? anchor : null;
 }