@jxsuite/studio 5.2.0 → 5.4.0

package/src/services/automation.ts

@@ -6,9 +6,9 @@
  * exactly three members (spec studio.md §13.5):
  *
  * - `run(id, args)` — **is** `registry.run(id, args)`, behind {@link isScriptable}. There is no
- *   second action table. A hand-maintained parallel list of what the app can do is what plan §2
- *   principle 1 defines as a defect, and this module used to be 39 entries of exactly that, 16 of
- *   them holding raw XPath into the shell and three of them matching RENDERED TEXT.
+ *   second action table. A hand-maintained parallel list of what the app can do is what §13 defines
+ *   as a defect, and this module used to be 39 entries of exactly that, 16 of them holding raw
+ *   XPath into the shell and three of them matching RENDERED TEXT.
  * - `seed(id, args)` — the {@link SEEDS} registry, under the **Remote Rule**: a seed may only write
  *   state whose real writer is a network or IPC boundary. It stands in for a remote, never for a
  *   user. {@link REFUSED_SEEDS} names what that excludes and why.
@@ -16,7 +16,7 @@
  *   `state()` (the full `CommandContext`), `commands()`, `seeds()`, and `pointAt`/`revealPath`,
  *   which compose the app's own transforms and answer in top-document coordinates.
  *
- * **What is deliberately absent**, each a normative refusal in spec §13.5:
+ * **What is deliberately absent**, each a normative refusal in studio.md §13.5:
  *
  * 1. No method that takes a selector. If a script cannot say it in command ids and `JxPath`s, it
  *    cannot say it here.
@@ -97,7 +97,7 @@ export function isScriptable(command: AnyCommand): boolean {
  *
  * - `command` — a thing a user does, so it becomes a registry record. The value names who lands it.
  * - `seed` — a remote's state, addressed through {@link AutomationApi.seed}.
- * - `refused` — §13.3 says the app will never provide it; the manifest step is deleted.
+ * - `refused` — §13.5 says the app will never provide it; the manifest step is deleted.
  */
 export type GapDisposition = "command" | "seed" | "refused";
 
@@ -118,8 +118,8 @@ export interface ManifestId {
  * — only to explain, when the registry refuses an id, which of the three fates that id has.
  *
  * This is a countdown, in the idiom of the checker's own `TOGGLE_DEBT`: it may only shrink. It went
- * 39 → 8 when the manifest converted (S2), and 8 → 7 when `element.insertData` became `insert.data`
- * (P5, `canvas/canvas-render.ts`). What left: every `seed` entry, now read off {@link seedIds} and
+ * 39 → 8 when the manifest converted, and 8 → 7 when `element.insertData` became `insert.data`
+ * (`canvas/canvas-render.ts`). What left: every `seed` entry, now read off {@link seedIds} and
  * answered from the live registry rather than from a hand-kept list; every `toggle*` entry, which
  * {@link TOGGLE_ID} refuses before this map is ever consulted; and every `command` entry whose
  * record has since landed.
@@ -127,7 +127,7 @@ export interface ManifestId {
  * What is left is two kinds. Two `command` entries are the manifest's real registry gaps — each
  * reached today by an `input` step clicking a hand-stamped region, and each of those steps carries
  * an `unstable` hatch naming the phase that lands the record, so this map and that hatch count are
- * the same debt. Five `refused` entries are NOT a countdown: they are §13.3's normative refusals,
+ * the same debt. Five `refused` entries are NOT a countdown: they are §13.5's normative refusals,
  * and they stay so that a caller reaching for one gets the reason instead of "unknown command".
  */
 export const AUTOMATION_COMMANDS: Readonly<Record<string, ManifestId>> = {
@@ -137,9 +137,9 @@ export const AUTOMATION_COMMANDS: Readonly<Record<string, ManifestId>> = {
   },
   "layers.contextMenu": {
     disposition: "refused",
-    note: "matched RENDERED TEXT, which §13's R1 forbids; P5.5 stamps data-jx-path on rows",
+    note: "matched RENDERED TEXT, which R1 of scripts/screenshots/README.md forbids; a row is addressed by its data-jx-path",
   },
-  "media.browse": { disposition: "command", note: "P7.5 — media.browse" },
+  "media.browse": { disposition: "command", note: "media.browse, site-architecture.md §9.4" },
   "project.showWelcome": {
     disposition: "refused",
     note: "cold start is a startup profile (?profile=fresh), not an action",
@@ -176,7 +176,7 @@ export const REFUSED_SEEDS: Readonly<Record<string, string>> = {
   setActivity: 'a user picks a Navigator panel — run("navigator.showPanel", { panel })',
   setRightTab: 'a user picks an Inspector tab — run("inspector.setTab", { tab })',
   setStatus:
-    "the status bar reports what the app just did; staging it is the one lie §13.3 names outright",
+    "the status bar reports what the app just did; staging it is the one lie the Remote Rule (studio.md §13.5) names outright",
   setZoom: 'a user zooms — run("canvas.setZoom", { zoom })',
 };
 
@@ -315,7 +315,7 @@ export interface ScriptableCommand {
   args?: object;
 }
 
-/** What `pointAt` can address. Region ids join `path` when P3.8's region registry lands. */
+/** What `pointAt` can address. Region ids join `path` when a region registry lands. */
 export interface AutomationTarget {
   path: JxPath;
 }

package/src/services/clock.ts

@@ -8,7 +8,8 @@
  * 1. **They were untestable.** A formatter that reads the wall clock can only be asserted against an
  *    offset from the real present, so "yesterday" and "over a year ago" were never covered.
  * 2. **They drift.** Two captures of the same state minutes apart legitimately read `01:59 PM` and
- *    `02:04 PM` (UX-REDESIGN-PLAN §13.4 measured exactly that on the git-panel shot).
+ *    `02:04 PM` (the shot contract's Determinism section measured exactly that on the git-panel
+ *    shot).
  *
  * This is deliberately NOT a global `Date.now` override. Monaco, every `setTimeout`, the collab
  * clock and the transaction log all read the real clock and must keep reading it — pinning time for

package/src/services/connection.ts

@@ -11,8 +11,8 @@
  * The transport now rejects those calls, and this is the other half: a person needs to be told
  * which of "it is broken" and "it is coming back" they are in. One keyed problem so a flapping
  * connection cannot stack up a column of identical rows, dismissed on recovery so a fixed thing
- * does not stay on the Problems list (§16.1's third tier, and §16.6's rule that a record is retired
- * by whoever owns its life).
+ * does not stay on the Problems list (§16.1's second and third rules: a record is retired when what
+ * it names is fixed, and a repeat is not a new row).
  *
  * A platform without `subscribeConnection` — the dev server, electrobun — installs nothing. There
  * is no connection to lose there, and a notice about one would be a lie.

package/src/services/context-manager.ts

@@ -2,7 +2,7 @@
  * Context-manager.js — Token budget management for the AI assistant
  *
  * Estimates token usage and trims conversation history before each send to keep the
- * context window within safe limits (ADR docs/ai-assistant-decision.md §11.4).
+ * context window within safe limits (specs/ai.md §2 and §2.1).
  *
  * Strategy (MVP): keep the system prompt + the most recent messages, dropping the oldest
  * messages when the estimated total exceeds the configured token budget. Dropped messages
@@ -30,7 +30,8 @@ const CHARS_PER_TOKEN = 4;
 
 /**
  * Approximate context windows (in tokens) per model id, longest-prefix matched. Used to derive a
- * model-aware budget instead of a flat cap (ADR §14.2). Conservative fallback for unknown models.
+ * model-aware budget instead of a flat cap (specs/ai.md §2.1). Conservative fallback for unknown
+ * models.
  */
 const MODEL_CONTEXT_WINDOWS: [string, number][] = [
   ["gpt-4o", 128_000],
@@ -123,6 +124,64 @@ function estimateTokens(input: string | MessageArrayEntry[]): number {
   return total;
 }
 
+/** The wire-shaped entry {@link estimateTokens} reads, for one transcript message. */
+function wireEntry(msg: ReturnType<typeof createChatState>["messages"][number]): MessageArrayEntry {
+  const entry: MessageArrayEntry = { content: msg.content, role: msg.role };
+  if (msg.toolCalls) {
+    entry.tool_calls = msg.toolCalls.map((tc) => ({
+      function: { arguments: tc.arguments, name: tc.name },
+    }));
+  }
+  return entry;
+}
+
+/**
+ * The context's size in tokens, as close to the provider's own count as the transcript allows.
+ *
+ * When the provider reported a count (`chatState.usage`) for a transcript this one still extends
+ * (the message at the count's boundary is the one it was taken at), that count covers everything up
+ * to it exactly, tool schemas included, so only the messages added since are estimated, plus
+ * whatever the system prompt has grown by. Without one, or once the transcript has been trimmed,
+ * rewound or repaired beneath it, the whole history is estimated at four characters per token,
+ * which is what every budget used before the count was forwarded.
+ */
+function contextTokens(
+  chatState: ReturnType<typeof createChatState>,
+  systemTokens: number,
+): number {
+  const { usage, messages } = chatState;
+  const boundary = usage ? messages[usage.messageCount - 1] : undefined;
+  if (usage && boundary && boundary.id === usage.lastMessageId) {
+    /* Only what will be SENT: `toMessagesArray` drops an assistant turn carrying neither text nor
+       tool calls — the placeholder `sendMessage` pushes is always one — so it is not counted. */
+    const since = messages
+      .slice(usage.messageCount)
+      .filter((msg) => msg.role !== "assistant" || msg.content || (msg.toolCalls?.length ?? 0) > 0)
+      .map((msg) => wireEntry(msg));
+    /* The system prompt is rebuilt on every send from live state (the document outline, the file
+       inventory), so the one the count covered is not the one about to go out. What it has grown
+       or shrunk by is added, estimated the same way on both sides. */
+    const promptDrift = usage.systemTokens === undefined ? 0 : systemTokens - usage.systemTokens;
+    const reused = Math.max(0, usage.contextTokens + promptDrift) + estimateTokens(since);
+    // A count this module cannot trust is no count at all.
+    if (Number.isFinite(reused)) {
+      return reused;
+    }
+  }
+  return systemTokens + estimateTokens(chatState.toMessagesArray() as MessageArrayEntry[]);
+}
+
+/**
+ * The estimate of a system prompt, in the same units {@link trimContext} budgets in — what the loop
+ * records beside a provider's count so the next budget can measure the prompt's drift.
+ *
+ * @param {string} systemPrompt
+ * @returns {number}
+ */
+export function estimatePromptTokens(systemPrompt: string): number {
+  return estimateTokens(systemPrompt);
+}
+
 // ─── Trim ───────────────────────────────────────────────────────────────────
 
 /**
@@ -146,8 +205,7 @@ export function trimContext(
 
   const systemTokens = estimateTokens(systemPrompt);
   const allMessages = chatState.messages;
-  const messageTokens = estimateTokens(chatState.toMessagesArray());
-  const total = systemTokens + messageTokens;
+  const total = contextTokens(chatState, systemTokens);
 
   if (total <= maxTokens) {
     chatState.setTokenCount(total);
@@ -194,6 +252,8 @@ export function trimContext(
 
   const droppedCount = keepFrom;
   allMessages.splice(0, keepFrom);
+  // The provider counted a transcript that no longer exists; the estimate is all there is now.
+  chatState.clearUsage();
 
   // Insert a summary note so the model knows context was trimmed.
   allMessages.unshift({
@@ -212,8 +272,11 @@ export function trimContext(
 
 // ─── Orphaned tool calls ────────────────────────────────────────────────────
 
-/** What a synthesized result says, so a reader and the model see the same reason. */
-const UNANSWERED_TOOL_RESULT = JSON.stringify({
+/**
+ * What a synthesized result says, so a reader and the model see the same reason. Exported so a
+ * restore can tell a seal from a reply (services/tool-outcomes.ts).
+ */
+export const UNANSWERED_TOOL_RESULT = JSON.stringify({
   success: false,
   error:
     "This tool call was never completed — the session was reloaded or the history was trimmed.",

package/src/services/directory-picker.ts

@@ -12,9 +12,17 @@
  * drop a hidden {@link LOCATION_ID_FILE} holding a freshly generated id and ask the backend which
  * directory holds that exact id. A fixed filename with the identity in its _contents_ is what makes
  * the match unambiguous: two folders may share a basename, and a stale file from a crashed session
- * may still be lying around, but only one file anywhere holds this id. The backend deletes the file
- * as soon as it matches, and this module removes it too, so neither a lost tab nor a failed lookup
- * leaves anything behind in the user's new project folder.
+ * may still be lying around, but only one file anywhere holds this id. The file lives in the chosen
+ * **Location** (the parent the project will be created in), never in the new project folder. The
+ * backend deletes it as soon as it matches, and this module removes it on every path the page
+ * survives, including a write that failed after the empty file was created. Only a tab closed
+ * mid-lookup can leave one behind, and a stale id can never match a later pick.
+ *
+ * **`null` means the user dismissed the chooser, and nothing else does.** Every other failure
+ * rejects with a sentence fit to show under the Location field: the chooser could not open, the
+ * folder cannot be written, the backend could not be reached, or it found no folder holding the id.
+ * This used to resolve `null` for all of them, which made a broken lookup indistinguishable from a
+ * cancel, and Browse… a button that silently did nothing.
  *
  * Only the plain dev-server browser session needs this. Every packaged build has a real native
  * dialog that returns a path directly and keeps it — electrobun's `Utils.openFileDialog`, and the
@@ -24,6 +32,7 @@
  */
 
 import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
+import { errorMessage } from "@jxsuite/schema/parse";
 
 /** Re-exported so a caller wiring up `locate` need not also reach into the protocol package. */
 export { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
@@ -62,54 +71,111 @@ function newLocationId(): string {
   return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+/**
+ * A thrown value's `name`, read structurally. A DOMException from another realm (an iframe's
+ * `showDirectoryPicker`, a test double) is not `instanceof Error` here, but it still says what it
+ * is.
+ */
+function nameOf(error: unknown): string {
+  return typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    typeof error.name === "string"
+    ? error.name
+    : "";
+}
+
 /**
  * Open the browser's native folder chooser and resolve the chosen folder's absolute path.
  *
- * Resolves `null` when the user cancels, when the API is unavailable, or when the backend cannot
- * place the folder (e.g. it lives outside the home directory the backend scans) — all three are "no
- * destination chosen", which the caller already handles by leaving the Location field alone.
+ * Resolves `null` only when the user dismisses the chooser (an `AbortError`, which is also what a
+ * declined readwrite grant reaches the page as: a user choice either way). Everything else rejects
+ * with an Error whose message is a plain sentence the caller can show as is:
+ *
+ * - No `showDirectoryPicker` at all (the dev-server adapter never offers Browse… then, so only an
+ *   embedder wiring this helper by hand reaches it);
+ * - The chooser refused to open (a `SecurityError` included: this runs synchronously from the click,
+ *   so a lost gesture means the environment is wrong, and silence would be a dead button);
+ * - The folder cannot be written, so it cannot be tagged, and a project could not be created there
+ *   either;
+ * - `locate` threw (backend unreachable, non-ok), or answered `null` (no folder holds the id).
  *
  * MUST be called synchronously from a user gesture; `showDirectoryPicker()` is invoked before this
  * function awaits anything so a click handler that calls it directly keeps the gesture.
  *
- * @param locate Ask the backend which directory holds `id`, given the handle's `name`.
+ * @param locate Ask the backend which directory holds `id`, given the handle's `name`. Resolve the
+ *   path, resolve `null` for "no directory holds this id", and throw on a transport or backend
+ *   failure. The not-found sentence assumes a backend that searches the home folder, as the dev
+ *   server does.
  */
 export async function pickDirectoryPath(
   locate: (query: { name: string; id: string }) => Promise<string | null>,
 ): Promise<string | null> {
   const show = (globalThis as { showDirectoryPicker?: ShowDirectoryPicker }).showDirectoryPicker;
   if (typeof show !== "function") {
-    return null;
+    throw new TypeError(
+      "This browser has no folder chooser. Type the folder's path into Location instead.",
+    );
   }
 
   let handle: DirectoryHandle;
   try {
     // `id` makes Chrome reopen at the last folder chosen for this purpose across sessions.
     handle = await show({ id: "jx-new-project-location", mode: "readwrite", startIn: "documents" });
-  } catch {
-    // AbortError on cancel; a SecurityError if the gesture was lost. Neither is worth surfacing.
-    return null;
+  } catch (error) {
+    if (nameOf(error) === "AbortError") {
+      return null;
+    }
+    throw new Error(
+      `The folder chooser could not open (${errorMessage(error)}). Type the folder's path into Location instead.`,
+      { cause: error },
+    );
   }
 
+  const { name } = handle;
   const id = newLocationId();
+  /* The `getFileHandle({ create: true })` call puts an empty file on disk before anything is
+     written, so a write that fails after it still leaves a tag to clean up. Only remove what this
+     call created. */
+  let tagged = false;
   try {
-    const file = await handle.getFileHandle(LOCATION_ID_FILE, { create: true });
-    const writable = await file.createWritable();
-    await writable.write(id);
-    await writable.close();
-  } catch {
-    // Read-only grant or a folder we cannot write: not a usable project destination anyway.
-    return null;
-  }
-  try {
-    return await locate({ id, name: handle.name });
-  } catch {
-    return null;
+    try {
+      const file = await handle.getFileHandle(LOCATION_ID_FILE, { create: true });
+      tagged = true;
+      const writable = await file.createWritable();
+      await writable.write(id);
+      await writable.close();
+    } catch (error) {
+      /* The readwrite grant was just issued, so this is the filesystem refusing: a read-only
+         mount, OS permissions, a full disk. Creating the project there would fail the same way. */
+      throw new Error(
+        `Jx Studio can't write to "${name}" (${errorMessage(error)}), so it can't create a project there. Choose a folder you can write to.`,
+        { cause: error },
+      );
+    }
+
+    let path: string | null;
+    try {
+      path = await locate({ id, name });
+    } catch (error) {
+      throw new Error(
+        `Jx Studio could not look up where "${name}" is: ${errorMessage(error)}. Type the folder's path into Location instead.`,
+        { cause: error },
+      );
+    }
+    if (!path) {
+      throw new Error(
+        `Jx Studio could not find where "${name}" is. From a browser it can only find folders inside your home folder. Type its full path into Location instead.`,
+      );
+    }
+    return path;
   } finally {
     // The backend removes the file the moment it matches; this covers every path where it did not
-    // (no match, a network failure, a backend that never ran the lookup).
-    await handle.removeEntry(LOCATION_ID_FILE).catch(() => {
-      /* Already gone — the backend beat us to it. */
-    });
+    // (no match, a network failure, a backend that never ran the lookup, a half-finished write).
+    if (tagged) {
+      await handle.removeEntry(LOCATION_ID_FILE).catch(() => {
+        /* Already gone — the backend beat us to it. */
+      });
+    }
   }
 }

package/src/services/document-assistant.ts

@@ -4,16 +4,17 @@
  *
  * Wires the @jxsuite/ai infrastructure (chat-state, proxy streaming client, tool registry) to
  * the active Jx document via `transactDoc()`-backed tools, and drives the error-correction
- * agent loop. See docs/ai-assistant-decision.md.
+ * agent loop. See specs/ai.md §3.
  *
  * @license MIT
  */
 
 import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
+import { createSessionFacts } from "@jxsuite/ai/tools";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
 import { activeTab, workspace } from "../workspace/workspace";
-import { toRaw } from "../reactivity";
+import { shallowRef, toRaw } from "../reactivity";
 import { projectState } from "../store";
 import { adoptProjectConfig } from "../tabs/project-config";
 import type { Tab } from "../tabs/tab";
@@ -27,10 +28,11 @@ import {
   createCommandToolRegistry,
 } from "./ai-command-tools";
 import { registerProjectTools } from "./ai-project-tools";
-import { registerImportTools, resetImportGuard } from "./ai-import-tools";
+import { registerImportTools } from "./ai-import-tools";
 import { createGatedToolRegistry } from "./gated-registry";
 import type { ToolAvailability } from "./gated-registry";
 import { adoptProject } from "./project-adoption";
+import { resetAiWrites } from "./ai-writes";
 import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
 import { AI_TOOL_TIERS, buildSystemPrompt, toolActive } from "./ai-system-prompt";
@@ -43,10 +45,12 @@ import { validateDoc } from "./jx-validate";
 import { reloadFileInTab } from "../files/files";
 import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
 import * as sessionStore from "./ai-session-store";
+import { backfillToolResults, stripToolResults } from "./tool-outcomes";
 
 /**
- * Project root scoping the session store (ADR §11.5 / §14.2 — conversations don't bleed across
- * projects). Falls back to a shared unscoped store when no project is open.
+ * Project root scoping the session store, so conversations don't bleed across projects (the history
+ * section of docs/studio/ai/chat.md). Falls back to a shared unscoped store when no project is
+ * open.
  *
  * @returns {string}
  */
@@ -73,6 +77,9 @@ export function createDocumentAssistant() {
 
   /** The persisted session backing the live chat; null = fresh unsaved chat. */
   let sessionId: string | null = null;
+  /* What the conversation's tools remember across its turns (an import already ran): every call's
+     `ctx.session`. New Chat starts over; a new session id keeps what the conversation knew. */
+  let sessionFacts = createSessionFacts();
 
   const getProjectStyle = () =>
     (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
@@ -88,7 +95,10 @@ export function createDocumentAssistant() {
 
   const innerRegistry = createToolRegistry();
   // Ungated: a question is not a function of what happens to be open.
-  registerAskTool(innerRegistry);
+  /* A question suspends the turn on the author, for as long as they like, and the conversation is
+     otherwise saved only when a turn starts and ends. Saving here is what lets a reload find the
+     question to restore as open rather than losing the whole unfinished turn. */
+  registerAskTool(innerRegistry, { onPending: () => persistChat() });
   registerAiTools(innerRegistry, {
     getTab: () => activeTab.value,
     saveFile: async (relPath: string, content: string) => {
@@ -222,6 +232,19 @@ export function createDocumentAssistant() {
 
   let controller: AbortController | null = null;
 
+  /**
+   * Whether a turn is in flight: true from the moment a send is accepted until its loop has ended.
+   *
+   * Not the chat's `status`, which belongs to the token stream: it reads idle while a round's tools
+   * run, while a question waits on the author and during an import. Guarding on it let a second
+   * send start a second turn beside the first, and let the composer offer Send in the middle of
+   * one. One window runs one turn, and this is the fact that says whether it is running.
+   */
+  const turnActive = shallowRef(false);
+
+  /** Settles when the turn in flight has ended, finally included; already settled when none is. */
+  let turnEnded: Promise<void> = Promise.resolve();
+
   function buildPrompt() {
     const tab = activeTab.value;
     const inventory = projectState
@@ -264,7 +287,7 @@ export function createDocumentAssistant() {
   }
 
   async function sendMessage(text: string) {
-    if (!text.trim() || chatState.status === "streaming") {
+    if (!text.trim() || turnActive.value || chatState.status === "streaming") {
       return;
     }
 
@@ -290,14 +313,25 @@ export function createDocumentAssistant() {
     // Persist after trimming so the saved history reflects what's actually sent.
     persistChat();
 
+    /* Stop is armed before the send's first wait. The turn's signal used to be created after
+       `await plat.aiChatUrl()`, which on desktop is an IPC round trip while the chat already reads
+       as streaming: a Stop pressed in that window found no controller, so the turn went on to
+       stream and run its tools, into a transcript the Stop had already cleared. The URL is now
+       resolved inside the first request, on the armed signal. */
+    controller = new AbortController();
+    const { signal } = controller;
+    turnActive.value = true;
+    let settleTurnEnded!: () => void;
+    turnEnded = new Promise<void>((settle) => {
+      settleTurnEnded = settle;
+    });
     try {
       const plat = getPlatform();
-      const chatUrl = await Promise.resolve(plat.aiChatUrl());
       // Re-read the persisted model each send: the session is constructed once at module load
       // (before the user sets a key/model), so the picker's choice must be picked up here.
       chatState.setModel(preferredModel());
       const streamingClient = createProxyStreamingClient({
-        chatUrl,
+        chatUrl: () => plat.aiChatUrl(),
         model: chatState.model,
         // Sent as X-Api-Key; the proxy falls back to the server's OPENAI_API_KEY when empty.
         apiKey: getOpenAiKey() || undefined,
@@ -305,29 +339,52 @@ export function createDocumentAssistant() {
         baseUrl: getBaseUrl() || undefined,
       });
 
-      controller = new AbortController();
+      if (sessionFacts.sessionId !== sessionId) {
+        sessionFacts = createSessionFacts(sessionId, sessionFacts.toJSON());
+      }
       await runAgentLoop({
         chatState,
         streamingClient,
         toolRegistry,
         systemPrompt: buildPrompt(),
-        signal: controller.signal,
+        signal,
+        session: sessionFacts,
         getTab: () => activeTab.value,
       });
     } catch (error) {
       /*
-       * Synchronous failure (e.g. platform not registered, network unreachable before the
-       * stream starts). Set the error so the panel can display it.
+       * A failure outside the stream's own error frames: the platform not registered, or its chat
+       * URL lookup rejecting inside the first request (a lookup that fails after a Stop ends the
+       * stream as cancelled instead). Set the error so the panel can display it.
        */
       chatState.setError(error instanceof Error ? error.message : String(error));
     } finally {
       controller = null;
+      turnActive.value = false;
       // Persist again once the stream settled so the completed reply (or the state
       // After an error/abort cleanup) survives a reload without another send.
       persistChat();
+      settleTurnEnded();
     }
   }
 
+  /** Whether a turn is in flight, tools and questions included. Reactive: read it in an effect. */
+  function isTurnActive(): boolean {
+    return turnActive.value;
+  }
+
+  /**
+   * Resolves once the turn in flight, if any, has ended.
+   *
+   * Stop, New Chat and Open Session end a turn but cannot finish it: they abort its signal, and the
+   * loop unwinds afterwards, at least a microtask later and as late as the call it was running
+   * allows. Until then the window still holds that turn, so a send made in the meantime is refused.
+   * A caller that means to start the next turn waits here first.
+   */
+  function whenTurnEnds(): Promise<void> {
+    return turnEnded;
+  }
+
   function stop() {
     controller?.abort();
     /* The abort settles an outstanding question through the turn signal, but only when the turn
@@ -342,7 +399,11 @@ export function createDocumentAssistant() {
     stop();
     resetAsk();
     resetImportRuns();
-    resetImportGuard();
+    /* The record of what each turn changed is drawn under that turn's message; with the messages
+       gone there is nothing to draw it under, and a Restore offered from it would undo whatever
+       document is active now (ai.md §3.2). A stopped turn still unwinding files under no message. */
+    resetAiWrites();
+    sessionFacts = createSessionFacts();
     chatState.clearChat();
     sessionId = null;
     sessionStore.setActiveSession(projectRoot(), null);
@@ -395,12 +456,18 @@ export function createDocumentAssistant() {
     const msgs = chatState.messages.filter(
       (m) => m.role !== "assistant" || m.content || (m.toolCalls?.length ?? 0) > 0,
     );
-    sessionStore.saveSession(projectRoot(), sessionId, msgs);
+    /* Without each call's `result`: the tool message that answers it is the outcome's one copy,
+       and a restore reads it back from there (services/tool-outcomes.ts). */
+    sessionStore.saveSession(projectRoot(), sessionId, stripToolResults(msgs));
   }
 
-  /** Push persisted messages into chat state, synthesizing ids where missing. */
+  /**
+   * Push persisted messages into chat state, synthesizing ids where missing, with each tool call's
+   * outcome backfilled from the tool message that answered it — so a restored chip shows how its
+   * call ended, and an answered question shows its answer.
+   */
   function pushRestoredMessages(msgs: sessionStore.PersistedMessage[]) {
-    for (const m of msgs) {
+    for (const m of backfillToolResults(msgs)) {
       chatState.messages.push({
         ...m,
         id: m.id || `restored_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
@@ -428,7 +495,9 @@ export function createDocumentAssistant() {
 
   return {
     chatState,
+    isTurnActive,
     sendMessage,
+    whenTurnEnds,
     stop,
     newChat,
     listSessions,

package/src/services/gated-registry.ts

@@ -13,7 +13,7 @@
  * @license MIT
  */
 
-import type { ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+import type { ToolContext, ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
 
 export interface ToolAvailability {
   /** Whether the tool is currently advertised/executable. */
@@ -58,7 +58,7 @@ export function createGatedToolRegistry(
     validate(toolName: string, args: object) {
       return inner.validate(toolName, args);
     },
-    async execute(toolName: string, args: object) {
+    async execute(toolName: string, args: object, ctx?: ToolContext) {
       if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
         const gate = availability.get(toolName);
         return {
@@ -66,7 +66,8 @@ export function createGatedToolRegistry(
           error: `Tool "${toolName}" is not available right now — it requires ${gate?.requires ?? "a different studio state"}.`,
         };
       }
-      return inner.execute(toolName, args);
+      // The call's context reaches the tool unchanged: its signal, id, ledger and session.
+      return inner.execute(toolName, args, ctx);
     },
   };
 }