@jxsuite/studio 8.1.0 → 9.0.0

package/src/services/project-adoption.ts

@@ -11,9 +11,8 @@
 
 import { initProjectRepo } from "../files/files";
 import { getPlatform, hasPlatform } from "../platform";
-import { beginBatch, endBatch, isBatching } from "../tabs/transact";
+import { flushOpenBatches } from "../tabs/transact";
 import { workspace } from "../workspace/workspace";
-import type { Tab } from "../tabs/tab";
 
 let _adopter: ((root: string) => Promise<void>) | null = null;
 
@@ -52,8 +51,6 @@ export interface AdoptOutcome {
 
 /** The seams {@link adoptCreatedProject} runs through, so each caller keeps the one it already had. */
 export interface AdoptCreatedOptions {
-  /** The active tab, read AFTER adoption to re-anchor the agent loop's undo batch. */
-  getTab: () => Tab | null;
   /** The project-open flow. Defaults to this module's late-bound {@link adoptProject}. */
   adopt?: (root: string) => Promise<void>;
   /** Version-control init. Defaults to `files/files.ts`'s `initProjectRepo`. */
@@ -76,9 +73,8 @@ export interface AdoptCreatedOptions {
  * - **Verifying.** `openRecentProject` swallows its failures into a status message, so a resolved
  *   promise is not proof of adoption. The caller must be told which of the two happened.
  *
- * The batch dance is the third: the agent loop may hold an undo batch on the pre-adoption tab, and
- * adoption replaces every tab in the workspace. Flush it, adopt, re-open one on whatever tab
- * adoption left active.
+ * The third is the undo batch: the agent loop's lane may hold segments on pre-adoption tabs, and
+ * adoption replaces every tab in the workspace, so they are closed first (specs/ai.md §3.3).
  *
  * @param {string} root - Absolute root of the project that was just created.
  * @param {AdoptCreatedOptions} opts
@@ -86,7 +82,7 @@ export interface AdoptCreatedOptions {
  */
 export async function adoptCreatedProject(
   root: string,
-  { getTab, adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions,
+  { adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions = {},
 ): Promise<AdoptOutcome> {
   // Never fails the create: a project that was written stays written (initProjectRepo notifies).
   await initRepo(root);
@@ -117,19 +113,15 @@ export async function adoptCreatedProject(
     }
   }
 
-  const wasBatching = isBatching();
-  if (wasBatching) {
-    endBatch();
-  }
+  /* The tabs an open lane has segments on are about to be replaced: close each now, against the
+     document it was written into. The lane stays open, so the turn's next write opens a segment on
+     whatever document it writes in the adopted project. */
+  flushOpenBatches();
   let adoptionError: string | null = null;
   try {
     await adopt(root);
   } catch (error) {
     adoptionError = error instanceof Error ? error.message : String(error);
   }
-  if (wasBatching) {
-    beginBatch(getTab());
-  }
-
   return { adopted: workspace.projectRoot === root, error: adoptionError, openedElsewhere };
 }

package/src/services/tool-executor.ts

@@ -9,17 +9,19 @@
  *   happen (`services/harness/chat-reducer.ts`), and each round's request is projected from it, as
  *   it always was, so the provider sees the conversation the panel shows, with whatever the send
  *   path trimmed or sealed before the turn began.
- * - **A batch belongs to the tab it edits** (§3.3). The undo batch opens on the active tab and is
- *   re-anchored after every call whose tools moved to another document, so a turn that edits two
- *   documents gives each its own history step and collab publish.
+ * - **The batch belongs to the assistant** (§3.3). The turn opens a batch lane owned by its actor,
+ *   and every write the turn's tools make joins it, one segment per document written: each document
+ *   gets one history step and one collab publish, whichever tab is active, and a person's edit
+ *   during the turn closes the segment on that document rather than being folded into it.
  * - **The ledger is filed under the last message the turn drew** (§3.2), in this module's `finally`,
  *   so the transcript draws the turn's changed-files summary under it.
  *
  * @license MIT
  */
 
+import type { InteractionStore } from "./harness/interaction-store";
 import type { createChatState } from "@jxsuite/ai/chat-state";
-import { DEFAULT_TURN_POLICY, runTurn } from "@jxsuite/ai/harness";
+import { DEFAULT_TURN_POLICY, assistantActorId, runTurn } from "@jxsuite/ai/harness";
 import type { TurnInput, TurnRun } from "@jxsuite/ai/harness";
 import { toChatMessages, toOpenAITools } from "@jxsuite/ai/messages";
 import type { StreamingClient } from "@jxsuite/ai/streaming-client";
@@ -27,7 +29,7 @@ import { createSessionFacts } from "@jxsuite/ai/tools";
 import type { SessionFacts, ToolRegistry } from "@jxsuite/ai/tools";
 
 import type { Tab } from "../tabs/tab";
-import { batchTab, beginBatch, endBatch } from "../tabs/transact";
+import { openBatchLane } from "../tabs/transact";
 import { estimatePromptTokens } from "./context-manager";
 import { fileTurn, openTurnLedger, turnAnchor } from "./ai-writes";
 import { applyHarnessEvent } from "./harness/chat-reducer";
@@ -48,6 +50,8 @@ interface RunAgentLoopOptions {
   getTab?: () => Tab | null;
   /** The conversation's facts, which every call's context carries; a fresh set when omitted. */
   session?: SessionFacts;
+  /** Where a call that needs the author waits on them. Without one, such a call is refused. */
+  interactions?: InteractionStore;
 }
 
 /**
@@ -62,26 +66,23 @@ export async function runAgentLoop({
   signal,
   getTab,
   session = createSessionFacts(),
+  interactions,
 }: RunAgentLoopOptions): Promise<void> {
   /* The ledger is filed under the turn's last DRAWN assistant message (see services/ai-writes), so
      the scan starts at the message this turn answers. */
   const turnUserId = chatState.messages.findLast((m) => m.role === "user")?.id;
   const ledger = openTurnLedger(`turn:${chatState.messages.length}`);
 
-  // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
-  if (getTab) {
-    beginBatch(getTab());
-  }
-  const reanchorBatch = () => {
-    if (!getTab) {
-      return;
-    }
-    const current = getTab();
-    if (current !== batchTab()) {
-      endBatch();
-      beginBatch(current);
-    }
-  };
+  /* One undo step per document the turn writes. A loop with no `getTab` has no document of its own
+     (the evals), so it gets no lane and each tool is its own entry. The owner's id is the one each
+     call's context will carry, so a tool's write joins the lane by naming `ctx.actor`. */
+  const lane = getTab
+    ? openBatchLane({
+        id: assistantActorId(session.sessionId, ledger.turnId),
+        kind: "assistant",
+        turnId: ledger.turnId,
+      })
+    : null;
 
   /* The placeholder `sendMessage` pushed is round one's message, so the turn answers into it; the
      conversation the turn continues is everything before it. */
@@ -124,7 +125,6 @@ export async function runAgentLoop({
           superseded = true;
           run?.cancel("superseded");
         },
-        reanchor: reanchorBatch,
       }),
       session,
       ledger,
@@ -137,13 +137,16 @@ export async function runAgentLoop({
     if (signal) {
       input.signal = signal;
     }
+    if (interactions) {
+      input.interactions = interactions.strategy;
+    }
     if (placeholder) {
       input.firstMessageId = placeholder.id;
     }
     run = runTurn(input);
     await run.outcome;
   } finally {
-    endBatch();
-    fileTurn(turnAnchor(chatState.messages, turnUserId) ?? "", ledger.writes);
+    const batches = lane?.close() ?? [];
+    fileTurn(turnAnchor(chatState.messages, turnUserId) ?? "", ledger.writes, batches);
   }
 }

package/src/state.ts

@@ -154,19 +154,9 @@ export function pathsEqual(a: JxPath | null, b: JxPath | null) {
   return a.every((v, i) => v === b[i]);
 }
 
-/**
- * Returns true if `path` is an ancestor of (or equal to) `descendant`.
- *
- * @param {JxPath} path
- * @param {JxPath} descendant
- * @returns {boolean}
- */
-export function isAncestor(path: JxPath, descendant: JxPath) {
-  if (path.length > descendant.length) {
-    return false;
-  }
-  return path.every((v, i) => v === descendant[i]);
-}
+/* Lives beside the doc-op vocabulary (`@jxsuite/schema/doc-ops`), with the other structural-path
+   helpers; re-exported for the many callers that import it from here. */
+export { isAncestor } from "@jxsuite/schema/doc-ops";
 
 // ─── Tree flattening (for layer panel) ────────────────────────────────────────
 

package/src/surfaces/files-panel.json

@@ -136,6 +136,18 @@
             }
           ]
         },
+        "address": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Add ?project= and a project folder's absolute path to this page's address to open it."
+            }
+          ]
+        },
         "welcome": {
           "tagName": "div",
           "attributes": {

package/src/surfaces/files-panel.ts

@@ -81,8 +81,11 @@ export interface FileRowView {
 
 /** Everything the document draws, as one value. */
 export interface FilesPanelValues {
-  /** Which of three things the panel is: no project, a monorepo root, or a tree. */
-  view: "none" | "welcome" | "tree";
+  /**
+   * Which of four things the panel is: no project, a monorepo root on a host that can open a
+   * project, the same root on one that opens from the address (`?project=`), or a tree.
+   */
+  view: "none" | "welcome" | "address" | "tree";
   headerState: "hidden" | "shown";
   projectName: string;
   query: string;

package/src/surfaces/welcome.ts

@@ -22,6 +22,7 @@
 import { getAccountStatus, getBannerNotices, needsAppInstall } from "../account-status";
 import { runOfferedAction } from "../account/action-flow";
 import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
+import { canOpenProject, getPlatform } from "../platform";
 import { getProjectList } from "../project-list";
 import { reactive } from "../reactivity";
 import { MINUTE, now } from "../services/clock";
@@ -226,7 +227,9 @@ function project(): Omit<WelcomeScope, "run" | "open" | "remove" | "clear" | "no
     // One entry, not two: the starter gallery IS the first step of New Project now, so the
     // Separate "Start from an Example…" button it used to hide behind is gone.
     { icon: "plus", id: "new", title: "New Project…" },
-    { icon: "folder-open", id: "open", title: "Open Project…" },
+    ...(canOpenProject(getPlatform())
+      ? [{ icon: "folder-open", id: "open", title: "Open Project…" } as const]
+      : []),
     ...(platformSupportsClone()
       ? [{ icon: "download-simple", id: "clone", title: "Clone Git Repository…" } as const]
       : []),

package/src/tabs/selection.ts

@@ -42,10 +42,22 @@
  * standing between a mixed selection and a half-applied, unrecorded delete.
  */
 
-import { isNumber } from "@jxsuite/schema/guards";
+import { isAncestor } from "@jxsuite/schema/doc-ops";
 
 import type { JxPath } from "../state";
-import { isAncestor, pathsEqual } from "../state";
+import { pathsEqual } from "../state";
+
+/* The structural-path helpers live beside the doc-op vocabulary, so any host that edits a document
+   the way Studio does orders and filters a batch the same way. Re-exported here, where every
+   Studio caller already imports them. */
+export {
+  comparePaths,
+  isSpliceablePath,
+  spliceCoordinate,
+  structuralBatch,
+  topLevelSelection,
+} from "@jxsuite/schema/doc-ops";
+export type { SpliceCoordinate } from "@jxsuite/schema/doc-ops";
 
 /**
  * The path single-target surfaces address — the most recently added, or `null` when empty.
@@ -171,113 +183,6 @@ export function pruneSelection(selection: readonly JxPath[], removed: JxPath): J
   return clonePaths(selection.filter((p) => !isAncestor(removed, p)));
 }
 
-/**
- * Order two paths the way the document reads: parents before children, siblings by index.
- *
- * Segments are compared pairwise; numbers numerically (so `children/10` follows `children/9`), and
- * anything else by string order. A prefix sorts before what extends it.
- *
- * @param {JxPath} a
- * @param {JxPath} b
- * @returns {number}
- */
-export function comparePaths(a: JxPath, b: JxPath): number {
-  const len = Math.min(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    const x = a[i]!;
-    const y = b[i]!;
-    if (x === y) {
-      continue;
-    }
-    if (isNumber(x) && isNumber(y)) {
-      return x - y;
-    }
-    return String(x) < String(y) ? -1 : 1;
-  }
-  return a.length - b.length;
-}
-
-/**
- * Drop any path whose ancestor is also selected.
- *
- * Deleting a `<section>` and one of its own paragraphs is one deletion, not two: the paragraph goes
- * with its parent, and a second splice into coordinates that no longer exist is how a batch
- * corrupts a document.
- *
- * @param {readonly JxPath[]} selection
- * @returns {JxPath[]}
- */
-export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
-  return clonePaths(
-    selection.filter((p) => !selection.some((q) => !pathsEqual(q, p) && isAncestor(q, p))),
-  );
-}
-
-/**
- * Whether `path` names a position a structural verb can splice — a tail of `"children"` + index.
- *
- * Every structural mutator (`mutateRemoveNode`, `mutateDuplicateNode`, `mutateWrapNode`) reaches
- * its parent with `parentElementPath` — drop the last two segments — and its position with
- * `childIndex` — take the last. That produces a splice coordinate for exactly one path shape, and
- * the Outline emits three others as first-class rows: the document element (`[]`), a repeater's map
- * template (`[…, "children", 1, "map"]`) and a `$switch` case (`[…, "cases", "warn"]`). For the
- * template, `parentElementPath` resolves to the enclosing children ARRAY, whose `.children` is
- * `undefined`, so the splice throws mid-transaction; for a case it splices at `NaN` and takes the
- * wrong child.
- *
- * Selecting one of those beside an ordinary element is a single ctrl-click, so this is the
- * invariant that keeps a batch from mutating the document and then throwing before anything is
- * recorded.
- *
- * @param {JxPath} path
- * @returns {boolean}
- */
-export function isSpliceablePath(path: JxPath): boolean {
-  return spliceCoordinate(path) !== null;
-}
-
-/** Where a structural verb splices: the parent element's path and the index in its children. */
-export interface SpliceCoordinate {
-  parentPath: JxPath;
-  index: number;
-}
-
-/**
- * The splice coordinate `path` names, or `null` for no path and for every path
- * {@link isSpliceablePath} refuses.
- *
- * @param {JxPath | null | undefined} path
- * @returns {SpliceCoordinate | null}
- */
-export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
-  const index = path?.at(-1);
-  return path && path.at(-2) === "children" && isNumber(index)
-    ? { index, parentPath: path.slice(0, -2) }
-    : null;
-}
-
-/**
- * The order a structural batch must run in: contained paths dropped, unspliceable paths dropped,
- * then LAST node first.
- *
- * Descending document order is what makes a loop of splices safe. Removing or duplicating at index
- * `n` renumbers every sibling after `n`, so a batch that starts at the end never touches a
- * coordinate a later step still needs. It is also why duplicating a multi-selection inserts each
- * clone directly after its own original instead of walking the whole run forward.
- *
- * Containment is decided BEFORE spliceability, on the selection the user actually made: a selected
- * repeater template still shadows its own descendants, so selecting the template and something
- * inside it yields nothing rather than quietly deleting the child the user never pointed at.
- *
- * @param {readonly JxPath[]} selection
- * @returns {JxPath[]} Deepest/last first, every entry a splice coordinate.
- */
-export function structuralBatch(selection: readonly JxPath[]): JxPath[] {
-  return topLevelSelection(selection)
-    .filter((path) => isSpliceablePath(path))
-    .toSorted((a, b) => comparePaths(b, a));
-}
-
 /**
  * Deduplicate a list of paths, keeping the FIRST occurrence of each.
  *

package/src/tabs/tab.ts

@@ -132,7 +132,7 @@ export interface StoredLivePreview {
   error: string | null;
 }
 
-interface HistorySnapshot {
+export interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: JxMutableNode | null;
   /** Selection after this state's transaction — the whole set, so a batch undoes back to it. */
@@ -153,6 +153,13 @@ interface HistorySnapshot {
    * back through the prose one pause at a time instead of undoing the edit.
    */
   coalesceKey?: string | null;
+  /**
+   * Who made this step, when it is not the person at the keyboard: the id of the actor whose batch
+   * lane closed it (specs/ai.md §3.3). Absent on a person's own edits.
+   */
+  actor?: string;
+  /** The turn whose batch this step is, beside {@link HistorySnapshot.actor}. */
+  turnId?: string;
 }
 
 /**
@@ -186,6 +193,8 @@ export interface Tab {
   scope: {
     stop: () => void;
     run: <T>(fn: () => T) => T | undefined;
+    /** False once {@link disposeTab} stopped it: how a record that outlives the tab can tell. */
+    readonly active?: boolean;
   };
   doc: {
     document: JxMutableNode;