@jxsuite/studio 0.32.0 → 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/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>;