poetry-agent 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f94b26ba2c90475193b090c1deba25d33ffad8fbec0c3b4fdee0e22be1c7a977
-  data.tar.gz: 8d504ccbe9f96573ffe89dee1e7ed80ccefd1b5af93a9f9543aa70228ff5c059
+  metadata.gz: 6741c0fdec4ef51366a3c84788aa915e926783aff97b1ee65ef1a24536657c17
+  data.tar.gz: 3da36a6f201c54d3eb54e9c652bd28268503b7f935e022fcf56325bbdae7c827
 SHA512:
-  metadata.gz: 9e565a75006736af0eae0d6ca7e7284c00c7450399abde58de0e9aafac1869a7f72fd77f256a3100e41525eeea2a92751ecb9b3b03a1324450453ab71402f2e3
-  data.tar.gz: 23e554fad8c091dca3ca66f7947452f870f88586d78901470024fd9d8f84b10a15129c35c8f2cba5b4f72044b9f4eb7af3f8d35e07dec630debba4de1b704d87
+  metadata.gz: dde4b223ac88d79f769ff4f86158441b27f3e04077da404a0bd44abb2fcc98eef160518483c3dd3ddb2c40300420c5adf825a15a3139045465c5932775399dab
+  data.tar.gz: dda91195a6772508385e79306e7f60e020c1d3d37d0c99a7869d8eb387568f1b30149d1fe7ee671e021268b7bf3bd94f569ad48b045692466e0e817d0d63c0a5

data/.controller_docs

@@ -0,0 +1 @@
+0

data/.jsdoc_floor

@@ -0,0 +1 @@
+2

data/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "rubydex": {
+      "command": "bundle",
+      "args": ["exec", "rdx", "mcp"]
+    }
+  }
+}

data/.yard-lint.yml

@@ -0,0 +1,25 @@
+# yard-lint: the documentation tier YARD's own gates miss - a documented
+# method missing a @param, an @example that does not parse, option tags,
+# tag order, invalid types. Runs as rake yard:lint (in the default task).
+# UndocumentedObjects stays off: yard:coverage gates public objects at its
+# recorded floor, and this validator counts the @api private internals the
+# gems hide on purpose (--hide-api is not honoured here). MissingReturn is
+# off until the @param backlog is cleared; revisit then.
+AllValidators:
+  YardOptions:
+    - --no-private
+Documentation/UndocumentedObjects:
+  Enabled: false
+Documentation/MissingReturn:
+  Enabled: false
+Tags/InvalidTypes:
+  Enabled: true
+# A **options splat passed through to a control is documented as @param
+# options [Hash], not one @option per key; and @example blocks here are
+# ERB as often as Ruby, which this validator cannot parse.
+Documentation/UndocumentedOptions:
+  Enabled: false
+Tags/OptionTags:
+  Enabled: false
+Tags/ExampleSyntax:
+  Enabled: false

data/.yard_coverage_all

@@ -0,0 +1 @@
+0

data/Archspec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# The architecture the family enforces by review, as checks (rake arch:check).
+# agent depends on core and ui, never on charts or extract, and never
+# names the host application.
+root "."
+source "app/**/*.rb", "lib/**/*.rb"
+
+component :lib, in: "lib/**/*.rb"
+component :app, in: "app/**/*.rb"
+
+lib.cannot_reference_constants "Poetry::Charts", "Poetry::Extract", "ApplicationController",
+                               because: "agent depends on core and ui and never names the host"
+app.cannot_reference_constants "Poetry::Charts", "Poetry::Extract", "ApplicationController",
+                               because: "agent depends on core and ui and never names the host"

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.1.5] - 2026-09-18
+
+### Added
+
+- The controllers manifest carries the prose beside each controller: its purpose (a JSDoc block above the class), the meaning of every value, and a summary of every action method, harvested when the manifest is generated; `rake stimulus:docs` holds the count of gaps at a committed floor, now zero.
+
+### Changed
+
+- 18 methods the reference already hid with `@api private` are Ruby-private now: each was called only by its own class or template, so the runtime enforces what the tag only stated. A host that reached one gets a NoMethodError instead of an internal that may change without notice. The tag remains on the internals the family shares between its gems and on whole internal classes.
+- Every class, module and method carries a one-sentence description, private helpers included: `rake yard:coverage:all` measures the whole tree (a tag-only docstring counts as blank) and the committed floor now stands at zero.
+- `describe_component` phrases any-of requirements through core's `RequiresAny`, and a test now covers the requirement and slot-facet lines.
+
+## [0.1.4] - 2026-09-15
+
+Lockstep release with the family; no changes in this gem.
+
 ## [0.1.3] - 2026-09-13
 
 ### Fixed

data/app/javascript/poetry/agent/a2ui_surface_controller.js

@@ -1,22 +1,33 @@
 import { Controller } from "@hotwired/stimulus"
 
-// The client side of an A2UI surface's checks: the server renders the
-// program (every checked component's rules with absolute bindings, the
-// bound inputs by path with their kinds, and the data model) and this
-// controller evaluates it as the user types - a button whose own checks
-// fail is disabled, a failing input is marked invalid and its error slot
-// carries the message. The five validators and the three combinators are
-// the checks vocabulary; anything else passes here and is judged by the
-// server, which re-runs every rule on the action.
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
 
+/**
+ * The client side of an A2UI surface's checks: the server renders the
+ * program (every checked component's rules with absolute bindings, the
+ * bound inputs by path with their kinds, and the data model) and this
+ * controller evaluates it as the user types - a button whose own checks
+ * fail is disabled, a failing input is marked invalid and its error slot
+ * carries the message. The five validators and the three combinators are
+ * the checks vocabulary; anything else passes here and is judged by the
+ * server, which re-runs every rule on the action.
+ */
 export default class extends Controller {
-  static values = { program: Object }
+  static values = {
+    // The check program the server compiled: the checks, the bound inputs by path, and the data model.
+    program: Object
+  }
 
+  /**
+   * Evaluates every check once at mount.
+   */
   connect() {
     this.evaluate()
   }
 
+  /**
+   * Runs every check in the program and applies its failures.
+   */
   evaluate() {
     const checks = this.programValue?.checks || {}
     for (const [key, entry] of Object.entries(checks)) {
@@ -25,7 +36,13 @@ export default class extends Controller {
     }
   }
 
-  // The message of a failing rule, or null when it passes.
+  /**
+   * A rule's failure message, or null when it passes or cannot be decided
+   * here.
+   *
+   * @param {Object} rule the check rule with its condition and message
+   * @returns {string|null} the failure message, or null
+   */
   failure(rule) {
     const result = this.resolve(rule.condition)
     if (result === null) return null // unknown here; the server decides
@@ -34,6 +51,14 @@ export default class extends Controller {
     return (result && typeof result === "object" && result.message) || rule.message || "Check failed"
   }
 
+  /**
+   * Reflects a check's failures on the elements bound to a key: a button
+   * disables, an input turns invalid.
+   *
+   * @param {string} key the bound key the elements carry
+   * @param {string} kind the control kind: button or input
+   * @param {string[]} failures the failure messages, empty when the check passes
+   */
   apply(key, kind, failures) {
     for (const element of this.element.querySelectorAll(`[data-a2ui-key="${escapeAttribute(key)}"]`)) {
       if (kind === "button") {
@@ -49,6 +74,12 @@ export default class extends Controller {
     }
   }
 
+  /**
+   * A value with its bindings read and its calls run, recursively.
+   *
+   * @param {*} value a literal, a binding, a call, or an array of them
+   * @returns {*} the resolved value
+   */
   resolve(value) {
     if (value === null || typeof value !== "object") return value
     if (Array.isArray(value)) return value.map((item) => this.resolve(item))
@@ -57,6 +88,14 @@ export default class extends Controller {
     return value
   }
 
+  /**
+   * Runs a catalog function by name with its arguments resolved; an unknown
+   * name resolves to null.
+   *
+   * @param {string} name the catalog function
+   * @param {Object} rawArgs the arguments, bindings and calls unresolved
+   * @returns {*} the function's result, or null for an unknown name
+   */
   call(name, rawArgs) {
     const fn = FUNCTIONS[name]
     if (!fn) return null
@@ -65,8 +104,13 @@ export default class extends Controller {
     return fn(args)
   }
 
-  // The current value of a bound path: the form control first, the
-  // server's model when no control carries it.
+  /**
+   * The current value of a bound path from the form's inputs, falling back to
+   * the data model.
+   *
+   * @param {string} path the bound pointer
+   * @returns {*} the input's current value, or the model's
+   */
   read(path) {
     const kind = this.programValue?.inputs?.[path]
     const name = `a2ui[values][${path}]`

data/app/javascript/poetry/agent/adapter.js

@@ -15,15 +15,31 @@
 // argument - an object rejects with UnknownError("Failed to parse input
 // arguments"), not a TypeError.
 
-// The live ModelContext, or null where the browser exposes none - callers
-// treat null as "do nothing", exactly like an edge bridge would.
+/**
+ * The live ModelContext, or null where the browser exposes none - callers
+ * treat null as "do nothing", exactly like an edge bridge would.
+ *
+ * @returns {Object|null} the live ModelContext, or null
+ */
 export const modelContext = () =>
   (typeof document !== "undefined" && document.modelContext) || null
 
+/**
+ * Whether this browser exposes a ModelContext.
+ *
+ * @returns {boolean} true when document.modelContext exists
+ */
 export const supported = () => modelContext() !== null
 
-// Registers one tool; resolves when the browser accepted it, rejects on a
-// duplicate name, an empty name/description, or an invalid schema.
+/**
+ * Registers one tool; resolves when the browser accepted it, rejects on a
+ * duplicate name, an empty name/description, or an invalid schema.
+ *
+ * @param {Object} definition the tool definition (name, description, inputSchema, execute)
+ * @param {Object} [root0] the options
+ * @param {AbortSignal} [root0.signal] aborts the registration
+ * @returns {Promise<void>} resolves once the browser accepted the tool
+ */
 export const registerTool = (definition, { signal } = {}) =>
   modelContext().registerTool(definition, signal ? { signal } : {})
 
@@ -31,8 +47,13 @@ export const registerTool = (definition, { signal } = {}) =>
 // executeTool go string-first without a wasted rejection.
 let stringArguments = false
 
-// The registered tools with inputSchema normalized to an object: parsed
-// when the browser serialized it, null when the text is not JSON.
+/**
+ * The registered tools with inputSchema normalized to an object: parsed
+ * when the browser serialized it, null when the text is not JSON.
+ *
+ * @param {Object} [options] the getTools options (fromOrigins)
+ * @returns {Promise<Array<Object>>} the registered tools
+ */
 export const getTools = async (options = {}) => {
   const tools = await modelContext().getTools(options)
   for (const tool of tools) {
@@ -47,9 +68,16 @@ export const getTools = async (options = {}) => {
   return tools
 }
 
-// Executes a tool with the spec's object arguments, falling back to the
-// JSON-string form the current Chrome build parses; when both shapes
-// reject, the first rejection surfaces.
+/**
+ * Executes a tool with the spec's object arguments, falling back to the
+ * JSON-string form the current Chrome build parses; when both shapes
+ * reject, the first rejection surfaces.
+ *
+ * @param {Object} tool the registered tool
+ * @param {Object} [args] the input arguments
+ * @param {Object} [options] the executeTool options (signal)
+ * @returns {Promise<string>} the stringified result
+ */
 export const executeTool = async (tool, args = {}, options = {}) => {
   const context = modelContext()
   const asString = () => context.executeTool(tool, JSON.stringify(args), options)
@@ -67,11 +95,21 @@ export const executeTool = async (tool, args = {}, options = {}) => {
   }
 }
 
-// WebMCP tool-name grammar: 1-128 chars of ASCII alphanumerics, "_", "-", ".".
+/**
+ * WebMCP tool-name grammar: 1-128 chars of ASCII alphanumerics, "_", "-", ".".
+ */
 export const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/
+/**
+ * Whether a name fits the WebMCP tool-name grammar.
+ *
+ * @param {string} name the candidate name
+ * @returns {boolean} true when it matches TOOL_NAME
+ */
 export const validToolName = (name) => TOOL_NAME.test(name)
 
-// Test seam: forget the argument shape the last browser taught us.
+/**
+ * Test seam: forget the argument shape the last browser taught us.
+ */
 export const _resetArgumentShape = () => {
   stringArguments = false
 }

data/app/javascript/poetry/agent/agui_client_tool_controller.js

@@ -1,23 +1,33 @@
 import { Controller } from "@hotwired/stimulus"
 import { executeRegisteredTool } from "@poetry/agent/webmcp_controller"
 
-// The AG-UI client-tool bridge: the relay appends one of these (hidden)
-// per tool call the agent made to a FRONTEND tool - a component tool the
-// page declared - and this controller executes it through the registrar
-// (the same dispatch a WebMCP call takes, so it works in every browser,
-// modelContext or not), then POSTs the result to the continue URL. The
-// server folds the tool message into the transcript and answers with the
-// next run's streams, which Turbo renders. One element, one execution:
-// the done flag makes a Turbo re-render inert.
+/**
+ * The AG-UI client-tool bridge: the relay appends one of these (hidden)
+ * per tool call the agent made to a FRONTEND tool - a component tool the
+ * page declared - and this controller executes it through the registrar
+ * (the same dispatch a WebMCP call takes, so it works in every browser,
+ * modelContext or not), then POSTs the result to the continue URL. The
+ * server folds the tool message into the transcript and answers with the
+ * next run's streams, which Turbo renders. One element, one execution:
+ * the done flag makes a Turbo re-render inert.
+ */
 export default class extends Controller {
   static values = {
+    // The pending tool call: its id, name and arguments.
     call: Object,
+    // Where the tool result is posted.
     url: String,
+    // Whether the call has already been answered (a restored snapshot must not
+    // answer twice).
     done: Boolean
   }
 
   static events = ["poetry:agui:client-tool-executed"]
 
+  /**
+   * Runs the pending client tool once, posts its result, and marks the call
+   * done.
+   */
   async connect() {
     if (this.doneValue) return
     this.doneValue = true

data/app/javascript/poetry/agent/index.js

@@ -21,7 +21,9 @@ export * from "@poetry/agent/adapter"
 export { _registrations, executeRegisteredTool } from "@poetry/agent/webmcp_controller"
 export { installVersionedReplace, installMorphStateGuard, preservesLocalState } from "@poetry/agent/stream_actions"
 
-// identifier -> controller class (the manifest introspects this).
+/**
+ * identifier -> controller class (the manifest introspects this).
+ */
 export const controllers = {
   "poetry--agent--webmcp": WebmcpController,
   "poetry--agent--webmcp-form": WebmcpFormController,
@@ -29,9 +31,13 @@ export const controllers = {
   "poetry--agent--a2ui-surface": A2uiSurfaceController
 }
 
-// Registers the runtime's controllers, installs the versioned replace
-// stream action the AG-UI relay and the A2UI streams emit (when Turbo is
-// present), and the morph guard that keeps an A2UI surface's local state.
+/**
+ * Registers the runtime's controllers, installs the versioned replace
+ * stream action the AG-UI relay and the A2UI streams emit (when Turbo is
+ * present), and the morph guard that keeps an A2UI surface's local state.
+ *
+ * @param {Object} application the Stimulus application
+ */
 export const registerPoetryAgent = (application) => {
   for (const [identifier, controller] of Object.entries(controllers)) {
     application.register(identifier, controller)

data/app/javascript/poetry/agent/stream_actions.js

@@ -1,12 +1,17 @@
-// The versioned replace Turbo Stream action the AG-UI relay and the A2UI
-// surface streams emit: a streamed frame re-renders the SAME element from
-// a server stream, which inherits an out-of-order delivery race, so every
-// payload carries data-version and this action applies only strictly-newer
-// frames - older or duplicate frames are dropped silently. With
-// method="morph" the newer frame morphs the element through Turbo's own
-// replace action (idiomorph), so local state survives an update. Installed
-// on Turbo by registerPoetryAgent when the host has Turbo and no vreplace
-// of its own.
+/**
+ * The versioned replace Turbo Stream action the AG-UI relay and the A2UI
+ * surface streams emit: a streamed frame re-renders the SAME element from
+ * a server stream, which inherits an out-of-order delivery race, so every
+ * payload carries data-version and this action applies only strictly-newer
+ * frames - older or duplicate frames are dropped silently. With
+ * method="morph" the newer frame morphs the element through Turbo's own
+ * replace action (idiomorph), so local state survives an update. Installed
+ * on Turbo by registerPoetryAgent when the host has Turbo and no vreplace
+ * of its own.
+ *
+ * @param {Object} [turbo] the Turbo global; a host with no Turbo installs nothing
+ * @returns {boolean} true when the action was installed
+ */
 export const installVersionedReplace = (turbo = globalThis.Turbo) => {
   if (!turbo?.StreamActions || turbo.StreamActions.vreplace) return false
 
@@ -39,6 +44,15 @@ const LOCAL_STATE = {
 }
 const EXPANDED = ["aria-expanded", "data-open", "data-state"]
 
+/**
+ * Whether a morph must leave an attribute alone to keep an A2UI surface's
+ * local state: an edited input's value or checked state, an open disclosure,
+ * or a slot-specific attribute the runtime owns.
+ *
+ * @param {Element} element the element being morphed
+ * @param {string} attributeName the attribute the morph would change
+ * @returns {boolean} true to keep the current attribute
+ */
 export const preservesLocalState = (element, attributeName) => {
   if (!element?.closest?.("[data-a2ui-surface]")) return false
   if (attributeName === "value" || attributeName === "checked") return isDirty(element)
@@ -55,6 +69,13 @@ const isDirty = (element) => {
   return false
 }
 
+/**
+ * Installs the before-morph-attribute guard once per document, so a streamed
+ * re-render morphs without clobbering local state.
+ *
+ * @param {Document} [doc] the document to guard
+ * @returns {boolean} true when installed, false when absent or already guarded
+ */
 export const installMorphStateGuard = (doc = globalThis.document) => {
   if (!doc || doc.__poetryA2uiMorphGuard) return false
   doc.__poetryA2uiMorphGuard = true

data/app/javascript/poetry/agent/webmcp_controller.js

@@ -1,35 +1,6 @@
 import { Controller } from "@hotwired/stimulus"
 import { supported, registerTool, validToolName } from "@poetry/agent/adapter"
 
-// The registrar: one controller on an opted-in component root
-// (`webmcp: "country"` on the helper call renders it beside the
-// component's own controllers) registers that instance's declared tools
-// with document.modelContext on connect and aborts them on disconnect.
-// Components gain zero runtime code - each tool dispatches to the
-// component's OWN controller action (the `executes` descriptor the Ruby
-// contract validated at class load), passing the tool's parameters
-// positionally in declared order.
-//
-// Correctness rules the spec makes load-bearing:
-// - Re-registration is skipped while the payload is unchanged (the spec
-//   documents an unregister/quick-re-register race where in-flight args
-//   for the old tool can hit the new tool's schema).
-// - Never register under Turbo's cache preview.
-// - Duplicate names are rejected by the browser; we warn and skip.
-// - A per-document budget caps registrations (each tool costs the agent
-//   context; overlap confuses tool choice).
-// - Errors come back as descriptive result strings (granular exceptions
-//   are still open spec issues; a string lets the agent self-correct):
-//   a missing or unknown parameter, a value of the wrong type or outside
-//   the enum, a missing action, a throwing action.
-// - A result is the action's return value when it is JSON-serializable
-//   (the contract's actions return their resulting state, so an answer
-//   says what happened rather than "done"); the done marker covers
-//   actions that return nothing.
-// - Parameters map positionally onto the action in declared order; the
-//   execute callback's {signal} is not forwarded (the actions are
-//   synchronous UI operations).
-
 // element -> { hash, controller: AbortController, names: string[] }
 const registrations = new Map()
 
@@ -41,10 +12,45 @@ const instances = new Map()
 const registeredCount = () =>
   [...registrations.values()].reduce((sum, entry) => sum + entry.names.length, 0)
 
+/**
+ * The registrar: one controller on an opted-in component root
+ * (`webmcp: "country"` on the helper call renders it beside the
+ * component's own controllers) registers that instance's declared tools
+ * with document.modelContext on connect and aborts them on disconnect.
+ * Components gain zero runtime code - each tool dispatches to the
+ * component's OWN controller action (the `executes` descriptor the Ruby
+ * contract validated at class load), passing the tool's parameters
+ * positionally in declared order.
+ *
+ * Correctness rules the spec makes load-bearing:
+ * - Re-registration is skipped while the payload is unchanged (the spec
+ *   documents an unregister/quick-re-register race where in-flight args
+ *   for the old tool can hit the new tool's schema).
+ * - Never register under Turbo's cache preview.
+ * - Duplicate names are rejected by the browser; we warn and skip.
+ * - A per-document budget caps registrations (each tool costs the agent
+ *   context; overlap confuses tool choice).
+ * - Errors come back as descriptive result strings (granular exceptions
+ *   are still open spec issues; a string lets the agent self-correct):
+ *   a missing or unknown parameter, a value of the wrong type or outside
+ *   the enum, a missing action, a throwing action.
+ * - A result is the action's return value when it is JSON-serializable
+ *   (the contract's actions return their resulting state, so an answer
+ *   says what happened rather than "done"); the done marker covers
+ *   actions that return nothing.
+ * - Parameters map positionally onto the action in declared order; the
+ *   execute callback's {signal} is not forwarded (the actions are
+ *   synchronous UI operations).
+ */
 export default class extends Controller {
   static values = {
+    // The instance name the tools register under (poetry.<name>.<tool>).
     name: String,
+    // The tool definitions this instance registers, as the component declared
+    // them.
     tools: Array,
+    // The most tools one page registers; past it, further registrations are
+    // dropped with a console warning.
     budget: { type: Number, default: 20 }
   }
 
@@ -54,25 +60,40 @@ export default class extends Controller {
     "poetry:webmcp:unregistered"
   ]
 
+  /**
+   * Registers this instance's tools and records it for the executor.
+   */
   connect() {
     instances.set(this.element, this)
     this.register()
   }
 
+  /**
+   * Forgets the instance and aborts its registrations.
+   */
   disconnect() {
     instances.delete(this.element)
     this.unregister()
   }
 
+  /**
+   * Re-registers under the new name once connected.
+   */
   nameValueChanged() {
     if (this.#connected) this.register()
   }
 
+  /**
+   * Re-registers the new tool list once connected.
+   */
   toolsValueChanged() {
     if (this.#connected) this.register()
   }
 
-  // Registers this instance's tools; idempotent for an unchanged payload.
+  /**
+   * Registers every declared tool with the browser under the instance name,
+   * within the page budget; skipped when unsupported or in a preview.
+   */
   register() {
     this.#connected = true
     if (!supported()) return
@@ -128,10 +149,14 @@ export default class extends Controller {
     })
   }
 
-  // Executes one of this instance's declared tools by its full registered
-  // name (`poetry.{instance}.{tool}`) or its bare tool name, with the same
-  // validation and dispatch a WebMCP call takes; unknown names answer with
-  // an error string like any other problem.
+  /**
+   * Runs one of this instance's tools by its registered or short name; an
+   * unknown name resolves to an error message.
+   *
+   * @param {string} name the registered or short tool name
+   * @param {Object} args the tool's arguments
+   * @returns {Promise<*>} the tool's result, or an error message for an unknown name
+   */
   execute(name, args = {}) {
     const tool = this.toolsValue.find((candidate) =>
       `poetry.${this.nameValue}.${candidate.name}` === name || candidate.name === name)
@@ -139,7 +164,9 @@ export default class extends Controller {
     return this.#execute(tool, args ?? {})
   }
 
-  // Aborts every registration of this instance.
+  /**
+   * Aborts every registration of this instance and announces it.
+   */
   unregister() {
     const entry = registrations.get(this.element)
     if (!entry) return
@@ -231,9 +258,16 @@ const serializable = (value) => {
   }
 }
 
-// Executes a declared tool by its full registered name on whichever
-// connected root declares it - the in-page dispatch path (no
-// modelContext needed). Answers an error string when no root does.
+/**
+ * Executes a declared tool by its full registered name on whichever
+ * connected root declares it - the in-page dispatch path (no
+ * modelContext needed). Answers an error string when no root does.
+ *
+ * @param {Object} application the Stimulus application
+ * @param {string} name the full registered tool name
+ * @param {Object} [args] the tool's arguments
+ * @returns {Promise<*>} the tool's result, or an error string when no root declares it
+ */
 export const executeRegisteredTool = (application, name, args = {}) => {
   for (const [element, controller] of instances) {
     const owns = controller.toolsValue.some((tool) => `poetry.${controller.nameValue}.${tool.name}` === name)
@@ -244,5 +278,7 @@ export const executeRegisteredTool = (application, name, args = {}) => {
   return Promise.resolve(`Error: no registered tool named ${name} on this page`)
 }
 
-// Test seam: the live registration table.
+/**
+ * Test seam: the live registration table.
+ */
 export const _registrations = registrations