@jxsuite/ai 0.39.5 → 0.41.0

package/src/jx-tools/facts.ts

@@ -0,0 +1,96 @@
+/**
+ * What each of the Jx assistant's tools does to the world (specs/ai.md §3.10), as data: the four
+ * behaviour hints, and the one effect a host's undo and approvals are decided by.
+ *
+ * Keyed by tool name rather than carried by each tool's module so one table can be read and
+ * reviewed whole, and so a tool that has none is a test failure rather than a silent default.
+ *
+ * @module @jxsuite/ai/jx-tools
+ * @license MIT
+ */
+
+import type { ToolAnnotations } from "../tools.ts";
+
+/**
+ * Where a tool's change lands: nowhere (`none`), in the host's view (`ui`), in the open document
+ * (`document`, which its history can undo), in the project's configuration (`project`, likewise),
+ * or straight on disk (`disk`, which nothing undoes).
+ */
+export type ToolEffect = "none" | "ui" | "document" | "project" | "disk";
+
+/** One tool's facts. */
+export interface ToolFacts {
+  readonly annotations: ToolAnnotations;
+  readonly effect: ToolEffect;
+}
+
+/** Facts from the hints in the order MCP names them: read-only, destructive, idempotent, open-world. */
+function facts(
+  readOnlyHint: boolean,
+  destructiveHint: boolean,
+  idempotentHint: boolean,
+  openWorldHint: boolean,
+  effect: ToolEffect,
+): ToolFacts {
+  return { annotations: { destructiveHint, idempotentHint, openWorldHint, readOnlyHint }, effect };
+}
+
+const INTERACTION = facts(true, false, false, false, "none");
+const READ = facts(true, false, true, false, "none");
+const DISK_OVERWRITE = facts(false, true, true, false, "disk");
+const BOOTSTRAP = facts(false, false, false, true, "disk");
+const TREE_IDEMPOTENT = facts(false, false, true, false, "document");
+const TREE = facts(false, false, false, false, "document");
+const UI = facts(false, false, true, false, "ui");
+const PROJECT = facts(false, false, true, false, "project");
+
+/** Every tool the Jx assistant offers, by name. */
+export const JX_TOOL_FACTS = {
+  add_child: TREE,
+  /* Creates a file under a name the arguments choose, and refuses one that exists: never an
+     overwrite, but not a call to repeat either. */
+  add_new: facts(false, false, false, false, "disk"),
+  add_project_locale: PROJECT,
+  add_state: TREE_IDEMPOTENT,
+  ask_user: INTERACTION,
+  check_accessibility: READ,
+  check_popovers: READ,
+  create_component: DISK_OVERWRITE,
+  create_page: DISK_OVERWRITE,
+  create_project: BOOTSTRAP,
+  delete_node: facts(false, true, false, false, "document"),
+  disable_extension: PROJECT,
+  duplicate_node: TREE,
+  // Installs a package, which reaches the registry and which undo cannot take back.
+  enable_extension: facts(false, true, true, true, "disk"),
+  import_site: BOOTSTRAP,
+  list_files: READ,
+  list_starters: READ,
+  move_node: TREE,
+  open_document: UI,
+  read_document: READ,
+  read_file: READ,
+  search_files: READ,
+  select_node: UI,
+  set_canvas_mode: UI,
+  set_property: TREE_IDEMPOTENT,
+  set_style: TREE_IDEMPOTENT,
+  set_text: TREE_IDEMPOTENT,
+  update_state: TREE_IDEMPOTENT,
+  validate_redirects: READ,
+  write_file: DISK_OVERWRITE,
+} satisfies Readonly<Record<string, ToolFacts>>;
+
+/** The name of a tool the Jx assistant offers. */
+export type JxToolName = keyof typeof JX_TOOL_FACTS;
+
+/**
+ * The facts of the tool named `name`, or undefined for a name the table does not know.
+ *
+ * @param {string} name
+ * @returns {ToolFacts | undefined}
+ */
+export function toolFacts(name: string): ToolFacts | undefined {
+  /* SAFETY: `Object.hasOwn` has just proven `name` is one of the table's own keys. */
+  return Object.hasOwn(JX_TOOL_FACTS, name) ? JX_TOOL_FACTS[name as JxToolName] : undefined;
+}

package/src/jx-tools/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@jxsuite/ai/jx-tools`: the assistant's document tools, portable to any host (specs/ai.md §3.9).
+ *
+ * Each tree tool is a pure producer of `@jxsuite/schema/doc-ops` ops, and a {@link DocumentHost}
+ * applies them in its own transaction: Studio's tab history, a file on disk, a room's document.
+ * Worker-safe: the module graph is this directory, `../tools.ts` and two `@jxsuite/schema` leaves.
+ *
+ * @module @jxsuite/ai/jx-tools
+ * @license MIT
+ * @docs extending/embedding/assistant-harness
+ */
+
+export { coerceIndex } from "@jxsuite/schema/doc-ops";
+export { DOC_TOOLS } from "./doc-tools.ts";
+export { docToolEntries, FROZEN_SENTENCE } from "./entries.ts";
+export { JX_TOOL_FACTS, toolFacts } from "./facts.ts";
+export type { JxToolName, ToolEffect, ToolFacts } from "./facts.ts";
+export type {
+  DocEdit,
+  DocTool,
+  DocToolName,
+  DocumentHost,
+  DocumentRef,
+  EditMeta,
+  EditReceipt,
+  SelectionEffect,
+  Undoability,
+  WriteReporter,
+} from "./types.ts";

package/src/jx-tools/types.ts

@@ -0,0 +1,118 @@
+/**
+ * The contracts of the portable document tools (specs/ai.md §3.9): what a producer answers, and
+ * what a host provides to run one.
+ *
+ * @module @jxsuite/ai/jx-tools
+ * @license MIT
+ */
+
+import type { JxDocOp } from "@jxsuite/schema/doc-ops";
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import type { Actor, JSONSchema, ToolArguments, ToolContext, ToolResult } from "../tools.ts";
+
+/** How an edit carries the host's selection across it. */
+export type SelectionEffect =
+  /** The selection is untouched. */
+  | { readonly kind: "keep" }
+  /** Every selected path at or under one of `under` is dropped: what it named was replaced. */
+  | { readonly kind: "prune"; readonly under: readonly JxPath[] }
+  /** A selection whose primary path is `from` moves to `to`, the moved node's post-edit path. */
+  | { readonly kind: "follow"; readonly from: JxPath; readonly to: JxPath };
+
+/** What a producer answers: the ops that make the edit, or why it refuses. */
+export type DocEdit =
+  | {
+      readonly ok: true;
+      readonly ops: readonly JxDocOp[];
+      /** The sentence the model reads on success, naming where the edit landed. */
+      readonly summary: string;
+      readonly selection: SelectionEffect;
+    }
+  | { readonly ok: false; readonly error: string };
+
+/** The tree tools a producer exists for. */
+export type DocToolName =
+  | "set_property"
+  | "set_style"
+  | "set_text"
+  | "add_child"
+  | "move_node"
+  | "add_state"
+  | "update_state";
+
+/** A tree tool as data: what the model is told, and the pure function that plans its edit. */
+export interface DocTool {
+  readonly name: DocToolName;
+  /** A person-facing name for the tool. */
+  readonly title: string;
+  readonly description: string;
+  readonly parameters: JSONSchema;
+  /**
+   * Pure: reads `doc`, never writes it, and answers the ops the edit is. A refusal is an answer,
+   * not a throw, so a host can run it once to check and again inside its transaction.
+   */
+  readonly edit: (doc: Readonly<JxMutableNode>, args: ToolArguments) => DocEdit;
+}
+
+/** A document a host has resolved for one call. Compared by identity within that call. */
+export interface DocumentRef {
+  readonly id: string;
+  /** Its project-relative path, or null for one never saved. */
+  readonly path: string | null;
+}
+
+/** Who is editing, for the host's history and attribution. */
+export interface EditMeta {
+  readonly actor: Actor;
+  readonly callId: string;
+  readonly tool: string;
+}
+
+/** What a host's edit did. */
+export type EditReceipt =
+  | { readonly applied: true; readonly changed: boolean }
+  | {
+      readonly applied: false;
+      /**
+       * `frozen`: the document refuses structural edits for now (a collaborator holds its source).
+       * `refused`: the producer refused against the document as it stood at commit. `invalid`: a
+       * host that cannot undo refused an edit that would leave the document invalid. `not-open`:
+       * the document is no longer the host's.
+       */
+      readonly reason: "frozen" | "refused" | "invalid" | "not-open";
+      readonly message: string;
+    };
+
+/**
+ * Whether a host can take an edit back. A host that can (`document`) commits and then reports what
+ * the edit broke; one that cannot (`none`) must validate before it commits.
+ */
+export type Undoability = "document" | "none";
+
+/** Where the tree tools read and write a document. */
+export interface DocumentHost {
+  readonly undoable: Undoability;
+  /** The document this call addresses, or the sentence refusing the call when there is none. */
+  readonly resolve: (ctx: ToolContext) => DocumentRef | string;
+  /** The document as it stands: plain data, never a reactive proxy. */
+  readonly snapshot: (ref: DocumentRef) => Readonly<JxMutableNode>;
+  /**
+   * Read the document, call `produce`, and apply its ops synchronously, with no await between them,
+   * so nothing can change the document between the plan and the write. A returned promise may
+   * settle later, for persistence only.
+   */
+  readonly edit: (
+    ref: DocumentRef,
+    produce: (doc: Readonly<JxMutableNode>) => DocEdit,
+    meta: EditMeta,
+  ) => EditReceipt | Promise<EditReceipt>;
+}
+
+/**
+ * What brackets a write: the document's standing before it (`Before`, whatever the host's verdict
+ * compares), and the verdict after it.
+ */
+export interface WriteReporter<Before> {
+  readonly before: (ref: DocumentRef) => Promise<Before>;
+  readonly after: (ref: DocumentRef, before: Before, summary: string) => Promise<ToolResult>;
+}

package/src/tools.ts

@@ -61,10 +61,70 @@ export interface JSONSchema {
  */
 export type ToolArguments = Readonly<Record<string, JsonValue | undefined>>;
 
+/**
+ * What a tool does to the world, as MCP's four behaviour hints name it (specs/ai.md §3.10). Every
+ * hint is stated, never left to a default: a host decides approvals and an MCP client its warnings
+ * from them.
+ */
+export interface ToolAnnotations {
+  /** It changes nothing. */
+  readonly readOnlyHint: boolean;
+  /** It may destroy or overwrite something a person made. */
+  readonly destructiveHint: boolean;
+  /** Calling it twice with the same arguments does what calling it once did. */
+  readonly idempotentHint: boolean;
+  /** It reaches outside the project (the network, an installer). */
+  readonly openWorldHint: boolean;
+}
+
+/** Why a call needs the author's approval before it runs. */
+export type ApprovalReason = "destructive" | "not-undoable" | "open-world";
+
+/** What a call asks a person, before any of the tool's own code runs (specs/ai.md §3.11). */
+export type InteractionRequest =
+  | {
+      readonly kind: "question";
+      readonly question: string;
+      /** Short answers offered as choices; a person may always answer in their own words. */
+      readonly options: readonly string[];
+      /** One line of why the question is being asked. */
+      readonly context: string;
+    }
+  | {
+      readonly kind: "approval";
+      readonly tool: string;
+      readonly title: string;
+      /** What the call would do, for the person deciding. */
+      readonly summary: string;
+      readonly reason: ApprovalReason;
+    };
+
+/** A person's answer to an {@link InteractionRequest}. */
+export type InteractionResponse =
+  /** `answer: null` with `skipped` is "you decide"; with neither, the question went unanswered. */
+  | { readonly kind: "question"; readonly answer: string | null; readonly skipped: boolean }
+  | { readonly kind: "approval"; readonly approved: boolean };
+
+/** Whether a call may run: as it is, never, or once the author approves it. */
+export type ApprovalDecision =
+  | { readonly kind: "proceed" }
+  | { readonly kind: "deny"; readonly message: string }
+  | { readonly kind: "confirm"; readonly reason: ApprovalReason; readonly summary: string };
+
+/** Decides, per call, whether it needs the author's approval before it runs. */
+export type ApprovalPolicy = (definition: ToolDefinition, args: ToolArguments) => ApprovalDecision;
+
+/** The policy that approves every call: what a host with no approvals runs. */
+export const proceedAlways: ApprovalPolicy = () => ({ kind: "proceed" });
+
 export interface ToolDefinition {
   name: string;
+  /** A person-facing name for the tool. A catalog requires it. */
+  title?: string;
   description: string;
   parameters: JSONSchema;
+  /** Its behaviour hints. A catalog requires them. */
+  annotations?: ToolAnnotations;
   strict: boolean;
   llmStrict: boolean;
   /**
@@ -72,6 +132,14 @@ export interface ToolDefinition {
    * made only such calls does not spend the turn's work budget.
    */
   interactive?: boolean;
+  /**
+   * What the call asks a person, or the sentence refusing the call (`refusal`). A tool that
+   * declares it is never executed by the invoker: the person's answer goes to `settle`, so no tool
+   * body awaits a person.
+   */
+  interaction?: (args: ToolArguments) => InteractionRequest | { readonly refusal: string };
+  /** The result of a call to an `interaction` tool, given the person's answer. */
+  settle?: (args: ToolArguments, response: InteractionResponse) => ToolResult;
   execute: (args: ToolArguments, ctx: ToolContext) => Promise<ToolResult> | ToolResult;
 }
 
@@ -129,6 +197,10 @@ export function toolError(error: string): ToolResult {
  *   (default false). Only enable if the parameter schema is OpenAI-strict-compliant
  *   (additionalProperties:false everywhere, all properties in `required`, every property typed).
  * @param {boolean} [opts.interactive] - The call suspends the turn on a person (`ask_user`)
+ * @param {string} [opts.title] - A person-facing name, which a catalog requires
+ * @param {ToolAnnotations} [opts.annotations] - Its behaviour hints, which a catalog requires
+ * @param {ToolDefinition["interaction"]} [opts.interaction] - What the call asks a person
+ * @param {ToolDefinition["settle"]} [opts.settle] - The result, given the person's answer
  * @param {(args: ToolArguments, ctx: ToolContext) => Promise<ToolResult> | ToolResult} opts.execute -
  *   The tool implementation, handed the call's context
  * @returns {ToolDefinition}
@@ -140,6 +212,10 @@ export function createToolDefinition({
   strict = true,
   llmStrict = false,
   interactive,
+  title,
+  annotations,
+  interaction,
+  settle,
   execute,
 }: {
   name: string;
@@ -148,6 +224,10 @@ export function createToolDefinition({
   strict?: boolean;
   llmStrict?: boolean;
   interactive?: boolean;
+  title?: string;
+  annotations?: ToolAnnotations;
+  interaction?: ToolDefinition["interaction"];
+  settle?: ToolDefinition["settle"];
   execute: (args: ToolArguments, ctx: ToolContext) => Promise<ToolResult> | ToolResult;
 }): ToolDefinition {
   const definition: ToolDefinition = { name, description, parameters, strict, llmStrict, execute };
@@ -155,6 +235,18 @@ export function createToolDefinition({
   if (interactive !== undefined) {
     definition.interactive = interactive;
   }
+  if (title !== undefined) {
+    definition.title = title;
+  }
+  if (annotations !== undefined) {
+    definition.annotations = annotations;
+  }
+  if (interaction !== undefined) {
+    definition.interaction = interaction;
+  }
+  if (settle !== undefined) {
+    definition.settle = settle;
+  }
   return definition;
 }
 
@@ -450,13 +542,25 @@ export interface ToolCall {
   readonly argumentsText: string;
 }
 
-/** What invoking a call produced. `executed` is false when the registry was never reached. */
-export interface InvokeOutcome {
-  readonly status: "done";
-  readonly result: ToolResult;
-  readonly executed: boolean;
+/**
+ * What invoking a call produced: a result (`executed` is false when the tool's body never ran), or
+ * the question a person must answer before it can be invoked again with their response.
+ */
+export type InvokeOutcome =
+  | { readonly status: "done"; readonly result: ToolResult; readonly executed: boolean }
+  | { readonly status: "needs_input"; readonly request: InteractionRequest };
+
+/** How a call is invoked: the host's approval policy, and a person's answer on a second invoke. */
+export interface InvokeOptions {
+  /** Defaults to {@link proceedAlways}. */
+  readonly approval?: ApprovalPolicy;
+  /** The answer to the request a first invoke returned as `needs_input`. */
+  readonly response?: InteractionResponse;
 }
 
+/** What a declined call answers. */
+export const DECLINED_SENTENCE = "The author declined this call.";
+
 /**
  * A result as JSON would carry it: the serialized bytes are unchanged, and `data` becomes plain
  * JSON, so the result survives any transport that serializes it.
@@ -562,31 +666,45 @@ function parseArguments(text: string): ToolArguments {
 }
 
 /**
- * Run one model call through a registry: parse its arguments, execute it with its context, and
- * return the result as JSON would carry it. Never throws: a failure is a result the model reads.
+ * Run one model call through a registry, in order: parse its arguments, put an interaction tool's
+ * question to a person or settle it with their answer, ask the approval policy, execute it with its
+ * context, and return the result as JSON would carry it (specs/ai.md §3.11). Never throws: a
+ * failure is a result the model reads.
  *
  * Arguments that do not parse answer `Failed to parse arguments: <reason>`, with the same prefix
- * for a non-object, so the model reads both as one kind of mistake. The registry keeps its own
- * texts for an unknown tool, failed validation, a gate and a tool that threw. A registry that
- * itself throws is answered with the parse prefix too, as the agent loop always answered it, and a
- * result JSON cannot carry is answered as one that cannot be serialized.
+ * for a non-object, so the model reads both as one kind of mistake. A call that needs a person
+ * answers `needs_input` before any tool code runs; the caller invokes it again with the response.
+ * The registry keeps its own texts for an unknown tool, failed validation, a gate and a tool that
+ * threw. A registry that itself throws is answered with the parse prefix too, as the agent loop
+ * always answered it, and a result JSON cannot carry is answered as one that cannot be serialized.
  *
  * @param {ToolRegistry} registry
  * @param {ToolCall} call
  * @param {ToolContext} ctx - The call's context, forwarded to the tool unchanged
+ * @param {InvokeOptions} [options]
  * @returns {Promise<InvokeOutcome>}
  */
 export async function invokeTool(
   registry: ToolRegistry,
   call: ToolCall,
   ctx: ToolContext,
+  { approval = proceedAlways, response }: InvokeOptions = {},
 ): Promise<InvokeOutcome> {
   let executed = false;
   let result: ToolResult;
   try {
     const args = parseArguments(call.argumentsText);
-    executed = true;
-    result = await registry.execute(call.name, args, ctx);
+    const definition = registry.getDefinition(call.name);
+    const step = definition ? beforeExecute(registry, definition, args, approval, response) : null;
+    if (step?.status === "needs_input") {
+      return step;
+    }
+    if (step) {
+      ({ result } = step);
+    } else {
+      executed = true;
+      result = await registry.execute(call.name, args, ctx);
+    }
   } catch (error) {
     result = toolError(`Failed to parse arguments: ${messageOf(error)}`);
   }
@@ -605,3 +723,73 @@ export async function invokeTool(
     };
   }
 }
+
+/**
+ * The steps before a body runs: an interaction tool is asked or settled and never executed, and any
+ * other tool is approved, denied, or put to the author. Null means execute.
+ */
+function beforeExecute(
+  registry: ToolRegistry,
+  definition: ToolDefinition,
+  args: ToolArguments,
+  approval: ApprovalPolicy,
+  response: InteractionResponse | undefined,
+): InvokeOutcome | null {
+  const { interaction, settle } = definition;
+  if (interaction && settle) {
+    const validation = registry.validate(definition.name, args);
+    if (!validation.valid) {
+      return refused(`Validation failed: ${(validation.errors || []).join("; ")}`);
+    }
+    if (response) {
+      return {
+        status: "done",
+        result: settleSafely(definition.name, settle, args, response),
+        executed: false,
+      };
+    }
+    const request = interaction(args);
+    return "refusal" in request ? refused(request.refusal) : { status: "needs_input", request };
+  }
+  const decision = approval(definition, args);
+  if (decision.kind === "deny") {
+    return refused(decision.message);
+  }
+  if (decision.kind === "confirm") {
+    if (!response) {
+      return {
+        status: "needs_input",
+        request: {
+          kind: "approval",
+          reason: decision.reason,
+          summary: decision.summary,
+          title: definition.title ?? definition.name,
+          tool: definition.name,
+        },
+      };
+    }
+    if (response.kind !== "approval" || !response.approved) {
+      return refused(DECLINED_SENTENCE);
+    }
+  }
+  return null;
+}
+
+/** A result no body produced. */
+function refused(error: string): InvokeOutcome {
+  return { status: "done", result: toolError(error), executed: false };
+}
+
+/** `settle`'s result, or the execution error a registry would have answered for a throw. */
+function settleSafely(
+  name: string,
+  settle: NonNullable<ToolDefinition["settle"]>,
+  args: ToolArguments,
+  response: InteractionResponse,
+): ToolResult {
+  try {
+    return settle(args, response);
+  } catch (error) {
+    return toolError(`Tool "${name}" execution error: ${messageOf(error)}`);
+  }
+}