@jxsuite/studio 4.0.0 → 5.0.0

package/src/services/a11y-report.ts

@@ -25,16 +25,32 @@
  * them means running the page and axe-core over it, which is a different program with a different
  * lifetime. `unavailableChecks()` names them so the absence is stated rather than implied.
  *
+ * **The structural rules live in `@jxsuite/schema/a11y`** — an unnamed control, an image with no
+ * alt, an aria reference to an id nothing has, a tab, menu item or option outside its container, a
+ * tablist with no selected tab, an unnamed dialog, aria-activedescendant on an element that cannot
+ * take focus — so `jx validate`, the kit's conformance tests and this report judge a document alike
+ * (spec §8.8). What stays here is what needs the whole page rather than a node: the heading
+ * outline, duplicate ids, the document language, link wording, autocomplete purposes and media.
+ *
  * @docs studio/interface/problems-and-progress
  */
 
 import { activeTab } from "../workspace/workspace";
-import { clearProblems, notify } from "./notify";
+import { clearProblems, notify, problemFindings } from "./notify";
+import { findA11yDefects } from "@jxsuite/schema/a11y";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { JxElement } from "@jxsuite/schema/types";
 
 /** WCAG success criteria these checks bind to, by the id ATAG B.3.1 asks a report to carry. */
-export type A11yCriterion = "1.1.1" | "1.3.1" | "1.3.5" | "2.4.4" | "2.4.6" | "3.1.1" | "4.1.2";
+export type A11yCriterion =
+  | "1.1.1"
+  | "1.3.1"
+  | "1.3.5"
+  | "2.1.1"
+  | "2.4.4"
+  | "2.4.6"
+  | "3.1.1"
+  | "4.1.2";
 
 /** One thing that is wrong with the document, and — where one exists — the command that fixes it. */
 export interface A11yFinding {
@@ -59,8 +75,23 @@ export interface A11yFinding {
   action?: string;
 }
 
-/** Elements whose whole purpose is an image, and which therefore owe alternative text. */
-const IMAGE_TAGS = new Set(["img", "area", "input-image"]);
+/**
+ * Whether the element's whole purpose is an image, so its `alt` is the text a reader hears.
+ *
+ * `<input type="image">` is one of the three elements HTML gives an `alt`, and it is a TYPE rather
+ * than a tag. The set this replaced spelled it `"input-image"` alongside `img` and `area` — a tag
+ * name no document can have — so the wording check below never once ran on a submit image.
+ *
+ * @param {JxElement} node
+ * @param {string} tag The node's lowercased tag name.
+ * @returns {boolean}
+ */
+function isImage(node: JxElement, tag: string): boolean {
+  if (tag === "img" || tag === "area") {
+    return true;
+  }
+  return tag === "input" && literal(node, "type")?.toLowerCase() === "image";
+}
 
 /** Controls that owe an accessible name. */
 const CONTROL_TAGS = new Set(["input", "select", "textarea", "button"]);
@@ -170,20 +201,14 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
     const where = tag === "" ? `element ${index}` : `<${tag}>`;
 
     // ── 1.1.1 Non-text Content ────────────────────────────────────────────────
-    if (IMAGE_TAGS.has(tag)) {
+    if (isImage(node, tag)) {
       const alt = literal(node, "alt");
-      if (!has(node, "alt")) {
-        findings.push({
-          criterion: "1.1.1",
-          detail:
-            "A screen reader falls back to reading the file name, which is rarely useful and " +
-            "sometimes misleading. An image that is purely decorative takes an EMPTY alt, which " +
-            "is a decision — the absent attribute is not.",
-          id: `img-no-alt:${index}`,
-          message: `${where} has no alt text.`,
-          severity: "error",
-        });
-      } else if (alt !== null && /^(image|photo|picture|graphic|icon)\b/i.test(alt.trim())) {
+      /*
+       * A missing alt is the schema engine's: `img-alt-missing` for an `<img>`, and
+       * `interactive-unnamed` for the two that are also controls, an `<area href>` and an
+       * `<input type="image">`. Only the WORDING is judged here, which no engine rule does.
+       */
+      if (alt !== null && /^(image|photo|picture|graphic|icon)\b/i.test(alt.trim())) {
         findings.push({
           criterion: "1.1.1",
           detail:
@@ -233,19 +258,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
     if (CONTROL_TAGS.has(tag)) {
       const type = literal(node, "type")?.toLowerCase() ?? "";
       const selfLabelling = tag === "button" || SELF_LABELLING_INPUTS.has(type);
-      const labelled = hasAccessibleName(node) || has(node, "id");
-      if (!selfLabelling && !labelled) {
-        findings.push({
-          criterion: "4.1.2",
-          detail:
-            'A control with no name is announced as its type alone — "edit", "combo box" — ' +
-            "which tells a reader nothing about what to type. Give it an aria-label, or an id a " +
-            "<label> points at.",
-          id: `control-unnamed:${index}`,
-          message: `${where} has no label.`,
-          severity: "error",
-        });
-      }
+      // An unnamed control is the schema rule `interactive-unnamed`, with `<label for>` resolved.
       // 1.3.5: a field asking for the user's own data should say which (autocomplete).
       if (tag === "input" && !selfLabelling && !has(node, "autocomplete")) {
         const name = `${literal(node, "name") ?? ""} ${literal(node, "id") ?? ""}`.toLowerCase();
@@ -269,17 +282,8 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
         .toLowerCase()
         .replaceAll(/[^a-z ]/g, "")
         .trim();
-      if (!hasAccessibleName(node)) {
-        findings.push({
-          criterion: "4.1.2",
-          detail:
-            "A link with no text is announced as its URL, one character at a time in some " +
-            "readers. If the link is an icon, give it an aria-label.",
-          id: `link-unnamed:${index}`,
-          message: "A link has no text.",
-          severity: "error",
-        });
-      } else if (VAGUE_LINK_TEXT.has(text)) {
+      // A link with no text is the schema rule `interactive-unnamed`; only the wording is judged here.
+      if (hasAccessibleName(node) && VAGUE_LINK_TEXT.has(text)) {
         findings.push({
           criterion: "2.4.4",
           detail:
@@ -363,7 +367,38 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
     });
   }
 
-  return findings;
+  // The structural rules, from the engine every judge of a Jx document shares.
+  for (const defect of findA11yDefects(doc)) {
+    findings.push({
+      criterion: defect.criterion as A11yCriterion,
+      detail: defect.detail,
+      id: `${defect.rule}:${defect.path.join("/")}`,
+      message: defect.message,
+      severity: defect.severity,
+    });
+  }
+  return distinctIds(findings);
+}
+
+/**
+ * Give every finding an id no other finding shares.
+ *
+ * A Problem key REPLACES rather than stacks, so two findings under one id are one row, and the
+ * author is told about the last of them and never hears about the rest. Two rules produce
+ * duplicates honestly: `aria-target-missing` files one per token that resolves to nothing, so
+ * `aria-labelledby="a b c"` is three at one rule and one path; and `duplicate-id` files one per
+ * extra element sharing an id, so three elements are two findings under one id. The ordinal is
+ * applied to every finding rather than to one loop, because "a key names a finding" is either true
+ * of all of them or it is not the rule it claims to be. The first keeps its bare id, so nothing
+ * already distinct moves and no existing key changes.
+ */
+function distinctIds(findings: A11yFinding[]): A11yFinding[] {
+  const seen = new Map<string, number>();
+  return findings.map((finding) => {
+    const before = seen.get(finding.id) ?? 0;
+    seen.set(finding.id, before + 1);
+    return before === 0 ? finding : { ...finding, id: `${finding.id}#${before}` };
+  });
 }
 
 /** A check this program cannot run, and the honest reason. */
@@ -464,8 +499,30 @@ export function a11yCommands(): AnyCommand[] {
         description:
           "Check the open document for accessibility problems an author can fix — missing alt " +
           "text, unlabelled controls, skipped heading levels, vague link text, duplicate ids — " +
-          "and file each as a Problem naming its WCAG criterion.",
+          "and file each as a Problem naming its WCAG criterion. The findings come back as data.",
         name: "check_accessibility",
+        /* A read the model has no other way to perform. The report is the PANEL's own read — the
+           Problems store filtered by this source — minus the unchecked-coverage rows, which are
+           about what this run could not see and are counted as such rather than listed as
+           defects. "Check this page and fix what you find" is two rounds, not a parse of a toast. */
+        report: () => {
+          const unchecked = unavailableChecks().length;
+          const findings = problemFindings(A11Y_PROBLEM_SOURCE).filter(
+            (finding) => !finding.key?.startsWith("a11y.unavailable."),
+          );
+          const n = findings.length;
+          const coverage =
+            unchecked === 0
+              ? ""
+              : ` ${unchecked} check${unchecked === 1 ? "" : "s"} could not run and ${unchecked === 1 ? "is" : "are"} listed in Problems as such.`;
+          return {
+            data: findings,
+            summary:
+              n === 0
+                ? `No accessibility problems found in this document.${coverage}`
+                : `Filed ${n} accessibility problem${n === 1 ? "" : "s"} in Problems.${coverage}`,
+          };
+        },
       },
       category: "Document",
       group: "2_document",

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

@@ -0,0 +1,468 @@
+/**
+ * Ai-command-tools.ts — the assistant's tools that ARE command records.
+ *
+ * A `ToolRegistry` that is a VIEW over this window's active command registry, in the idiom of
+ * `services/automation.ts`'s `scriptableCommands()`: nothing is registered here, ever. Every call to
+ * `listForLLM()` enumerates the records that carry an `aiTool` projection and builds one function
+ * schema per record whose `parameters` is the record's own `args` object — by reference, so a
+ * `derivedEnumProperty` getter serialises live on every agent-loop round — whose `description` is
+ * the record's, and which is advertised exactly while `registry.isEnabled(id)` holds. `execute` is
+ * `registry.run(id, args)`.
+ *
+ * **Why a view and not a registration.** `const assistant = createDocumentAssistant()` runs at
+ * module load of `panels/ai-panel.ts`, before the bootstrap composes the registry, so a
+ * registration step would have to import `app-commands.ts` (every command module into the
+ * assistant's import graph) and read `report` from a record built with `noopCommandDeps` — a
+ * second instance of every record, whose closures are not the app's. A view has neither problem,
+ * and it cannot be dormant: issue 273 was forty-seven declarations that reached the assistant from
+ * none of them, because each waited on a hand-registered tool nobody wrote. There is no
+ * registration step between `aiTool` and the tool, so there is nothing to omit.
+ *
+ * **What the model reads.** A refusal is the person's own sentence: `CommandUnavailableError.message`
+ * IS `refusalSentence`, and a `RangeError` from `coerceArgs` (which `registry.run` applies for
+ * every caller) or from inside `run` already names the value and the declared list. Both pass
+ * through untouched. There is deliberately no pre-check with `refusalMessage` — `run` refuses with
+ * the same sentence, and a second call site for one predicate is precisely the divergence
+ * `specs/studio-ui-guidelines.md` §12.4 is about. And because this module owns `execute`,
+ * `@jxsuite/ai`'s `Tool "<name>" execution error:` prefix never wraps a refusal.
+ *
+ * **The write witness.** A record with `undo: "document"` is held to having written: `transactDoc`
+ * replaces the document's root reference on every applied transaction (`tabs/transact.ts`), so an
+ * unchanged reference after `run` means the collab freeze refused it, or `run` returned early, and
+ * the model is told "changed nothing" rather than congratulated. This is what closes the
+ * phantom-success finding for every bridged document write, not just the one tool it was found on.
+ *
+ * **`validate()` is a no-op, on purpose.** `@jxsuite/ai`'s validator never checks `enum` and treats
+ * a required `null` as missing (`packages/ai/src/tools.ts`), which would refuse `select_node
+ * { path: null }`. The registry's coercion is the single validator, so every projected tool is
+ * `strict: false`.
+ *
+ * @license MIT
+ */
+
+import { toolError } from "@jxsuite/ai/tools";
+import type { ToolDefinition, ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
+import { activeRegistry } from "../commands/active-registry";
+import { argsSchema } from "../commands/command-args";
+import { inCanvas } from "../commands/context";
+import { toRaw } from "../reactivity";
+import { recordWrite } from "./ai-writes";
+import { reportDocumentWrite, snapshotBeforeWrite } from "./ai-write-report";
+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";
+
+/**
+ * The record a selection-level projection composes through.
+ *
+ * The model addresses nodes by path, so a selection verb's tool takes `paths` and the bridge runs
+ * this selector first. "Act on whatever is selected" would be a verb over state the model cannot
+ * observe — the same objection `specs/studio.md` §13.5 raises against a `toggle*` id.
+ */
+export const SELECTOR = "selection.setPaths";
+
+/** What the bridge needs that a command record cannot know: the tab, and the write reporter's deps. */
+export interface CommandToolDeps extends WriteReportDeps {
+  /**
+   * The active tab — the document a `undo: "document"` record wrote, for the witness and the
+   * ledger.
+   */
+  getTab: () => Tab | null;
+}
+
+/** Schema for a record that declares no `args`: an empty object, so the wire shape is uniform. */
+const EMPTY_ARGS = argsSchema({});
+
+/** The loosely-typed view of a record's `args` this module reads. */
+interface ArgsShape {
+  properties?: Record<string, object>;
+  required?: readonly string[];
+}
+
+/**
+ * The selector's own `paths` property object, taken BY REFERENCE from the live record so the
+ * description the model reads is the selector's. `undefined` when the selector is not registered,
+ * in which case no selection-level record can be composed and none is projected.
+ */
+function pathsProperty(registry: CommandRegistry): object | undefined {
+  const args = registry.get(SELECTOR)?.args as ArgsShape | undefined;
+  return args?.properties?.paths;
+}
+
+/**
+ * A selection-level record's parameters: the selector's `paths` in front, REQUIRED, then the
+ * record's own properties. Merging the record's after the selector's is what lets a future
+ * selection verb with an argument of its own compose without a rule change — and `register()`
+ * refuses a selection-level record that declares `paths` itself, so the two cannot collide.
+ */
+function withPaths(paths: object, args: object | undefined): object {
+  const own = (args ?? EMPTY_ARGS) as ArgsShape;
+  return {
+    additionalProperties: false,
+    properties: { paths, ...own.properties },
+    required: ["paths", ...(own.required ?? [])],
+    type: "object",
+  };
+}
+
+/**
+ * The tail every projected description carries, so a record says neither in its own sentence.
+ *
+ * `undo` names what ⌘Z reaches; `destructive` is the same flag the menus derive the danger styling
+ * from. A record with no `undo` is a read or a navigation, and says nothing.
+ */
+function undoSuffix(command: AnyCommand): string {
+  const undo =
+    command.undo === "document"
+      ? " Undo: document."
+      : command.undo === "project"
+        ? " Undo: project."
+        : command.undo === "none"
+          ? " Not undoable."
+          : "";
+  return `${undo}${command.destructive ? " Destructive." : ""}`;
+}
+
+/**
+ * Whether a selection-level projection can be composed and honoured right now: a document tree is
+ * on the canvas (`inCanvas`, the predicate `hasSelection` is built from — read, not respelled) and
+ * the selector is usable, which is "a document is open". The `count > 0` conjunct of the verb's own
+ * `when` is what the bridge satisfies itself by running the selector.
+ */
+function selectionAdvertised(registry: CommandRegistry): boolean {
+  return (
+    inCanvas(registry.context()) &&
+    registry.get(SELECTOR) !== undefined &&
+    registry.isEnabled(SELECTOR)
+  );
+}
+
+/**
+ * Whether one record's tool is advertised this round. For a project- or document-level record it is
+ * the record's own gate, evaluated as the palette evaluates it — a module-state `enablement`
+ * closure included. Selection-level records are the one derived case, above.
+ */
+function advertised(registry: CommandRegistry, command: AnyCommand): boolean {
+  return command.level === "selection"
+    ? selectionAdvertised(registry)
+    : registry.isEnabled(command.id);
+}
+
+/** Every record carrying a projection, enabled or not. */
+function projected(registry: CommandRegistry): AnyCommand[] {
+  return registry.list().filter((command) => command.aiTool !== undefined);
+}
+
+/**
+ * The definition one record projects, or `undefined` for a selection-level record when the selector
+ * it composes through is not registered.
+ */
+function definitionOf(
+  registry: CommandRegistry,
+  command: AnyCommand,
+  execute: (name: string, args: object) => Promise<ToolResult>,
+): ToolDefinition | undefined {
+  const tool = command.aiTool!;
+  let parameters: object;
+  if (command.level === "selection") {
+    const paths = pathsProperty(registry);
+    if (paths === undefined) {
+      return undefined;
+    }
+    parameters = withPaths(paths, command.args);
+  } else {
+    parameters = command.args ?? EMPTY_ARGS;
+  }
+  return {
+    name: tool.name,
+    description: `${tool.description}${undoSuffix(command)}`,
+    parameters: parameters as ToolDefinition["parameters"],
+    strict: false,
+    llmStrict: false,
+    execute: (args) => execute(tool.name, args),
+  };
+}
+
+/**
+ * Pure: the definitions a given registry projects RIGHT NOW (advertised = the record's gate).
+ *
+ * Read by `listForLLM()` and by {@link commandToolBlurbs} both, so the prompt advertises exactly
+ * what the gate will honour — one function, not two that agree until someone edits one.
+ *
+ * @param {CommandRegistry} registry
+ * @param {(name: string, args: object) => Promise<ToolResult>} [execute] What each definition's
+ *   `execute` calls. Defaults to a refusal, so a caller that only reads definitions cannot run
+ *   one.
+ * @returns {ToolDefinition[]}
+ */
+export function advertisedCommandTools(
+  registry: CommandRegistry,
+  execute: (name: string, args: object) => Promise<ToolResult> = async (name) =>
+    toolError(`Tool "${name}" was listed without an executor.`),
+): ToolDefinition[] {
+  const definitions: ToolDefinition[] = [];
+  for (const command of projected(registry)) {
+    if (!advertised(registry, command)) {
+      continue;
+    }
+    const definition = definitionOf(registry, command, execute);
+    if (definition) {
+      definitions.push(definition);
+    }
+  }
+  return definitions;
+}
+
+/** The parameter list a prompt blurb prints: `a, b?` — required names bare, optional ones marked. */
+function signatureOf(parameters: object): string {
+  const shape = parameters as ArgsShape;
+  const required = new Set(shape.required);
+  return Object.keys(shape.properties ?? {})
+    .map((key) => (required.has(key) ? key : `${key}?`))
+    .join(", ");
+}
+
+/**
+ * Pure: the prompt lines for the definitions a registry projects right now, in the hand tools' own
+ * blurb shape: `name(a, b?) — description`. `null` (no registry composed yet) is no lines.
+ *
+ * Why `isEnabled` rather than `isVisible` with a "(not right now)" line: the prompt's invariant is
+ * "advertises exactly what the gate will honour", and with the kept records there is no steady
+ * state in which a projected record is visible and disabled, so the line would be empty in practice
+ * and cost a wasted round when it was not. If a future record wants the palette's "why can't I"
+ * answer in the prompt, this is the one function to extend.
+ *
+ * @param {CommandRegistry | null} registry
+ * @returns {string[]}
+ */
+export function commandToolBlurbs(registry: CommandRegistry | null): string[] {
+  if (!registry) {
+    return [];
+  }
+  return advertisedCommandTools(registry).map(
+    (definition) =>
+      `${definition.name}(${signatureOf(definition.parameters)}) — ${definition.description}`,
+  );
+}
+
+/** A `report` return, normalised: a bare string is a summary alone. */
+function normaliseReport(report: string | AiToolReport): AiToolReport {
+  return typeof report === "string" ? { summary: report } : report;
+}
+
+/**
+ * The ledger paths a record's write defaults to when `report` names none, by undo scope. `"none"`
+ * has no default on purpose — see {@link AiToolReport.wrote}.
+ */
+function defaultPaths(command: AnyCommand, tab: Tab | null): string[] {
+  if (command.undo === "document") {
+    return [tab?.documentPath ?? "(untitled)"];
+  }
+  if (command.undo === "project") {
+    return ["project.json"];
+  }
+  return ["(unknown file)"];
+}
+
+/**
+ * File a projected run in the "Changed N files" ledger, by undo scope.
+ *
+ * No `undo` is a read or a navigation and records nothing. `disk` is `undo === "none"`, because
+ * `undo: "project"` IS a transaction ⌘Z reaches and the ledger's flag means "unreachable by undo".
+ * An EMPTY `wrote` is a run that changed nothing — an idempotent verb asked for a state it already
+ * had — and files nothing, because the ledger names files that changed; `undefined` is a report
+ * that named none and takes the record's defaults.
+ */
+function fileLedger(command: AnyCommand, tab: Tab | null, wrote?: readonly string[]): void {
+  if (command.undo === undefined) {
+    return;
+  }
+  const disk = command.undo === "none";
+  for (const path of wrote ?? defaultPaths(command, tab)) {
+    recordWrite({ disk, ok: true, path, tool: command.title });
+  }
+}
+
+/**
+ * A ToolRegistry whose tools are the active registry's `aiTool` records. Nothing is registered.
+ *
+ * @param {CommandToolDeps} deps
+ * @returns {ToolRegistry}
+ */
+export function createCommandToolRegistry(deps: CommandToolDeps): ToolRegistry {
+  /** The record projecting `name`, enabled or not — so `execute` can reach a refusal. */
+  function commandFor(name: string): AnyCommand | undefined {
+    return activeRegistry()
+      ?.list()
+      .find((command) => command.aiTool?.name === name);
+  }
+
+  /**
+   * Run one projected record as the agent — the whole of §3 of the design.
+   *
+   * @param {string} name
+   * @param {object} received
+   * @returns {Promise<ToolResult>}
+   */
+  async function execute(name: string, received: object): Promise<ToolResult> {
+    const registry = activeRegistry();
+    const command = commandFor(name);
+    if (!registry || !command) {
+      /* Two absences, one shape. A window with no registry is answered in today's wording; a name
+         no record projects is `@jxsuite/ai`'s own `Unknown tool` sentence. */
+      return registry
+        ? toolError(`Unknown tool: "${name}"`)
+        : { error: `Cannot run "${name}" — this window has no command registry.`, success: false };
+    }
+    const tool = command.aiTool!;
+    const args = received as Record<string, unknown>;
+
+    /* The witness and the snapshot, only for a record that writes the document: `rootBefore` is
+       what `transactDoc` replaces, and the snapshot is what the verdict compares against. */
+    const tab = command.undo === "document" ? deps.getTab() : null;
+    const rootBefore = tab ? toRaw(tab.doc.document) : null;
+    let snapshot: WriteSnapshot | null = null;
+    let before: CommandContext;
+    try {
+      if (tab) {
+        snapshot = await snapshotBeforeWrite(tab, deps);
+      }
+      if (command.level === "selection") {
+        /* The selector first, with its own gate and its own argument refusal ("addresses no
+           node", "expected an array of document paths"); then the verb, against the selection the
+           selector made. Both steps are records; the bridge holds no predicate of its own. On a
+           refusal at the second step the selection stays where the selector put it — the honest
+           trace of what the agent attempted, and restoring it would be a second write inside a
+           refusal path. */
+        const { paths, ...rest } = args;
+        await registry.run(SELECTOR, { paths });
+        before = registry.context();
+        await registry.run(command.id, rest);
+      } else {
+        before = registry.context();
+        await registry.run(command.id, args);
+      }
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error), success: false };
+    }
+
+    if (tab && toRaw(tab.doc.document) === rootBefore) {
+      const frozen = registry.context().collab.sourceCanonical
+        ? " A collaborator is editing its source, so structural edits are paused."
+        : "";
+      return {
+        error: `${command.title} changed nothing: the document is exactly as it was.${frozen}`,
+        success: false,
+      };
+    }
+
+    const after = registry.context();
+    let report: AiToolReport;
+    try {
+      report = normaliseReport(tool.report({ after, args: args as never, before }));
+    } catch (error) {
+      /* `run` has resolved, so the write HAPPENED; a report that throws must not make it vanish.
+         Left to the loop, the throw would be labelled "Failed to parse arguments" and the ledger
+         would never be filed. So the ledger is filed from `undo`'s defaults — the report that would
+         have named the paths is the thing that failed — and the model is told both halves. */
+      fileLedger(command, tab);
+      const message = error instanceof Error ? error.message : String(error);
+      return { error: `${command.title} ran, but its report failed: ${message}`, success: false };
+    }
+    fileLedger(command, tab, report.wrote);
+
+    let { summary } = report;
+    if (tab && snapshot) {
+      const verdict = await reportDocumentWrite(tab, snapshot, summary, deps);
+      if (!verdict.success) {
+        return verdict;
+      }
+      /* A success verdict may have appended the token hints; the report's sentence is kept. */
+      summary = verdict.summary ?? summary;
+    }
+    return {
+      success: true,
+      summary,
+      ...(report.data === undefined ? {} : { data: report.data }),
+    };
+  }
+
+  return {
+    register() {
+      throw new Error(
+        "command tools are a view over the registry; declare aiTool on the record instead",
+      );
+    },
+    list() {
+      const registry = activeRegistry();
+      return registry ? advertisedCommandTools(registry, execute) : [];
+    },
+    listForLLM() {
+      return this.list().map((definition) => ({
+        type: "function",
+        function: {
+          name: definition.name,
+          description: definition.description,
+          parameters: definition.parameters,
+        },
+      }));
+    },
+    getDefinition(name) {
+      const registry = activeRegistry();
+      const command = commandFor(name);
+      return registry && command ? definitionOf(registry, command, execute) : undefined;
+    },
+    validate() {
+      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}"`] };
+    },
+    async execute(name, args) {
+      const side = sideOf(name);
+      return side ? side.execute(name, args) : toolError(`Unknown tool: "${name}"`);
+    },
+  };
+}