@jxsuite/studio 8.1.0 → 10.0.0

package/src/services/ai-tools.ts

@@ -1,116 +1,31 @@
 /**
  * Ai-tools.js — Jx document manipulation tools for the AI assistant
  *
- * Concrete `.jx` AST tools registered into a `@jxsuite/ai` ToolRegistry. Each tool wraps an
- * existing `transactDoc()` mutation helper so AI edits get the same undo/redo history as manual
- * edits (specs/ai.md §3.1 and §3.2 — optimistic apply, undo as the backstop).
+ * Concrete `.jx` AST tools registered into a `@jxsuite/ai` ToolRegistry. The tree tools are the
+ * portable producers of `@jxsuite/ai/jx-tools` over the active tab, so AI edits get the same
+ * undo/redo history as manual edits (specs/ai.md §3.1 and §3.2 — optimistic apply, undo as the
+ * backstop); `create_page` and `create_component` write new files.
  *
  * @license MIT
  */
 
 import { createToolDefinition } from "@jxsuite/ai/tools";
-import type { ToolRegistry, ToolResult, WriteLedger } from "@jxsuite/ai/tools";
-import type { JsonObject, JxMutableNode, JxPath } from "@jxsuite/schema/types";
-import { getNodeAtPath } from "../state";
+import type { ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
+import { docToolEntries, JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
+import type { JsonObject } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
-import {
-  mutateAddDef,
-  mutateInsertNode,
-  mutateMoveNode,
-  mutateRemoveDef,
-  mutateUpdateProperty,
-  mutateUpdateStyle,
-  transactDoc,
-} from "../tabs/transact";
-import type { JxNodeValue } from "../tabs/transact";
-import type { JsonValue } from "../types";
 import { validateDoc } from "./jx-validate";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
 import { serializeJson } from "@jxsuite/schema/json-layout";
-import {
-  reportDocumentWrite,
-  snapshotBeforeWrite,
-  translateValidationError,
-} from "./ai-write-report";
-import type { CandidateDocument, RenderVerdict } from "./ai-write-report";
+import { translateValidationError } from "./ai-write-report";
+import type { CandidateDocument } from "./ai-write-report";
+import { studioDocumentHost, studioWriteReporter } from "./harness/studio-documents";
 
 /* Re-exported from its new home so `ai-project-tools.ts` and the tests keep their import: the
    translation moved with the verdict it belongs to (`ai-write-report.ts`), where every document
    write — hand-registered or projected from a command record — now reads it. */
 export { translateValidationError } from "./ai-write-report";
 
-const PATH_DESCRIPTION =
-  "Path to a node in the document, as a JSON array of keys/indices from the root " +
-  '(e.g. ["children", 0, "children", 1]). Use read_document to discover valid paths.';
-
-/**
- * The node at `path`, typed as what {@link getNodeAtPath} actually answers: a path the model made up
- * runs off the tree, and that is `undefined`, which every tool here reports as "No node exists".
- */
-function nodeAt(doc: JxMutableNode, path: JxPath): JxMutableNode | undefined {
-  return getNodeAtPath(doc, path);
-}
-
-/** Steering error for document tools called with no active tab. */
-function noDocError(): ToolResult {
-  return {
-    success: false,
-    error:
-      "No document is open — use open_document(path) to open one on the canvas, or " +
-      "read_file/write_file to work with project files directly.",
-  };
-}
-
-/**
- * Apply a mutation, then hand the verdict to `ai-write-report.ts`: only the schema errors the edit
- * NEWLY introduced are reported, the render check runs when a renderCheck was provided and
- * rendering worked before, and a success carries the token hints. The change stays applied either
- * way (optimistic apply + undo); reporting the errors lets the agent loop self-correct on the next
- * round. Both rules are specs/ai.md §3.1.
- *
- * @param {WriteLedger} ledger - The call's ledger (`ctx.ledger`)
- * @param {import("../tabs/tab").Tab} tab
- * @param {(t: import("../tabs/tab").Tab) => void} mutationFn
- * @param {string} summary
- * @param {(doc: CandidateDocument) => Promise<string[]>} validate
- * @param {((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined} renderCheck
- * @param {Record<string, string> | undefined} projectStyle
- * @returns {Promise<import("@jxsuite/ai/tools").ToolResult>}
- */
-async function applyAndValidate(
-  ledger: WriteLedger,
-  tab: Tab,
-  mutationFn: (t: Tab) => void,
-  summary: string,
-  validate: (doc: CandidateDocument) => Promise<string[]>,
-  renderCheck: ((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined,
-  projectStyle: Record<string, string> | undefined,
-): Promise<ToolResult> {
-  const deps = { getProjectStyle: () => projectStyle, renderCheck, validate };
-  const before = await snapshotBeforeWrite(tab, deps);
-
-  /* AND THE WRITE CAN BE REFUSED, in which case the model must be told rather than congratulated.
-     The collab gate pauses structural editing while source is canonical, and this went on to
-     record a ledger entry ("Changed N files") and validate the UNCHANGED document — which produces
-     no new errors, so the tool answered `success: true`. The model then built its next three edits
-     on a change that never existed. A refusal is an ordinary state of the room, so it is an error
-     result with a reason the model can act on (wait, or ask the author), not a thrown exception. */
-  if (!transactDoc(tab, mutationFn)) {
-    return {
-      success: false,
-      error:
-        "The document is frozen: a collaborator is editing its source, so structural edits are " +
-        "paused. Nothing was changed. Try again once source editing ends.",
-    };
-  }
-  /* One ledger entry per mutation, so the panel's "Changed N files" counts documents the model
-     touched rather than sentences it wrote (`ai.md` §3.2). `disk: false` is the load-bearing half:
-     this went through transactDoc, so the tab's history — and "Restore to here" — can reach it. */
-  ledger.record({ disk: false, ok: true, path: tab.documentPath ?? "(untitled)", tool: summary });
-
-  return reportDocumentWrite(tab, before, summary, deps);
-}
-
 /**
  * Register the document-manipulation tools into a tool registry.
  *
@@ -181,481 +96,26 @@ export function registerAiTools(
     }
     return `${summary} (Saved to disk; not undoable.)`;
   }
-  registry.register(
-    createToolDefinition({
-      name: "read_document",
-      description:
-        "Read the current Jx document, or the subtree at a given path. Use this to discover " +
-        "node paths before calling set_property, add_child, or delete_node.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "array",
-            description: `${PATH_DESCRIPTION} Omit to read the whole document.`,
-            items: { type: ["string", "number"] },
-          },
-        },
-        required: [],
-      },
-      execute(args) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, which refuses
-           a `path` that is present but not an array. Its items are not checked; a key that does
-           not resolve makes `nodeAt` answer undefined, reported just below. */
-        const { path } = args as { path?: JxPath };
-        const node = path && path.length > 0 ? nodeAt(tab.doc.document, path) : tab.doc.document;
-        if (node === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
-        }
-        return { success: true, data: node };
-      },
-    }),
-  );
-
-  registry.register(
-    createToolDefinition({
-      name: "set_property",
-      description:
-        "Set or remove a property on a node (e.g. tagName, textContent, className, style, " +
-        "attributes, $props). Pass value: null to remove the property.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "array",
-            description: PATH_DESCRIPTION,
-            items: { type: ["string", "number"] },
-          },
-          key: {
-            type: "string",
-            description: 'The property name to set, e.g. "textContent" or "className".',
-          },
-          value: {
-            description: "The new value, or null to remove the property.",
-          },
-        },
-        /*
-         * "value" omitted from required: passing null / omitting it means "remove the property",
-         * but the registry rejects null on required args (tools.js:181). See `ai.md` §3.6.
-         */
-        required: ["path", "key"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
-           present array and `key` a present string. `value` declares no type, so it is any JSON
-           value or absent, all of which `JxNodeValue` includes. A `path` whose items do not resolve
-           is caught by `nodeAt` just below. */
-        const { path, key, value } = args as { path: JxPath; key: string; value?: JxNodeValue };
-        const node = nodeAt(tab.doc.document, path);
-        if (node === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          (t) => mutateUpdateProperty(t, path, key, value ?? undefined),
-          `Set "${key}" at ${JSON.stringify(path)}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  registry.register(
-    createToolDefinition({
-      name: "add_child",
-      description:
-        "Insert a new child node into the children array of the node at parentPath, at the " +
-        "given index (0 = first child). The node definition follows the Jx document schema " +
-        '(e.g. { "tagName": "p", "textContent": "Hello" }).',
-      parameters: {
-        type: "object",
-        properties: {
-          parentPath: {
-            type: "array",
-            description: `${PATH_DESCRIPTION} Must point at a node, not a children array.`,
-            items: { type: ["string", "number"] },
-          },
-          index: { type: "integer", description: "Position in the children array to insert at." },
-          node: {
-            type: "object",
-            description:
-              'The Jx node definition to insert, e.g. { "tagName": "div", "children": [] }.',
-          },
-        },
-        required: ["parentPath", "index", "node"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `parentPath` is
-           a present array, `node` a present object, and `index` a present number — or a numeric
-           string, which the validator also admits for an integer and `splice` coerces alike.
-           `node` is a model-written tree whose shape the schema check after the write judges, and
-           a `parentPath` that does not resolve is caught just below. */
-        const {
-          parentPath,
-          index,
-          node: childNode,
-        } = args as {
-          parentPath: JxPath;
-          index: number;
-          node: JxMutableNode;
-        };
-        const parent = nodeAt(tab.doc.document, parentPath);
-        if (parent === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(parentPath)}.` };
-        }
-        /*
-         * Guard against a parentPath that points at a children *array* rather than a node — the
-         * common failure is a trailing "children" segment (e.g. ["children",0,"children"]).
-         * add_child appends "children" + index itself, so an array-valued parentPath would splice
-         * into a bogus `.children` property on the array (childArray() creates one) and the node
-         * would be stored where nothing renders, yet the tool would report success. Reject it with
-         * a precise message so the loop self-corrects.
-         */
-        if (Array.isArray(parent)) {
-          return {
-            success: false,
-            error:
-              `parentPath ${JSON.stringify(parentPath)} points at a children array, not a node. ` +
-              `Drop the trailing "children" segment — add_child appends "children" and the index ` +
-              `automatically. For example, to insert into the node at ["children",0,"children",1], ` +
-              `pass parentPath: ["children",0,"children",1].`,
-          };
-        }
-        if (parent.children !== undefined && !Array.isArray(parent.children)) {
-          return {
-            success: false,
-            error: "Cannot insert into mapped-array children; edit the map template instead.",
-          };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          (t) => mutateInsertNode(t, parentPath, index, childNode),
-          `Inserted node at ${JSON.stringify([...parentPath, "children", index])}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  // ── set_style ──────────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "set_style",
-      description:
-        "Set or remove a CSS style property on a node. Style property names use camelCase " +
-        '(e.g. "backgroundColor", "fontSize", "borderRadius"). Values are always strings ' +
-        '(e.g. "10px", "center", "var(--color-accent)"). Pass value: null to remove.',
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "array",
-            description: PATH_DESCRIPTION,
-            items: { type: ["string", "number"] },
-          },
-          property: {
-            type: "string",
-            description: 'CSS property name in camelCase, e.g. "backgroundColor".',
-          },
-          value: {
-            description:
-              'CSS value as a string (e.g. "10px", "var(--color-accent)"), or null to remove.',
-          },
-        },
-        /*
-         * "value" omitted from required so null / omitted = remove (registry rejects null on
-         * required args, tools.js:181). See `ai.md` §3.6.
-         */
-        required: ["path", "property"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
-           present array and `property` a present string; a `path` that does not resolve is caught
-           just below. `value` is read untyped and stringified. */
-        const { path, property } = args as { path: JxPath; property: string };
-        const { value } = args;
-        if (nodeAt(tab.doc.document, path) === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
-        }
-        const prop = property;
-        const val = value == null ? undefined : String(value);
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          (t) => mutateUpdateStyle(t, path, prop, val),
-          `Set style "${prop}" at ${JSON.stringify(path)}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  // ── set_text ───────────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "set_text",
-      description:
-        "Set the textContent of a node. Convenience alias for set_property with key: 'textContent'.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "array",
-            description: PATH_DESCRIPTION,
-            items: { type: ["string", "number"] },
-          },
-          value: { type: "string", description: "Text content." },
-        },
-        required: ["path", "value"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `path` is a
-           present array and `value` a present string; a `path` that does not resolve is caught
-           just below. */
-        const { path, value } = args as { path: JxPath; value: string };
-        if (nodeAt(tab.doc.document, path) === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          /* Through the recording mutators, as two `set-key` ops, rather than by writing the node
-             directly. An unrecorded write reaches the canvas only as a full re-render, history only
-             as a whole-document snapshot, and collaborators only as a diff. */
-          (t) => {
-            mutateUpdateProperty(t, path, "textContent");
-            mutateUpdateProperty(t, path, "children", [value]);
-          },
-          `Set text at ${JSON.stringify(path)}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  // ── add_state ──────────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "add_state",
-      description:
-        "Add a new reactive state variable under the document's `state` object. The value can be a scalar " +
-        '(e.g. 0, ""), a typed object ({ "type": "string", "default": "" }), a computed ' +
-        'string ("${state.other}"), a function ({ "$prototype": "Function", "body": "..." }), ' +
-        'or a data source ({ "$prototype": "Data", "$src": "./data.json" }).',
-      parameters: {
-        type: "object",
-        properties: {
-          key: { type: "string", description: 'State variable name, e.g. "count", "isOpen".' },
-          value: {
-            description:
-              "Initial value or state shape object (scalar, typed, computed, function, or data source).",
-          },
-        },
-        required: ["key", "value"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so `key` is a
-           present string. */
-        const { key } = args as { key: string };
-        const { value } = args;
-        if (tab.doc.document.state && tab.doc.document.state[key] !== undefined) {
-          return {
-            success: false,
-            error: `State key "${key}" already exists. Use update_state to change it, or remove it first.`,
-          };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          /* `mutateAddDef` rather than `mutateUpdateProperty`: the latter deletes on "", which is
-             wrong for a state default (`"title": ""`). It also records the op, so the canvas, the
-             history and collaborators each get the edit as an edit. */
-          /* SAFETY: `value` is required, so the registry refused it missing or null; it is the
-             model's state entry, possibly a scalar default (`0`, `""`) the schema admits.
-             `mutateAddDef` only clones `def` and stores it under `state[key]`, never reading it
-             as the object its parameter names. */
-          (t) => mutateAddDef(t, key, value as Record<string, JsonValue>),
-          `Added state "${key}".`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  // ── update_state ───────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "update_state",
-      description:
-        "Update or remove an existing state variable at the document root. Pass value: null to remove.",
-      parameters: {
-        type: "object",
-        properties: {
-          key: { type: "string", description: 'State variable name to update, e.g. "count".' },
-          value: {
-            description:
-              "New value (same shapes as add_state), or null to remove the state variable.",
-          },
-        },
-        /*
-         * "value" omitted from required so null = remove (registry rejects null on required
-         * args, tools.js:181). See `ai.md` §3.6.
-         */
-        required: ["key"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so `key` is a
-           present string. */
-        const { key } = args as { key: string };
-        const { value } = args;
-        if (!tab.doc.document.state || tab.doc.document.state[key] === undefined) {
-          return {
-            success: false,
-            error: `State key "${key}" does not exist. Use add_state to create it, or check the name. Current state keys: ${Object.keys(tab.doc.document.state || {}).join(", ") || "(none)"}`,
-          };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          /* The recording def mutators, for the reason `add_state` gives. Removing the last key
-             drops the empty `state` object, as the Inspector's own removal does. */
-          (t) => {
-            if (value == null) {
-              mutateRemoveDef(t, key);
-            } else {
-              /* SAFETY: the model's state entry, possibly a scalar default the schema admits.
-                 `mutateAddDef` only clones `def` and stores it under `state[key]`, never reading
-                 it as the object its parameter names. */
-              mutateAddDef(t, key, value as Record<string, JsonValue>);
-            }
-          },
-          value == null ? `Removed state "${key}".` : `Updated state "${key}".`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
-
-  // ── move_node ──────────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "move_node",
-      description:
-        "Move a node from one location to another in the document tree. The node is removed " +
-        "from fromPath and inserted into toParentPath at toIndex.",
-      parameters: {
-        type: "object",
-        properties: {
-          fromPath: {
-            type: "array",
-            description: `${PATH_DESCRIPTION} The node to move.`,
-            items: { type: ["string", "number"] },
-          },
-          toParentPath: {
-            type: "array",
-            description: `${PATH_DESCRIPTION} The target parent (a node, not a children array).`,
-            items: { type: ["string", "number"] },
-          },
-          toIndex: {
-            type: "integer",
-            description: "Insertion index in the target parent's children array.",
-          },
-        },
-        required: ["fromPath", "toParentPath", "toIndex"],
-      },
-      async execute(args, ctx) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: both paths are
-           present arrays, and `toIndex` a present number or numeric string (the validator admits
-           both for an integer). Paths that do not resolve are caught just below. */
-        const { fromPath, toParentPath, toIndex } = args as {
-          fromPath: JxPath;
-          toParentPath: JxPath;
-          toIndex: number;
-        };
-        if (fromPath.length < 2) {
-          return { success: false, error: "Cannot move the document root." };
-        }
-        if (nodeAt(tab.doc.document, fromPath) === undefined) {
-          return {
-            success: false,
-            error: `No node exists at fromPath ${JSON.stringify(fromPath)}.`,
-          };
-        }
-        if (nodeAt(tab.doc.document, toParentPath) === undefined) {
-          return {
-            success: false,
-            error: `No node exists at toParentPath ${JSON.stringify(toParentPath)}.`,
-          };
-        }
-        return applyAndValidate(
-          ctx.ledger,
-          tab,
-          (t) => mutateMoveNode(t, fromPath, toParentPath, toIndex),
-          `Moved node from ${JSON.stringify(fromPath)} to ${JSON.stringify([...toParentPath, "children", toIndex])}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
+  /* `read_document` and the seven tree tools are the portable producers of `@jxsuite/ai/jx-tools`,
+     run over the active tab: each plans its edit as doc ops, and the tab applies them as one
+     transaction the turn's batch lane, history and collaborators all see (specs/ai.md §3.9). */
+  const host = studioDocumentHost({ getTab });
+  const reporter = studioWriteReporter(host, {
+    getProjectStyle: styleOf,
+    renderCheck,
+    validate,
+  });
+  for (const entry of docToolEntries(host, { reporter })) {
+    registry.register(entry);
+  }
 
   // ── create_component ───────────────────────────────────────────────────
 
   registry.register(
     createToolDefinition({
       name: "create_component",
+      title: "Create a component",
+      annotations: JX_TOOL_FACTS.create_component.annotations,
       description:
         "Create a new Jx component file on disk. Writes the component JSON to the given " +
         "relative path within the project. The content must be a valid Jx component document.",
@@ -744,6 +204,8 @@ export function registerAiTools(
   registry.register(
     createToolDefinition({
       name: "create_page",
+      title: "Create a page",
+      annotations: JX_TOOL_FACTS.create_page.annotations,
       description:
         "Create a new Jx page file on disk. A page typically includes a layout component and " +
         "section children. The content must be a valid Jx page document.",