@jxsuite/studio 8.1.0 → 9.0.0

package/src/services/ai-ask.ts

@@ -1,12 +1,10 @@
 /**
  * Ai-ask.ts — the assistant's one way to stop and put a question to the author.
  *
- * The agent loop `await`s `toolRegistry.execute` (`services/tool-executor.ts`), so a tool that
- * returns a pending promise suspends the turn. That is the whole mechanism: `ask_user` registers a
- * question, hands back a promise, and the panel resolves it when the human answers. No new chat
- * status, no pre-execution hook, and nothing in the published `@jxsuite/ai` changes —
- * `finishStream` has already set the state to `"idle"` by the time tools run, so a suspended turn
- * is idle by construction and this store is what "waiting" means.
+ * `ask_user` declares what it asks (`interaction`) and what its answer means (`settle`), and has no
+ * body that waits: the invoker answers `needs_input` before any tool code runs, the turn engine
+ * puts the question to the assistant's interaction store (`harness/interaction-store.ts`), and the
+ * person's answer comes back through `settle` as the call's result (specs/ai.md §3.4 and §3.11).
  *
  * Two decisions are load-bearing and easy to get wrong on a rewrite:
  *
@@ -17,29 +15,16 @@
  *   between them is a 400. The answer travels as the tool result, and the chat view renders it into
  *   the question's own chip.
  *
- * Exactly one question can be outstanding, because `runAgentLoop` executes a round's tool calls
- * serially. The guard below is defensive, not load-bearing.
- *
  * @license MIT
  */
 
+import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
 import { isString } from "@jxsuite/schema/guards";
-import { reactive } from "../reactivity";
-
-import type { ToolRegistry } from "@jxsuite/ai/tools";
 
-/** A question the assistant is waiting on. `id` is the tool-call id, so the chip and this agree. */
-export interface PendingAsk {
-  id: string;
-  question: string;
-  /** Short choices rendered as buttons. Free text is always allowed alongside them. */
-  options: string[];
-  /** One line of why-I'm-asking, rendered under the question. */
-  context: string;
-}
+import type { InteractionResponse, ToolRegistry } from "@jxsuite/ai/tools";
 
-/** How a question was settled. `answer: null` with `skipped` is the author saying "you decide". */
+/** What a settled question's result carries: the answer, or `null` with `skipped` for "you decide". */
 export interface AskAnswer {
   answer: string | null;
   skipped: boolean;
@@ -48,112 +33,6 @@ export interface AskAnswer {
 /** Max choices rendered as buttons; beyond this the question wants free text, not a menu. */
 const MAX_OPTIONS = 6;
 
-const state = reactive<{ pending: PendingAsk | null }>({ pending: null });
-
-/** The resolver for {@link state.pending}, kept out of the reactive object (it is not render data). */
-let settle: ((answer: AskAnswer) => void) | null = null;
-
-/** Torn down with the question so a stopped turn does not leave a listener on a dead signal. */
-let detachAbort: (() => void) | null = null;
-
-function clear() {
-  state.pending = null;
-  settle = null;
-  detachAbort?.();
-  detachAbort = null;
-}
-
-/**
- * The outstanding question, or null. Reactive — read it inside an `effect()` to repaint on it.
- *
- * @returns {PendingAsk | null}
- */
-export function pendingAsk(): PendingAsk | null {
-  return state.pending;
-}
-
-/** Whether a turn is suspended on the author. The composer's Send becomes Answer on this. */
-export function isAwaitingAnswer(): boolean {
-  return state.pending !== null;
-}
-
-/**
- * Register a question and suspend until it is settled.
- *
- * @param {PendingAsk} ask
- * @param {AbortSignal} [signal] - The asking call's signal. Without one the question can still be
- *   settled by {@link cancelAsk}, but a Stop would leave the turn awaiting a promise nothing could
- *   resolve.
- * @returns {Promise<AskAnswer>} Resolves on an answer, a skip, or the turn being stopped (`{
- *   answer: null, skipped: false }` — the shape the tool reports as a failure).
- */
-export function askUser(ask: PendingAsk, signal?: AbortSignal): Promise<AskAnswer> {
-  return new Promise<AskAnswer>((resolve) => {
-    state.pending = ask;
-    settle = resolve;
-
-    if (signal?.aborted) {
-      clear();
-      resolve({ answer: null, skipped: false });
-      return;
-    }
-    if (signal) {
-      const onAbort = () => {
-        cancelAsk();
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-      detachAbort = () => signal.removeEventListener("abort", onAbort);
-    }
-  });
-}
-
-/**
- * Answer the outstanding question.
- *
- * @param {string} text
- * @returns {boolean} False when nothing was pending, so a caller can fall through to a normal send.
- */
-export function answerAsk(text: string): boolean {
-  if (!settle) {
-    return false;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: text, skipped: false });
-  return true;
-}
-
-/**
- * Decline to answer — "you decide". Settles as a success, so the turn carries on.
- *
- * @returns {boolean} False when nothing was pending.
- */
-export function skipAsk(): boolean {
-  if (!settle) {
-    return false;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: null, skipped: true });
-  return true;
-}
-
-/** Settle an outstanding question as unanswered. Called from `stop()` and from the turn's abort. */
-export function cancelAsk(): void {
-  if (!settle) {
-    return;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: null, skipped: false });
-}
-
-/** Drop any outstanding question without settling a turn. For New Chat and for tests. */
-export function resetAsk(): void {
-  cancelAsk();
-  clear();
-}
-
 /**
  * Register `ask_user` into a tool registry.
  *
@@ -163,24 +42,12 @@ export function resetAsk(): void {
  *
  * @param {Pick<ToolRegistry, "register">} registry
  */
-/** What the host that registers the question tool may hook. */
-export interface AskToolOptions {
-  /**
-   * Called once a question has been put to the author, before the turn waits on the answer. A host
-   * saves the conversation here: a turn suspended on a person may wait for as long as they like,
-   * and a reload in the meantime must still find the question to restore as open (`specs/ai.md`
-   * §3.4).
-   */
-  onPending?: () => void;
-}
-
-export function registerAskTool(
-  registry: Pick<ToolRegistry, "register">,
-  { onPending }: AskToolOptions = {},
-): void {
+export function registerAskTool(registry: Pick<ToolRegistry, "register">): void {
   registry.register(
     createToolDefinition({
       name: "ask_user",
+      title: "Ask the user",
+      annotations: JX_TOOL_FACTS.ask_user.annotations,
       // It suspends the turn on the author, so a round that only asked spends no work budget.
       interactive: true,
       description:
@@ -212,43 +79,32 @@ export function registerAskTool(
         },
         required: ["question"],
       },
-      execute: async (args, ctx) => {
+      interaction(args) {
         /* Every field is any JSON value, narrowed by a guard rather than by `?.`. The registry's
-           `validate()` is "a lightweight structural check, not a JSON Schema validator",
-           `strict: false` skips it entirely, and this tool may be registered into someone else's
-           registry — so an argument that is a number is a case, not an impossibility. Optional
-           chaining guards null, not type: `context?.trim()` threw on one. */
+           `validate()` is "a lightweight structural check, not a JSON Schema validator", and this
+           tool may be registered into someone else's registry, so an argument that is a number is
+           a case, not an impossibility. Optional chaining guards null, not type: `context?.trim()`
+           threw on one. */
         const { question, options, context } = args;
         if (!isString(question) || !question.trim()) {
-          return toolError('Pass "question" — the question to put to the user.');
-        }
-        if (isAwaitingAnswer()) {
-          return toolError("A question is already waiting for the user.");
+          return { refusal: 'Pass "question" — the question to put to the user.' };
         }
         const choices = Array.isArray(options)
           ? options
               .filter((o): o is string => isString(o) && o.trim().length > 0)
               .slice(0, MAX_OPTIONS)
           : [];
-
-        const answering = askUser(
-          {
-            context: isString(context) ? context.trim() : "",
-            /* The tool-call id, so the chip the transcript draws and the question this registers
-               are the same thing. Without it a restored, permanently unanswered question would
-               render identically to the live one. */
-            id: ctx.callId,
-            options: choices,
-            question: question.trim(),
-          },
-          ctx.signal,
-        );
-        // The question is published by now (`askUser` sets it synchronously); the answer is not.
-        if (isAwaitingAnswer()) {
-          onPending?.();
-        }
-        const { answer, skipped } = await answering;
-
+        return {
+          context: isString(context) ? context.trim() : "",
+          kind: "question",
+          options: choices,
+          question: question.trim(),
+        };
+      },
+      settle(_args, response) {
+        /* SAFETY: `ask_user` only ever asks a question, so the response the invoker hands back is
+           the answer to one. */
+        const { answer, skipped } = response as Extract<InteractionResponse, { kind: "question" }>;
         if (skipped) {
           /* A success: the model asked, and "you decide" is an answer. Rendering it as a failure
              would have the model apologise for having asked a fair question. */
@@ -262,6 +118,8 @@ export function registerAskTool(
         }
         return toolSuccess({ answer, skipped: false }, `The user answered: "${answer}"`);
       },
+      // Never reached through the invoker, which settles an interaction instead of executing it.
+      execute: () => toolError("ask_user needs a person, and none is available here."),
     }),
   );
 }

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.",