@jxsuite/studio 5.5.0 → 5.7.0

package/src/publish/pages-service.ts

@@ -1,11 +1,10 @@
 /// <reference lib="dom" />
 /**
- * Pages-service — Cloudflare Pages publish domain logic over the PAL's
- * `cfApi` passthrough. Works identically on every platform that provides it:
- * the dev server / desktop (user API token via cf-settings → /__studio/cf/proxy)
- * and the cloud platform (hosted OAuth). Publish state is written to
- * project.json `build.deploy` — it travels with the repo, so any Studio can
- * tell whether the publish workflow already exists.
+ * Pages-service — Cloudflare Pages publish domain logic over the PAL's `cfApi` passthrough. Works
+ * identically on every platform that provides it: the dev server / desktop (user API token via
+ * cf-settings → /__studio/cf/proxy) and the cloud platform (hosted OAuth). Publish state is written
+ * to project.json `build.deploy` — it travels with the repo, so any Studio can tell whether the
+ * publish workflow already exists.
  *
  * @license MIT
  */
@@ -13,6 +12,7 @@
 import { updateWranglerConfig } from "@jxsuite/create/scaffold";
 import type { DeployConfig, ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
+import { actIfRequired } from "../account/action-flow";
 import { updateSiteConfig } from "../site-context";
 
 export interface CfAccount {
@@ -52,12 +52,22 @@ export function platformSupportsPublish(): boolean {
   }
 }
 
+/**
+ * One Cloudflare call. A refusal that offers an action (desktop.md §10.4) is offered here, once for
+ * every publish step, and still thrown: the step that asked failed, and its caller reports that in
+ * its own words while the offer says how to fix it.
+ */
 async function cfApi<T>(path: string, init?: { method?: string; body?: unknown }): Promise<T> {
   const api = getPlatform().cfApi;
   if (!api) {
     throw new Error("This platform cannot reach the Cloudflare API");
   }
-  return (await api(path, init)) as T;
+  try {
+    return (await api(path, init)) as T;
+  } catch (error) {
+    void actIfRequired(error);
+    throw error;
+  }
 }
 
 export async function listAccounts(): Promise<CfAccount[]> {

package/src/services/ai-models.ts

@@ -2,17 +2,17 @@
 /**
  * Ai-models.js — available-model listing from the studio AI proxy.
  *
- * Fetches the proxy's /models endpoint (the chat endpoint's sibling), forwarding the
- * stored API key as X-Api-Key and the endpoint override as X-Api-Base-URL so the proxy
- * lists models from the user's chosen provider. Shared by the credentials form and the
- * chat composer's model picker; results are cached module-wide until invalidated (e.g.
- * after credentials change).
+ * Fetches the proxy's /models endpoint (the chat endpoint's sibling), forwarding the stored API key
+ * as X-Api-Key and the endpoint override as X-Api-Base-URL so the proxy lists models from the
+ * user's chosen provider. Shared by the credentials form and the chat composer's model picker;
+ * results are cached module-wide until invalidated (e.g. after credentials change).
  *
  * @license MIT
  */
 
-import type { AiModelsResponse } from "@jxsuite/protocol";
+import type { AiModelsResponse, OfferedAction } from "@jxsuite/protocol";
 import { getPlatform } from "../platform";
+import { offeredActions } from "../platform-errors";
 import { getBaseUrl, getOpenAiKey, hasOpenAiKey, storedModel } from "./ai-settings";
 import { SETTINGS } from "./settings/definitions";
 import { onSettingsChanged } from "./settings/kernel";
@@ -76,6 +76,14 @@ let proxyManaged = false;
 let proxyDefaultModel = "";
 let proxyCode: AiModelsResponse["code"];
 let proxyModelsError = "";
+/** What an `action_required` probe offered; null for every other answer. */
+let proxyAction: ProxyActionOffer | null = null;
+
+/** What a managed backend says the assistant needs first, in the backend's own words. */
+export interface ProxyActionOffer {
+  detail?: string;
+  actions: OfferedAction[];
+}
 
 /**
  * One-shot capability probe shared by every credentials gate, plus the hosts to repaint when it
@@ -118,6 +126,7 @@ export function resetModelCache() {
   proxyDefaultModel = "";
   proxyCode = undefined;
   proxyModelsError = "";
+  proxyAction = null;
   /* The probe's result IS the flags above. Clearing them while keeping the settled promise
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
@@ -278,6 +287,14 @@ export function proxyModelsErrorMessage(): string {
   return proxyModelsError;
 }
 
+/**
+ * The offer the last probe carried — set only when the backend answered `action_required` (ai.md
+ * §2.1), and null for every other answer, so no gate can offer an action the backend did not name.
+ */
+export function proxyActionOffer(): ProxyActionOffer | null {
+  return proxyAction;
+}
+
 /** The proxy's preferred model id ("" when it does not declare one). */
 export function getProxyDefaultModel(): string {
   return proxyDefaultModel;
@@ -369,6 +386,13 @@ export async function fetchAvailableModels(
   proxyDefaultModel = data.defaultModel ?? "";
   proxyCode = data.code;
   proxyModelsError = data.upstreamError !== undefined ? (data.upstreamMessage ?? "") : "";
+  proxyAction =
+    data.code === "action_required"
+      ? {
+          actions: offeredActions(data.actions),
+          ...(typeof data.detail === "string" && data.detail ? { detail: data.detail } : {}),
+        }
+      : null;
   /* Capabilities are kept, not dropped. The backend has reported `toolSupport` all along and the
      ingest mapped `{id, name}` only, so a Workers AI model that cannot call tools looked exactly
      like one that can — the agent loop ran, called nothing, and answered as if that were normal.

package/src/services/ai-system-prompt.ts

@@ -1,8 +1,8 @@
 /**
  * Ai-system-prompt.js — Dynamic system prompt builder for the Jx AI assistant
  *
- * Constructs the system prompt based on the current project context, open document,
- * and available components. The quality of AI output depends critically on this file.
+ * Constructs the system prompt based on the current project context, open document, and available
+ * components. The quality of AI output depends critically on this file.
  *
  * @license MIT
  */
@@ -656,6 +656,75 @@ When asked to build a site with multiple pages:
 
 // ─── System prompt builder ───────────────────────────────────────────────────
 
+const ROLE = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
+
+/**
+ * What to do when a tool call fails. Static: it names tools and validation messages, never the
+ * state, so it belongs to the cacheable prefix rather than after the dynamic sections.
+ */
+const ERROR_RECOVERY = `## Error Recovery
+
+If a tool call fails (returns { success: false }):
+1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
+2. Each error points to a specific path in the document and a specific rule violation.
+3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
+4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
+5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
+
+### Common validation errors and their fixes:
+
+| Error pattern | What happened | How to fix |
+|---|---|---|
+| "must NOT have additional property" in style | You used a non-camelCase CSS property (e.g. "background-color") or put an HTML attribute directly on the element. | Use camelCase: "backgroundColor". Put aria-*, data-*, role, and other non-IDL attributes inside the "attributes" object: { "attributes": { "aria-label": "..." } } |
+| "must match pattern" on tagName | A custom element tag name doesn't contain a hyphen. | Add a hyphen: "newsletter-form" not "newsletter". Standard HTML elements use their exact name ("div", "p", "input"). |
+| "must be string" | A value is an unquoted number, boolean, or bare word. | Wrap the value in quotes: "10px" not 10px. All CSS values and text must be strings. |
+| "must be number" / "must be integer" | A numeric field (like index, tabIndex) is wrapped in quotes. | Remove the quotes: use 0 not "0". |
+| "must have required property" | A required field is missing from the node. | Add the missing property. Every element must have "tagName". |
+| "must be object" | A field that expects an object (like style or attributes) received a string or other type. | Use {} not a string. |
+| "No node exists at path" | The path you provided doesn't point to an existing node. | Call read_document first to see the current structure and valid paths, then use the correct path. |
+
+### If you keep getting errors:
+- Call read_document again — the document may have changed since you last read it.
+- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
+- If the error message points to a different path than you expected, the node might have moved due to previous edits.`;
+
+/** What every section of the prompt is joined with. */
+const SECTION_SEPARATOR = "\n\n---\n\n";
+
+/**
+ * The part of every system prompt that does not depend on the state, byte for byte: the role, the
+ * Jx reference sections, and the error-recovery guidance, each followed by the section separator.
+ *
+ * It exists for providers' prompt caches. A cache matches on a PREFIX of the request, and the
+ * system prompt is the request's first message, so the reference material (most of the prompt's
+ * tokens) only hits when nothing that changes between rounds comes before it. The prompt used to
+ * open with the role, the workflow for the current state and its tool list, so opening a document
+ * or registering one more command tool moved the first changed byte to the second paragraph and
+ * every request after it paid for the whole reference again. Everything dynamic — the mode, the
+ * tool list, the document, project and file summaries — now follows this prefix, and the closing
+ * instructions stay last. {@link buildSystemPrompt} always starts with it, and its tests hold that
+ * for every combination of the state flags.
+ */
+export const SYSTEM_PROMPT_STATIC_PREFIX =
+  [
+    // 1. Role
+    ROLE,
+    // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
+    JX_SCHEMA_REFERENCE,
+    // 2a. State shape decision tree
+    STATE_SHAPE_DECISION_TREE,
+    // 2b. Real-world patterns
+    REAL_WORLD_PATTERNS,
+    // 2c. Design principles — spacing, type, color, layout, restraint
+    DESIGN_PRINCIPLES,
+    // 2d. Control flow & reactivity — signals, list rendering ($map), conditionals ($switch)
+    CONTROL_FLOW_PATTERNS,
+    // 2e. Multi-page site building — layouts, file-based routing, navigation
+    MULTI_PAGE_PATTERNS,
+    // 3. Error recovery guidance
+    ERROR_RECOVERY,
+  ].join(SECTION_SEPARATOR) + SECTION_SEPARATOR;
+
 /**
  * Build a dynamic system prompt for the AI assistant.
  *
@@ -681,7 +750,7 @@ export function buildSystemPrompt({
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
 
-  // 1. Role, state-appropriate workflow, and the tool list for the current state.
+  // The state-appropriate workflow and the tool list for the current state.
   // The list the model is TOLD about and the list the gate will honour are the same filter, so a
   // Refusal is never a surprise to it. The command-projected tools arrive already filtered by
   // Their records' own gates, for the same reason — one function answers both the prompt and the
@@ -695,8 +764,6 @@ export function buildSystemPrompt({
     .map((blurb) => `- ${blurb}`)
     .join("\n");
 
-  const role = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
-
   let workflow: string;
   if (!hasProject && !hasDocument) {
     workflow = `No project is open yet. Your first job is to bootstrap one:
@@ -734,23 +801,10 @@ ${ASKING_THE_USER}
 
 Be concise. Don't explain what Jx is unless asked. Just build.`;
 
-  const sections = [`${role}\n\n${workflow}\n\n${closing}`];
-
-  // eslint-disable-next-line unicorn/no-immediate-mutation -- conditional section builder: later sections are pushed only when their context exists
-  sections.push(
-    // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
-    JX_SCHEMA_REFERENCE,
-    // 3. State shape decision tree
-    STATE_SHAPE_DECISION_TREE,
-    // 4. Real-world patterns
-    REAL_WORLD_PATTERNS,
-    // 4a. Design principles — spacing, type, color, layout, restraint
-    DESIGN_PRINCIPLES,
-    // 4b. Control flow & reactivity — signals, list rendering ($map), conditionals ($switch)
-    CONTROL_FLOW_PATTERNS,
-    // 4c. Multi-page site building — layouts, file-based routing, navigation
-    MULTI_PAGE_PATTERNS,
-  );
+  /* 4. The mode. Everything from here on is a function of what is open right now, so it all follows
+     SYSTEM_PROMPT_STATIC_PREFIX: a provider's prompt cache matches on a prefix, and the first byte
+     that differs between two requests ends the match. */
+  const sections = [`## Current Mode\n\n${workflow}`];
 
   // 5. Current document context
   if (document) {
@@ -758,7 +812,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     sections.push(`## Current Document\n\n${summary}`);
   }
 
-  // 6. Project context
+  // 5a. Project context
   if (hasProject && (projectConfig || components || projectRoot)) {
     const projectSummary = buildProjectSummary({
       components,
@@ -771,7 +825,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     }
   }
 
-  // 6a. File inventory — a compact map of the project for cross-file work
+  // 5b. File inventory — a compact map of the project for cross-file work
   if (hasProject && fileInventory && fileInventory.length > 0) {
     const capped = fileInventory.slice(0, FILE_INVENTORY_CAP);
     const more =
@@ -781,34 +835,10 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     sections.push(`## Project Files\n\n${capped.join("\n")}${more}`);
   }
 
-  // 7. Error recovery guidance
-  sections.push(`## Error Recovery
-
-If a tool call fails (returns { success: false }):
-1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
-2. Each error points to a specific path in the document and a specific rule violation.
-3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
-4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
-5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
-
-### Common validation errors and their fixes:
-
-| Error pattern | What happened | How to fix |
-|---|---|---|
-| "must NOT have additional property" in style | You used a non-camelCase CSS property (e.g. "background-color") or put an HTML attribute directly on the element. | Use camelCase: "backgroundColor". Put aria-*, data-*, role, and other non-IDL attributes inside the "attributes" object: { "attributes": { "aria-label": "..." } } |
-| "must match pattern" on tagName | A custom element tag name doesn't contain a hyphen. | Add a hyphen: "newsletter-form" not "newsletter". Standard HTML elements use their exact name ("div", "p", "input"). |
-| "must be string" | A value is an unquoted number, boolean, or bare word. | Wrap the value in quotes: "10px" not 10px. All CSS values and text must be strings. |
-| "must be number" / "must be integer" | A numeric field (like index, tabIndex) is wrapped in quotes. | Remove the quotes: use 0 not "0". |
-| "must have required property" | A required field is missing from the node. | Add the missing property. Every element must have "tagName". |
-| "must be object" | A field that expects an object (like style or attributes) received a string or other type. | Use {} not a string. |
-| "No node exists at path" | The path you provided doesn't point to an existing node. | Call read_document first to see the current structure and valid paths, then use the correct path. |
-
-### If you keep getting errors:
-- Call read_document again — the document may have changed since you last read it.
-- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
-- If the error message points to a different path than you expected, the node might have moved due to previous edits.`);
+  // 6. Closing — last, where a long prompt's final instructions carry the most weight.
+  sections.push(closing);
 
-  return sections.join("\n\n---\n\n");
+  return SYSTEM_PROMPT_STATIC_PREFIX + sections.join(SECTION_SEPARATOR);
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────

package/src/services/context-manager.ts

@@ -1,17 +1,23 @@
 /**
  * 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 (specs/ai.md §2 and §2.1).
+ * Estimates token usage and trims conversation history before each send to keep the 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
- * are replaced with a single summary note so the model knows history was truncated.
+ * 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 are replaced with
+ * a single summary note so the model knows history was truncated.
  *
  * @license MIT
  */
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
+import {
+  SEAL_RELOADED,
+  repairToolPairs,
+  toChatMessages,
+  toLiveMessages,
+} from "@jxsuite/ai/messages";
 import { modelContextWindow } from "./ai-models";
 
 /** Shape of a single entry returned by `chatState.toMessagesArray()`. */
@@ -273,91 +279,56 @@ export function trimContext(
 // ─── Orphaned tool calls ────────────────────────────────────────────────────
 
 /**
- * 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).
+ * What a seal says for a call that was not cut off, so a reader and the model see the same reason.
+ * Exported so a restore can name the outcome of an ordinary call nothing answered
+ * (services/tool-outcomes.ts); `isSealContent` tells any seal from a reply.
  */
-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.",
-});
+export const UNANSWERED_TOOL_RESULT = JSON.stringify({ success: false, error: SEAL_RELOADED });
 
 /**
  * Repair tool-call pairing in place, and report how many messages it touched.
  *
  * `toMessagesArray()` serializes the array verbatim: an assistant message with `tool_calls` becomes
  * a `tool_calls` request, and a `tool` message becomes a reply carrying `tool_call_id`. Providers
- * require the two to come in pairs, and **three ordinary things break the pairing**:
+ * require each reply directly after the request that made the call, and **four ordinary things
+ * break that**:
  *
  * 1. `saveSession` persists `msgs.slice(-MAX_PERSIST_MESSAGES)` and `restoreChat` pushes the result
  *    back, so a session longer than the cap can be restored starting mid-pair.
  * 2. {@link trimContext} splices from the front for the token budget, with no more regard for pairs.
  * 3. A turn that stopped while a tool was still running — which `ask_user` makes routine, because its
  *    tool is _designed_ to be outstanding — leaves a request with no reply.
+ * 4. A transcript written before one window ran one turn can hold a reply after a later message.
  *
  * Each of those produced a 400 on the NEXT send, from a conversation the user could see was fine.
- * So the repair belongs on the send path, after trimming, rather than at any one of the three
- * sites: a request with no reply gets a synthesized failure (keeping the assistant's text, which
- * dropping the message would lose), and a reply with no request is dropped.
+ * So the repair belongs on the send path, after trimming, rather than at any one of the sites. It
+ * is `repairToolPairs` (`@jxsuite/ai/messages`, specs/ai.md §3.4), the same repair the turn engine
+ * runs at turn start, applied to the chat store: pairing is per request rather than by call id
+ * across the transcript, because a provider may reuse `call_0` every round; a reply away from its
+ * request is moved back beside it; a request with no reply is sealed with a synthesized failure
+ * (keeping the assistant's text, which dropping the message would lose) that says whether the call
+ * was cut off mid-arguments; and a reply with no request is dropped.
+ *
+ * The store is rebuilt with one `splice`, and only when something changed. Every message the repair
+ * kept is the store's own object, which the streaming turn and the panel hold by identity, and the
+ * array itself is never reassigned.
  *
  * @param {ReturnType<typeof createChatState>} chatState
- * @returns {{ sealed: number; dropped: number }}
+ * @returns {{ dropped: number; moved: number; sealed: number }}
  */
 export function pruneOrphanToolMessages(chatState: ReturnType<typeof createChatState>): {
-  sealed: number;
   dropped: number;
+  moved: number;
+  sealed: number;
 } {
-  const { messages } = chatState;
-
-  const requested = new Set<string>();
-  const answered = new Set<string>();
-  for (const msg of messages) {
-    if (msg.role === "assistant" && msg.toolCalls) {
-      for (const call of msg.toolCalls) {
-        requested.add(call.id);
-      }
-    } else if (msg.role === "tool" && msg.toolCallId) {
-      answered.add(msg.toolCallId);
-    }
+  const live = chatState.messages;
+  const neutral = toChatMessages(live);
+  const { messages, sealed, dropped, moved } = repairToolPairs(neutral);
+  if (sealed.length + dropped.length + moved.length === 0) {
+    return { dropped: 0, moved: 0, sealed: 0 };
   }
-
-  // Replies with no request, and replies with no id at all — neither can be serialized into a
-  // Well-formed pair, and a reply is the half that carries no author text worth keeping.
-  let dropped = 0;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i]!;
-    if (msg.role === "tool" && (!msg.toolCallId || !requested.has(msg.toolCallId))) {
-      messages.splice(i, 1);
-      dropped += 1;
-    }
-  }
-
-  /* Requests with no reply. Walk backwards so each insertion is past the indices still to visit,
-     and seal immediately after the requesting message — `toMessagesArray` emits in array order, so
-     that is the only position the pair is adjacent in. */
-  let sealed = 0;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i]!;
-    if (msg.role !== "assistant" || !msg.toolCalls) {
-      continue;
-    }
-    const missing = msg.toolCalls.filter((call) => !answered.has(call.id));
-    if (missing.length === 0) {
-      continue;
-    }
-    messages.splice(
-      i + 1,
-      0,
-      ...missing.map((call, n) => ({
-        content: UNANSWERED_TOOL_RESULT,
-        id: `sealed_${call.id}_${n}`,
-        role: "tool" as const,
-        timestamp: msg.timestamp,
-        toolCallId: call.id,
-      })),
-    );
-    sealed += missing.length;
-  }
-
-  return { dropped, sealed };
+  const liveOf = new Map(neutral.map((message, index) => [message, live[index]!]));
+  const next = messages.map((message) => liveOf.get(message) ?? toLiveMessages([message])[0]!);
+  live.splice(0, live.length, ...next);
+  return { dropped: dropped.length, moved: moved.length, sealed: sealed.length };
 }

package/src/services/document-assistant.ts

@@ -10,6 +10,7 @@
  */
 
 import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
+import { createTurnLock } from "@jxsuite/ai/harness";
 import { createSessionFacts } from "@jxsuite/ai/tools";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
@@ -233,14 +234,17 @@ 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.
+   * One window runs one turn. The lock is what decides it: a send is accepted only when it can take
+   * the lock, and holds it 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.
+   * one. `turnActive` is the lock's reactive reading, for the panel's effects.
    */
+  const turnLock = createTurnLock();
   const turnActive = shallowRef(false);
+  let turnCount = 0;
 
   /** Settles when the turn in flight has ended, finally included; already settled when none is. */
   let turnEnded: Promise<void> = Promise.resolve();
@@ -287,7 +291,7 @@ export function createDocumentAssistant() {
   }
 
   async function sendMessage(text: string) {
-    if (!text.trim() || turnActive.value || chatState.status === "streaming") {
+    if (!text.trim() || turnLock.active !== null || chatState.status === "streaming") {
       return;
     }
 
@@ -320,6 +324,10 @@ export function createDocumentAssistant() {
        resolved inside the first request, on the armed signal. */
     controller = new AbortController();
     const { signal } = controller;
+    /* Taken here rather than at the guard so nothing above can leave it held. Everything since the
+       guard is synchronous, so no other send can have taken it in between: it is free. */
+    turnCount += 1;
+    const releaseTurn = turnLock.acquire(`send:${turnCount}`)!;
     turnActive.value = true;
     let settleTurnEnded!: () => void;
     turnEnded = new Promise<void>((settle) => {
@@ -363,6 +371,7 @@ export function createDocumentAssistant() {
       chatState.setError(error instanceof Error ? error.message : String(error));
     } finally {
       controller = null;
+      releaseTurn();
       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.

package/src/services/harness/chat-reducer.ts

@@ -0,0 +1,115 @@
+/**
+ * Chat-reducer.ts — a turn's events, applied to Studio's chat store.
+ *
+ * The chat store is Studio's transcript of record: the panel renders it and the session store saves
+ * it. The turn engine (`@jxsuite/ai/harness`) reports what a turn does as events, and this is the
+ * one place they become chat-store calls, in the order the agent loop always made them (specs/ai.md
+ * §3.8): the recorded agent traces hold the two to the same sequence, call for call.
+ *
+ * @license MIT
+ */
+
+import type { createChatState } from "@jxsuite/ai/chat-state";
+import type { HarnessEvent, TurnOutcome } from "@jxsuite/ai/harness";
+import type { ImportProgressEvent } from "../../types";
+import { recordImportProgress } from "../import-run";
+
+type ChatStore = ReturnType<typeof createChatState>;
+
+/** How a turn's end reads in the transcript: the cap message, an error row, or nothing more. */
+function applyOutcome(chat: ChatStore, outcome: TurnOutcome): void {
+  switch (outcome.kind) {
+    case "cap_partial": {
+      // A partial success is said as the assistant, not as a failure (specs/ai.md §3.2).
+      chat.beginAssistantTurn();
+      chat.appendDelta(outcome.cap?.text ?? "");
+      chat.finishStream("length");
+      break;
+    }
+    case "cap_failed":
+    case "empty":
+    case "error": {
+      /* `setError` alone, never after `finishStream`: it removes the round's partial message, and
+         only while that message is still the streaming one. */
+      chat.setError(outcome.error?.message ?? "");
+      break;
+    }
+    default: {
+      break;
+    }
+  }
+}
+
+/**
+ * Apply one turn event to the chat store.
+ *
+ * Round one answers into the placeholder `sendMessage` already pushed, so only a later round opens
+ * a message. A round that failed, or a turn that drew nothing, is never finished: its error row
+ * removes the partial. `turn_start`, `tool_start` and `write` change nothing here; the ledger
+ * records writes itself. Nor does `transcript_repaired`: the send path ran the same repair on the
+ * chat store before the turn began (`pruneOrphanToolMessages`), so the store is already the history
+ * the engine repaired.
+ *
+ * @param {ChatStore} chat
+ * @param {HarnessEvent} event
+ */
+export function applyHarnessEvent(chat: ChatStore, event: HarnessEvent): void {
+  switch (event.type) {
+    case "round_start": {
+      if (event.round > 1) {
+        chat.beginAssistantTurn();
+      }
+      break;
+    }
+    case "text": {
+      chat.appendDelta(event.text);
+      break;
+    }
+    case "reasoning": {
+      /* Kept on the turn, not shown as answer text: the next round has to replay it
+         (specs/ai.md §2.2). */
+      chat.appendReasoning(event.text);
+      break;
+    }
+    case "tool_call_start": {
+      chat.appendToolCallStart(event.callId, event.name);
+      break;
+    }
+    case "tool_call_delta": {
+      chat.appendToolCallDelta(event.callId, event.args);
+      break;
+    }
+    case "tool_call_end": {
+      chat.appendToolCallEnd(event.callId);
+      break;
+    }
+    case "usage": {
+      /* The provider's own count replaces the four-characters-per-token estimate; the prompt it
+         covered is recorded with it, because the next send rebuilds the prompt. */
+      chat.recordUsage(event.frame, { systemTokens: event.systemTokens });
+      break;
+    }
+    case "round_end": {
+      if (!event.dropped) {
+        chat.finishStream(event.stopReason);
+      }
+      break;
+    }
+    case "tool_progress": {
+      recordImportProgress(event.callId, event.progress as unknown as ImportProgressEvent);
+      break;
+    }
+    case "tool_result": {
+      chat.appendToolResult(event.callId, event.result);
+      chat.pushToolResultMessage(event.callId, JSON.stringify(event.result));
+      break;
+    }
+    case "turn_end": {
+      applyOutcome(chat, event.outcome);
+      break;
+    }
+    default: {
+      break;
+    }
+  }
+}