@jxsuite/studio 0.31.1 → 0.33.0

package/src/services/tool-executor.ts

@@ -0,0 +1,156 @@
+/**
+ * Tool-executor.js — Agentic loop driver for the document AI assistant
+ *
+ * Streams a chat round, executes any tool calls the model makes (via a ToolRegistry backed by
+ * `transactDoc()`), feeds the results back as `tool` messages, and re-streams — up to a capped
+ * number of rounds (spec §10.2, ADR docs/ai-assistant-decision.md §6a).
+ *
+ * @license MIT
+ */
+
+import type { createChatState } from "@jxsuite/ai/chat-state";
+import type { StreamingClient } from "@jxsuite/ai/streaming-client";
+import type { ToolRegistry } from "@jxsuite/ai/tools";
+
+import type { Tab } from "../tabs/tab";
+import { beginBatch, endBatch } from "../tabs/transact";
+
+const MAX_ROUNDS = 5;
+
+interface RunAgentLoopOptions {
+  chatState: ReturnType<typeof createChatState>;
+  streamingClient: StreamingClient;
+  toolRegistry: ToolRegistry;
+  systemPrompt: string;
+  signal?: AbortSignal;
+  getTab?: () => Tab | null;
+}
+
+/**
+ * Run one user turn through the agent loop: stream the model's response, execute any tool calls,
+ * and repeat until the model stops calling tools or the round cap is hit.
+ */
+export async function runAgentLoop({
+  chatState,
+  streamingClient,
+  toolRegistry,
+  systemPrompt,
+  signal,
+  getTab,
+}: RunAgentLoopOptions): Promise<void> {
+  const allErrors: string[] = [];
+  const appliedSummaries: string[] = [];
+
+  // Batch all tool-call mutations into a single undo step
+  if (getTab) {
+    beginBatch(getTab());
+  }
+
+  try {
+    for (let round = 1; round <= MAX_ROUNDS; round++) {
+      const messages = chatState.toMessagesArray();
+      const tools = toolRegistry.listForLLM();
+
+      const toolCalls = new Map<string, { name: string; arguments: string }>();
+      let stopReason = "stop";
+      let streamError = null;
+
+      for await (const event of streamingClient.streamChat(
+        messages,
+        tools,
+        systemPrompt,
+        signal as AbortSignal,
+      )) {
+        switch (event.type) {
+          case "delta": {
+            chatState.appendDelta(event.content);
+            break;
+          }
+          case "tool_call_start": {
+            chatState.appendToolCallStart(event.id, event.name);
+            toolCalls.set(event.id, { name: event.name, arguments: "" });
+            break;
+          }
+          case "tool_call_delta": {
+            chatState.appendToolCallDelta(event.id, event.args);
+            const tc = toolCalls.get(event.id);
+            if (tc) {
+              tc.arguments += event.args;
+            }
+            break;
+          }
+          case "tool_call_end": {
+            chatState.appendToolCallEnd(event.id);
+            break;
+          }
+          case "done": {
+            ({ stopReason } = event);
+            break;
+          }
+          case "error": {
+            streamError = event.message;
+            break;
+          }
+          default: {
+            break;
+          }
+        }
+      }
+
+      chatState.finishStream(stopReason);
+
+      if (streamError) {
+        chatState.setError(streamError);
+        return;
+      }
+
+      if (stopReason !== "tool_calls" || toolCalls.size === 0) {
+        return;
+      }
+
+      for (const [id, call] of toolCalls) {
+        let result;
+        try {
+          const args = call.arguments ? (JSON.parse(call.arguments) as object) : {};
+          result = await toolRegistry.execute(call.name, args);
+        } catch (error) {
+          result = {
+            success: false,
+            error: `Failed to parse arguments: ${(error as Error).message}`,
+          };
+        }
+        if (!result.success && result.error) {
+          allErrors.push(result.error);
+        }
+        if (result.success && result.summary) {
+          appliedSummaries.push(result.summary);
+        }
+        chatState.appendToolResult(id, result);
+        chatState.pushToolResultMessage(id, JSON.stringify(result));
+      }
+
+      if (round < MAX_ROUNDS) {
+        chatState.beginAssistantTurn();
+      }
+    }
+
+    /*
+     * Surface the actual errors so the user knows what went wrong, not just a generic
+     * "I couldn't do it" message.
+     */
+    const uniqueErrors = [...new Set(allErrors)];
+    const applied =
+      appliedSummaries.length > 0
+        ? `\n\nChanges applied so far:\n${appliedSummaries.map((s) => `- ${s}`).join("\n")}`
+        : "";
+    const errors =
+      uniqueErrors.length > 0
+        ? `\n\nErrors encountered:\n${uniqueErrors.map((e) => `- ${e}`).join("\n")}`
+        : "";
+    chatState.setError(
+      `I ran out of tool-call rounds (${MAX_ROUNDS}) before finishing.${applied}${errors}\n\nYou can continue by sending another message, or try a more specific request.`,
+    );
+  } finally {
+    endBatch();
+  }
+}

package/src/state.ts

@@ -73,6 +73,35 @@ export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
   return node;
 }
 
+/**
+ * Shallow-clone every node along `path` from root to target, leaving non-path subtrees as shared
+ * references. Returns the new root and the mutable target node at the end of the path.
+ *
+ * Used by mutation functions for structural-sharing history: the old root becomes an immutable
+ * snapshot (shared subtrees are never mutated), and the new root is the live document.
+ */
+export function cloneAlongPath(
+  doc: JxMutableNode,
+  path: JxPath,
+): { root: JxMutableNode; target: JxMutableNode } {
+  const root = Array.isArray(doc) ? [...doc] : { ...doc };
+  let node: Record<string | number, unknown> = root as Record<string | number, unknown>;
+
+  for (const key of path) {
+    const child = node[key];
+    if (child == null) {
+      return { root: root as JxMutableNode, target: node as JxMutableNode };
+    }
+    const cloned = Array.isArray(child)
+      ? [...(child as unknown[])]
+      : { ...(child as Record<string, unknown>) };
+    node[key] = cloned;
+    node = cloned as Record<string | number, unknown>;
+  }
+
+  return { root: root as JxMutableNode, target: node as JxMutableNode };
+}
+
 /**
  * The node's children when they are a static array (the edit-mode invariant); an empty array for
  * mapped-array or absent children.

package/src/studio.ts

@@ -106,7 +106,7 @@ import { initCssData } from "./panels/style-utils";
 import { updateForcedPseudoPreview } from "./panels/pseudo-preview";
 import { initPanelEvents } from "./panels/panel-events";
 import { initQuickSearch } from "./panels/quick-search";
-import { addRecentProject } from "./recent-projects";
+import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
 import { initWelcome } from "./panels/welcome-screen";
 import { openNewProjectModal } from "./new-project/new-project-modal";
 import type { DocumentStackEntry, GitDiffState } from "./types";
@@ -338,7 +338,7 @@ toolbarPanel.mount(toolbarEl, {
 });
 
 initLayers();
-initQuickSearch();
+initQuickSearch({ openRecentProject: (root: string) => openRecentProject(root) });
 
 tabStrip.mount(document.querySelector("#tab-strip") as HTMLElement);
 
@@ -662,6 +662,14 @@ if (_projectParam) {
   ensureFsSync();
 }
 
+// Hydrate the recent-projects list from the backend store (desktop/chromium), then refresh the
+// Toolbar dropdown + welcome screen, both of which read it synchronously.
+// oxlint-disable-next-line unicorn/prefer-top-level-await -- deliberate fire-and-forget: hydration must not block initial render
+void hydrateRecentProjects().then(() => {
+  toolbarPanel.render();
+  render();
+});
+
 // ─── Left panel: delegated to panels/left-panel.js ───────────────────────────
 
 function renderLeftPanel() {
@@ -748,6 +756,11 @@ async function openRecentProject(root: string) {
     ensureFsSync();
     void maybePromptJxsuiteUpdate(root);
   } catch (error) {
+    // The project likely moved or was deleted — drop the stale entry so it stops cluttering the
+    // List, and refresh the dropdown + welcome screen.
+    removeRecentProject(root);
+    toolbarPanel.render();
+    render();
     statusMessage(`Error: ${errorMessage(error)}`);
   }
 }

package/src/tabs/transact.ts

@@ -86,6 +86,12 @@ export type JxNodeValue =
  * "Array"`) cannot be index-mutated — fail loudly instead of corrupting.
  */
 function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
+  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
+  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
+  // Nothing renders. Callers must pass a node; fail loudly if they don't.
+  if (Array.isArray(node)) {
+    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
+  }
   if (!node.children) {
     node.children = [];
   }
@@ -154,7 +160,7 @@ export function transactDoc(
     }
   }
 
-  if (!skipHistory) {
+  if (!skipHistory && !_batchTab) {
     pushHistoryEntry(tab, raw, record, selectionBefore);
   }
 
@@ -351,6 +357,36 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
   }
 }
 
+// ─── Batch (group multiple mutations into one undo step) ────────────────────
+
+let _batchTab: Tab | null = null;
+
+export function beginBatch(tab: Tab | null) {
+  _batchTab = tab;
+}
+
+export function endBatch() {
+  if (_batchTab) {
+    const raw = toRaw(_batchTab.doc.document);
+    const snapshot = {
+      document: jsonClone(raw),
+      selection: _batchTab.session.selection ? [..._batchTab.session.selection] : null,
+    };
+    const truncated = _batchTab.history.snapshots.slice(0, _batchTab.history.index + 1);
+    truncated.push(snapshot);
+    if (truncated.length > HISTORY_LIMIT) {
+      truncated.shift();
+    }
+    _batchTab.history.snapshots = truncated;
+    _batchTab.history.index = truncated.length - 1;
+  }
+  _batchTab = null;
+}
+
+export function isBatching(): boolean {
+  return _batchTab !== null;
+}
+
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
 
 /** Restore a materialized snapshot state (full-render path). */

package/src/types.ts

@@ -214,12 +214,8 @@ export interface StudioPlatform {
     adapter?: string;
     directory: string;
   }) => Promise<{ root: string; config: ProjectConfig }>;
-  aiAuthStatus: () => Promise<{ authenticated: boolean; error?: string }>;
-  aiCreateSession: (opts: { message: string; systemPrompt?: string }) => Promise<{ id: string }>;
-  aiSendMessage: (id: string, message: string) => Promise<void>;
-  aiStreamUrl: (id: string) => string | Promise<string>;
-  aiStopSession: (id: string) => Promise<void>;
-  aiDeleteSession: (id: string) => Promise<void>;
+  /** Stack B AI assistant: URL of the OpenAI-compatible SSE chat proxy (`/__studio/ai/chat`). */
+  aiChatUrl: () => string | Promise<string>;
   // ─── Multi-window (desktop only; undefined on dev-server) ───────────────────
   /** Open a project in a new window, focusing an existing window if it is already open. */
   openProjectInNewWindow?: (root: string) => Promise<void>;
@@ -232,6 +228,22 @@ export interface StudioPlatform {
   setWindowProject?: (root: string) => Promise<{ deduped: boolean; config: ProjectConfig | null }>;
   /** The project root this window's backend is currently bound to. */
   getProjectRoot?: () => Promise<{ root: string | null }>;
+  // ─── Recent projects (backend-persisted; undefined on dev-server) ───────────
+  /**
+   * Read the user-level recent-projects list from a backend store shared across all
+   * projects/windows. Platforms without a native backend (dev server) omit it and the studio falls
+   * back to localStorage.
+   */
+  getRecentProjects?: () => Promise<RecentProjectEntry[]>;
+  /** Persist the full recent-projects list to the backend store. */
+  saveRecentProjects?: (projects: RecentProjectEntry[]) => Promise<void>;
+}
+
+/** A recently-opened project, keyed by its re-openable `root` (platform-specific). */
+export interface RecentProjectEntry {
+  name: string;
+  root: string;
+  timestamp: number;
 }
 
 // ─── Studio Types ───────────────────────────────────────────────────────────

package/src/ui/media-picker.ts

@@ -10,7 +10,7 @@ import { html, render as litRender, nothing } from "lit-html";
 import { live } from "lit-html/directives/live.js";
 import { ref } from "lit-html/directives/ref.js";
 import { getPlatform } from "../platform";
-import { debouncedStyleCommit } from "../store";
+import { debouncedStyleCommit, renderOnly } from "../store";
 import { getLayerSlot } from "./layers";
 
 // ─── Media file cache ────────────────────────────────────────────────────────
@@ -88,6 +88,10 @@ async function loadMediaCache() {
     m.path = m.path.replace(/^\/public\//, "/");
   }
   mediaCacheLoaded = true;
+  // Re-render the host panels so the Browse button (gated on mediaCache.length) appears once the
+  // Async listing resolves — including when an image value is already set, so the current image can
+  // Be replaced. Mirrors loadLayoutEntries()'s renderOnly() in head-panel.
+  renderOnly("leftPanel", "rightPanel");
 }
 
 /** Force media cache reload (e.g. after upload). */

package/src/utils/studio-utils.ts

@@ -168,6 +168,9 @@ export function findContentTypeSchema(
   if (!documentPath || !projectConfig?.contentTypes) {
     return null;
   }
+  // Content-type `source` prefixes are always forward-slash. The desktop platform can hand us
+  // OS-native backslash paths on Windows, so normalize before prefix matching.
+  const docPath = documentPath.replaceAll("\\", "/");
   for (const [name, def] of Object.entries(
     projectConfig.contentTypes as Record<string, ContentTypeDef>,
   )) {
@@ -177,7 +180,7 @@ export function findContentTypeSchema(
     const src = def.source.replace(/^\.\//, "").replace(/\/$/, "");
     const hasExt = src.includes(".") && !src.endsWith("/");
     if (hasExt) {
-      if (documentPath === src || documentPath.endsWith(`/${src}`)) {
+      if (docPath === src || docPath.endsWith(`/${src}`)) {
         return { name, schema: def.schema };
       }
     } else {
@@ -187,7 +190,7 @@ export function findContentTypeSchema(
           : (formatByName(def.format)?.extensions[0] ??
             defaultContentFormat()?.extensions[0] ??
             ".json");
-      if (documentPath.startsWith(`${src}/`) && documentPath.endsWith(ext)) {
+      if (docPath.startsWith(`${src}/`) && docPath.endsWith(ext)) {
         return { name, schema: def.schema };
       }
     }