@jxsuite/studio 8.1.0 → 10.0.0

package/src/services/ai-command-tools.ts

@@ -60,6 +60,7 @@
  * @license MIT
  */
 
+import { toolFacts } from "@jxsuite/ai/jx-tools";
 import { createToolContext, toolError } from "@jxsuite/ai/tools";
 import type {
   ToolArguments,
@@ -82,6 +83,7 @@ import type { WriteReportDeps, WriteSnapshot } from "./ai-write-report";
 import type { CommandContext } from "../commands/context";
 import type { AiToolReport, AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
+import { runAsActor } from "../tabs/transact";
 
 /**
  * The record a selection-level projection composes through.
@@ -214,8 +216,9 @@ function definitionOf(
   } else {
     parameters = command.args ?? EMPTY_ARGS;
   }
-  return {
+  const definition: ToolDefinition = {
     name: tool.name,
+    title: command.title,
     description: `${tool.description}${undoSuffix(command)}`,
     /* SAFETY: `parameters` is an `argsSchema()` object (or the selector's composed from one), a
        JSON Schema object whose only departures from `JSONSchema` are readonly arrays and a
@@ -227,6 +230,13 @@ function definitionOf(
     llmStrict: false,
     execute: (args, ctx) => execute(tool.name, args, ctx),
   };
+  /* The facts are the table's, by tool name (`@jxsuite/ai/jx-tools`). A record with none projects a
+     tool without them, which the catalog refuses: that is the test that keeps the table whole. */
+  const facts = toolFacts(tool.name);
+  if (facts) {
+    definition.annotations = facts.annotations;
+  }
+  return definition;
 }
 
 /**
@@ -347,13 +357,21 @@ function fileLedger(
   }
 }
 
+/** The command view, which also answers what the catalog asks of it. */
+export interface CommandToolRegistry extends ToolRegistry {
+  /** Every record's projection, offered or not: the catalog's members from this side. */
+  readonly members: () => ToolDefinition[];
+  /** Whether the record projecting `name` is offered this round (its gate, and a non-empty enum). */
+  readonly advertises: (name: string) => boolean;
+}
+
 /**
  * A ToolRegistry whose tools are the active registry's `aiTool` records. Nothing is registered.
  *
  * @param {CommandToolDeps} deps
- * @returns {ToolRegistry}
+ * @returns {CommandToolRegistry}
  */
-export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
+export function createCommandToolRegistry(deps: CommandToolDeps): CommandToolRegistry {
   /** The record projecting `name`, enabled or not — so `execute` can reach a refusal. */
   function commandFor(name: string): AnyCommand | undefined {
     return activeRegistry()
@@ -408,10 +426,10 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
         const { paths, ...rest } = args;
         await registry.run(SELECTOR, { paths });
         before = registry.context();
-        await registry.run(command.id, rest);
+        await runAsActor(ctx.actor, () => registry.run(command.id, rest));
       } else {
         before = registry.context();
-        await registry.run(command.id, args);
+        await runAsActor(ctx.actor, () => registry.run(command.id, args));
       }
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error), success: false };
@@ -507,52 +525,24 @@ export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
       return { valid: true };
     },
     execute,
-  };
-}
-
-/**
- * Union of two registries for the loop: hand tools gated by tier, command tools gated by the
- * record.
- *
- * `list`/`listForLLM` concatenate (hand first); `getDefinition`/`validate`/`execute` go to
- * whichever side has the definition, hand first; an unknown name answers `Unknown tool: "<name>"`
- * as `@jxsuite/ai` does; `register` goes to `hand`. A name on both sides is a defect the parity
- * test in `tests/ai-system-prompt.test.ts` catches; the composite's hand-first order is not a
- * feature anyone may rely on.
- *
- * @param {ToolRegistry} hand
- * @param {ToolRegistry} commands
- * @returns {ToolRegistry}
- */
-export function composeToolRegistries(hand: ToolRegistry, commands: ToolRegistry): ToolRegistry {
-  function sideOf(name: string): ToolRegistry | undefined {
-    if (hand.getDefinition(name)) {
-      return hand;
-    }
-    return commands.getDefinition(name) ? commands : undefined;
-  }
-  return {
-    register(tool) {
-      hand.register(tool);
-    },
-    list() {
-      return [...hand.list(), ...commands.list()];
-    },
-    listForLLM() {
-      return [...hand.listForLLM(), ...commands.listForLLM()];
-    },
-    getDefinition(name) {
-      return sideOf(name)?.getDefinition(name);
-    },
-    validate(name, args) {
-      const side = sideOf(name);
-      return side
-        ? side.validate(name, args)
-        : { valid: false, errors: [`Unknown tool: "${name}"`] };
+    members() {
+      const registry = activeRegistry();
+      if (!registry) {
+        return [];
+      }
+      const definitions: ToolDefinition[] = [];
+      for (const command of projected(registry)) {
+        const definition = definitionOf(registry, command, execute);
+        if (definition) {
+          definitions.push(definition);
+        }
+      }
+      return definitions;
     },
-    async execute(name, args, ctx) {
-      const side = sideOf(name);
-      return side ? side.execute(name, args, ctx) : toolError(`Unknown tool: "${name}"`);
+    advertises(name) {
+      const registry = activeRegistry();
+      const command = commandFor(name);
+      return registry !== null && command !== undefined && advertised(registry, command);
     },
   };
 }

package/src/services/ai-import-tools.ts

@@ -21,6 +21,7 @@
  * @license MIT
  */
 
+import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
 import { IMPORT_MAX_PAGES } from "@jxsuite/protocol";
 import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
@@ -35,7 +36,6 @@ import { adoptCreatedProject } from "./project-adoption";
 import type { AdoptCreatedOptions, AdoptOutcome } from "./project-adoption";
 
 import type { JsonValue, ToolRegistry } from "@jxsuite/ai/tools";
-import type { Tab } from "../tabs/tab";
 import type {
   ImportBreakpointPolicy,
   ImportReadyEvent,
@@ -62,8 +62,6 @@ const DEFAULT_MIN_FIDELITY = 25;
 const MAX_FIDELITY = 100;
 
 export interface ImportToolsCtx {
-  /** The active tab, read AFTER adoption to re-anchor the agent loop's undo batch. */
-  getTab: () => Tab | null;
   /** Open the imported project in this window. Defaults to the late-bound adopter. */
   adoptProject?: (root: string) => Promise<void>;
   /** Fired once adoption is VERIFIED — the session store re-keys the live chat here. */
@@ -269,7 +267,6 @@ function describeRun(id: string, root: string, summary?: ImportSiteSummary): str
 export function registerImportTools(
   registry: Pick<ToolRegistry, "register">,
   {
-    getTab,
     adoptProject,
     onProjectAdopted,
     brief: briefStore = { clear: clearPendingImportBrief, read: pendingImportBrief },
@@ -278,6 +275,8 @@ export function registerImportTools(
   registry.register(
     createToolDefinition({
       name: "import_site",
+      title: "Import a site",
+      annotations: JX_TOOL_FACTS.import_site.annotations,
       description:
         "Clone a live website into a new Jx project and open it in the studio: pages, styles, " +
         "assets, a shared layout and recurring components. Only available while no project is " +
@@ -454,7 +453,7 @@ export function registerImportTools(
          * failure here is not the run's failure: the import continues either way, and the terminal
          * path below reports honestly on whichever state the window ended up in.
          */
-        const adoptOptions: AdoptCreatedOptions = { getTab };
+        const adoptOptions: AdoptCreatedOptions = {};
         if (adoptProject) {
           adoptOptions.adopt = adoptProject;
         }

package/src/services/ai-project-tools.ts

@@ -14,6 +14,7 @@
  * @license MIT
  */
 
+import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition } from "@jxsuite/ai/tools";
 import { isJsonObject, isNumber } from "@jxsuite/schema/guards";
 import type { CreateProjectDestination, StudioPlatform } from "../types";
@@ -64,7 +65,6 @@ interface ListedEntry {
 }
 
 export interface ProjectToolsCtx {
-  getTab: () => Tab | null;
   validate?: (doc: CandidateDocument) => Promise<string[]>;
   /**
    * Gate for `project.json` writes — the per-project entry document, not the document schema. It
@@ -113,7 +113,6 @@ export interface ProjectToolsCtx {
 export function registerProjectTools(
   registry: Pick<ToolRegistry, "register">,
   {
-    getTab,
     validate = validateDoc,
     validateProject = validateProjectConfig,
     renderCheck,
@@ -130,6 +129,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "list_files",
+      title: "List files",
+      annotations: JX_TOOL_FACTS.list_files.annotations,
       description:
         "List the project's files recursively (paths relative to the project root, with type and " +
         "size). Use this to discover pages, layouts, components, content, data, and styles before " +
@@ -199,6 +200,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "read_file",
+      title: "Read a file",
+      annotations: JX_TOOL_FACTS.read_file.annotations,
       description:
         "Read a project file's content by its project-relative path. Works for any text file " +
         "(Jx documents, markdown, CSS, data). Large files are truncated.",
@@ -247,6 +250,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "write_file",
+      title: "Write a file",
+      annotations: JX_TOOL_FACTS.write_file.annotations,
       description:
         "Write a project file (create or overwrite) at a project-relative path. Jx documents " +
         "(.json under pages/, layouts/, components/) are schema-validated and render-checked " +
@@ -422,6 +427,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "search_files",
+      title: "Search files",
+      annotations: JX_TOOL_FACTS.search_files.annotations,
       description:
         "Search project files by file NAME (not content). Returns matching paths. Use list_files " +
         "for a directory overview and read_file to inspect contents.",
@@ -465,6 +472,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "create_project",
+      title: "Create a project",
+      annotations: JX_TOOL_FACTS.create_project.annotations,
       description:
         "Create a new Jx project (project.json, conventional directories, starter pages) and open " +
         "it in the studio. Only available while no project is open. After it succeeds, the file " +
@@ -625,7 +634,6 @@ export function registerProjectTools(
          */
         const { adopted, error: adoptionError } = await adoptCreatedProject(result.root, {
           adopt: adoptProject,
-          getTab,
         });
         if (adopted) {
           onProjectAdopted?.(result.root);
@@ -653,6 +661,8 @@ export function registerProjectTools(
   registry.register(
     createToolDefinition({
       name: "list_starters",
+      title: "List starters",
+      annotations: JX_TOOL_FACTS.list_starters.annotations,
       description:
         "List the starter templates available for new projects (id, name, description). " +
         "Currently informational — create_project scaffolds from built-in template variants.",