@jxsuite/studio 5.6.0 → 6.0.0

package/src/panels/pane-grid.ts

@@ -5,27 +5,28 @@
  * `workspace.panes` has been a real data model since the shell redesign's chrome phase: an ordered
  * list, a focused id, a split, an unsplit. Nothing drew it. `index.html` declared ONE each of
  * `#tab-strip`, `#jump-bar`, `#pane-chrome` and `#canvas-wrap` as flat siblings in `#app`'s grid —
- * four surfaces that belong to a PANE, laid out as rows and columns of the APPLICATION — so the
- * shell could model two panes and had somewhere to put exactly one. §18.3's stage handover was the
+ * surfaces that belong to a PANE, laid out as rows and columns of the APPLICATION — so the shell
+ * could model two panes and had somewhere to put exactly one. §18.3's stage handover was the
  * workaround: one stage, taken by whichever pane had focus, releasing the loser's artboards on the
  * way past. This module is what that scaffolding was standing in for, and the handover is deleted
  * with it.
  *
  * **The document owns the frame; this module owns the decisions.** `surfaces/pane-grid.json` is the
- * cells, the five boxes inside each one, the splitter between two of them and every rule that lays
+ * cells, the four boxes inside each one, the splitter between two of them and every rule that lays
  * them out; `surfaces/pane-grid.ts` is the mount. What is left here is the flow: which panes there
  * are, what a cell's stage is furnished with, in what ORDER a departing cell is taken apart, and
  * what the grid's own tracks are. Everything a cell CONTAINS still arrives through the module that
  * owns it — `canvas/canvas-render.ts` is the render root of the stage and this document puts
- * nothing inside it, `panels/jump-bar.ts` and `panels/pane-context.ts` are handed the jump and
- * chrome boxes, `panels/tab-strip.ts` is handed the strip, and this module makes the fifth — the
- * right-edge drop zone — a pragmatic target itself.
+ * nothing inside it, `panels/pane-context.ts` is handed the chrome box, `panels/tab-strip.ts` is
+ * handed the strip, and this module makes the fourth — the right-edge drop zone — a pragmatic
+ * target itself. (The jump bar had a box here too, until it moved to the status bar: a pane's
+ * address is now the focused pane's breadcrumb trail along the foot of the window.)
  *
  * **Three properties survived the conversion, and each is structural rather than remembered:**
  *
  * 1. _A pane is complete before it is published._ The runtime builds a `$map` row inside its own
- *    effect scope and inserts it afterwards, so the five `cellPart` calls below — the surface
- *    record, the gestures, the two bars' mounts, the pane-focus listener, the drop zone's own
+ *    effect scope and inserts it afterwards, so the `cellPart` calls below — the surface record,
+ *    the gestures, the context bar's mount, the pane-focus listener, the drop zone's own
  *    registration — all happen while the cell is still detached. There is no frame in which a cell
  *    exists with no stage inside it.
  * 2. _A pane's node is never re-parented._ The repeater is keyed on the pane id and the runtime's
@@ -81,7 +82,6 @@ import { releaseCanvasHosts } from "../canvas/iframe-host";
 import { installStageGestures } from "../editor/shortcuts";
 import { scheduleCanvasRender } from "../canvas/canvas-render";
 import { paneRegion, paneStripRegion } from "../ui/regions";
-import { attachJumpBarHost } from "./jump-bar";
 import { attachPaneChromeHost } from "./pane-context";
 import { MAX_PANES, focusPane, workspace } from "../workspace/workspace";
 import { mountPaneGridSurface } from "../surfaces/pane-grid";
@@ -89,12 +89,11 @@ import type { EffectScope } from "@vue/reactivity";
 import type { CanvasSurface } from "../canvas/canvas-surface";
 import type { PaneCellPart, PaneGridRow, PaneGridSurface } from "../surfaces/pane-grid";
 
-/** One drawn pane: its root and the five surfaces inside it. */
+/** One drawn pane: its root and the four surfaces inside it. */
 export interface PaneCell {
   paneId: string;
   root: HTMLElement;
   strip: HTMLElement;
-  jump: HTMLElement;
   chrome: HTMLElement;
   stage: HTMLElement;
   dropZone: HTMLElement;
@@ -162,7 +161,6 @@ function cellState(paneId: string): CellState {
   const cell: CellState = {
     chrome: null as unknown as HTMLElement,
     dropZone: null as unknown as HTMLElement,
-    jump: null as unknown as HTMLElement,
     paneId,
     releaseDropZone: null,
     releaseGestures: null,
@@ -283,15 +281,15 @@ function attachDropZone(paneId: string, element: HTMLElement): () => void {
 }
 
 /**
- * One of a cell's six boxes has been created. Fill the record in, and wire what belongs to it.
+ * One of a cell's five boxes has been created. Fill the record in, and wire what belongs to it.
  *
- * The two bars are HANDED their host rather than resolving a region, the same way
- * `panels/frontmatter-panel.ts` is handed the stage. They cannot resolve one the way the tab strip
+ * The context bar is HANDED its host rather than resolving a region, the same way
+ * `panels/frontmatter-panel.ts` is handed the stage. It cannot resolve one the way the tab strip
  * does: the strip's host carries `pane.<id>/tabs` and nothing inside it re-stamps that id, while
- * the jump bar and the context bar both stamp `pane.<id>/jump` and `pane.<id>/context` on markup
- * they render INSIDE their two boxes — so a region on the wrapper as well would put the same id on
- * two nested elements, and `resolveRegion` takes the LAST match. Sixty shots crop
- * `pane.primary/context`; a second, larger element carrying it is a silently widened crop.
+ * the context bar stamps `pane.<id>/context` on markup it renders INSIDE its box — so a region on
+ * the wrapper as well would put the same id on two nested elements, and `resolveRegion` takes the
+ * LAST match. Sixty shots crop `pane.primary/context`; a second, larger element carrying it is a
+ * silently widened crop.
  */
 function cellPart(paneId: string, part: PaneCellPart, element: HTMLElement): void {
   const cell = cellState(paneId);
@@ -304,11 +302,6 @@ function cellPart(paneId: string, part: PaneCellPart, element: HTMLElement): voi
     cell.strip = element;
     return;
   }
-  if (part === "jump") {
-    cell.jump = element;
-    attachJumpBarHost(paneId, element);
-    return;
-  }
   if (part === "chrome") {
     cell.chrome = element;
     attachPaneChromeHost(paneId, element);
@@ -333,7 +326,7 @@ function cellPart(paneId: string, part: PaneCellPart, element: HTMLElement): voi
  *
  * The order is the document's own, and each step needs the one before it:
  *
- * - The two bars go first, each disposing a mount whose DOM is inside this cell — the runtime that
+ * - The context bar goes first, disposing a mount whose DOM is inside this cell — the runtime that
  *   owns it is about to be unreachable.
  * - `releaseCanvasHosts` goes before `disposePaneSurface` and while `stage` still CONTAINS its
  *   frames, which is the whole reason it can find them. A frame released later is noticed only by
@@ -345,7 +338,6 @@ function cellPart(paneId: string, part: PaneCellPart, element: HTMLElement): voi
 function disposeCell(cell: CellState): void {
   cell.releaseDropZone?.();
   cell.releaseDropZone = null;
-  attachJumpBarHost(cell.paneId, null);
   attachPaneChromeHost(cell.paneId, null);
   cell.releaseGestures?.();
   cell.releaseGestures = null;

package/src/panels/style-panel.ts

@@ -813,7 +813,7 @@ function buttonGroup(
     return {
       icon,
       row: rowKey,
-      selected: v === value,
+      checked: v === value ? ("true" as const) : ("false" as const),
       text: icon === "" ? v : "",
       title: v,
       value: v,
@@ -2112,7 +2112,7 @@ function rememberButtons(view: StylePanelView): void {
   for (const section of view.sections) {
     for (const row of section.rows) {
       if (row.widget === "buttons") {
-        _buttonValues.set(row.key, row.buttons.find((b) => b.selected)?.value ?? "");
+        _buttonValues.set(row.key, row.buttons.find((b) => b.checked === "true")?.value ?? "");
       }
     }
   }

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;
+    }
+  }
+}

package/src/services/harness/turn-hooks.ts

@@ -0,0 +1,50 @@
+/**
+ * Turn-hooks.ts — what Studio does between the turn engine's steps.
+ *
+ * @license MIT
+ */
+
+import type { TurnHooks } from "@jxsuite/ai/harness";
+import { ensureProxyProbe, resetModelCache } from "../ai-models";
+
+/** What Studio's hooks act on, injected so the hooks hold no state of their own. */
+export interface StudioTurnHookDeps {
+  /** Whether the conversation the turn answers has left the transcript (another chat was opened). */
+  superseded: () => boolean;
+  /** Called once a call settles into a transcript that replaced the turn's own. */
+  onSuperseded: () => void;
+  /** Re-anchor the undo batch on the document the tools now edit (specs/ai.md §3.3). */
+  reanchor: () => void;
+}
+
+/**
+ * Studio's turn hooks.
+ *
+ * - **After each call**, a turn whose conversation has been replaced stops there: its reply belongs
+ *   to a request that is no longer on screen, and writing it would land a stray `tool` message in
+ *   the other conversation. Otherwise the undo batch follows the document the tools moved to, which
+ *   a tool, project adoption or the author clicking another tab can each change.
+ * - **On a stream error**, a lapsed hosted grant (`cf_reconnect_required`) drops the model reading
+ *   and re-probes (specs/ai.md §2.1): the probe settles once at boot, so without this every gate
+ *   keeps offering an assistant that cannot answer, and the failed send is the only evidence.
+ *
+ * @param {StudioTurnHookDeps} deps
+ * @returns {TurnHooks}
+ */
+export function studioTurnHooks(deps: StudioTurnHookDeps): TurnHooks {
+  return {
+    afterTool() {
+      if (deps.superseded()) {
+        deps.onSuperseded();
+        return;
+      }
+      deps.reanchor();
+    },
+    onStreamError(error) {
+      if (error.code === "cf_reconnect_required") {
+        resetModelCache();
+        ensureProxyProbe();
+      }
+    },
+  };
+}