@particle-academy/agent-integrations 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -11,6 +11,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.53.0] - 2026-10-30
+
+### Added
+
+- **Several forms on one host.** A second `registerFormBridge` on the same host
+  now JOINS the existing form tools instead of throwing. Every form tool takes an
+  optional `form` argument (the form's `adapter.id`). It may be omitted while
+  exactly one form is mounted. With two or more, a call without it is refused
+  with the mounted ids listed, and an id that is not mounted is always refused.
+  A new `form_list` tool returns `{ forms: [{ id, title, screenId, fields }] }`.
+  Each registration's `dispose()` removes only that form and settles only its
+  pending writes, with the 0.52.0 "outcome unknown" error. The tools are
+  withdrawn when the last form on the host is disposed. `pendingMode`, the
+  confirm gate, `agent` and the activity target stay per form. This is option A
+  of `docs/multi-form-hosts.md`, which now records what was built.
+  **Nothing to do for a single-form host:** every existing call shape works
+  unchanged. Hosts that gave each form its own MCP host to work around the
+  0.51.0 refusal can now mount them all on one host. Several `<BridgedForm>`s
+  may share one `server`.
+- Internal: `src/bridges/multi-instance.ts` (`joinInstanceRouter`), the shared
+  per-host router behind this. Only the form bridge uses it so far. The design
+  note says what adopting it would take for charts, grids and the other
+  bridges keyed by an adapter id.
+
+### Changed
+
+- The form tools are now registered once per host under the single owner
+  `"form-bridge"`, not `form:<adapter.id>`. An unrelated registrant claiming a
+  form tool name is still refused, and `Bridge.id` is still `form:<adapter.id>`.
+  Their descriptions no longer name a form, because they serve every mounted
+  form. `form_describe` still returns the form's `id` and `title`.
+- `registerFormBridge` throws if `adapter.id` is missing or empty, since it is
+  how agents pick the form. `adapter.id` was already a required `string` in the
+  type, so only code that bypassed the type is affected.
+- Registering a form whose `adapter.id` is already mounted replaces it, as a
+  remount did before. The earlier registration's `dispose()` leaves the newer
+  one in place.
+
 ## [0.52.0] - 2026-10-30
 
 ### Added

package/README.md

@@ -193,9 +193,51 @@ argument: your write is the authority, so check your own version or ETag there
 and refuse with `{ ok: false, error: "Draft changed since you read it; re-read
 and retry", code: "stale" }`. The agent gets that sentence as the tool error.
 
-The form bridge pushes **no undo entries**, and **one form bridge per host**:
-since 0.51.0 a second form bridge with a different `id` on the same host throws,
-because the tool names are not scoped to the form. See
+The form bridge pushes **no undo entries**.
+
+### Several forms on one host
+
+Since 0.53.0, call `registerFormBridge` once per form on the **same** host. The
+first form registers the form tools; later forms join them, so the tool list
+stays the same eight tools however many forms are mounted:
+
+```ts
+import { registerFormBridge } from "@particle-academy/agent-integrations/bridges/forms";
+
+const billing = registerFormBridge(host, { adapter: billingAdapter });   // adapter.id === "billing"
+const shipping = registerFormBridge(host, {
+  adapter: shippingAdapter,                                              // adapter.id === "shipping"
+  pendingMode: false,                     // per form: shipping submits without a human confirm
+  agent: { id: "checkout-agent", name: "Checkout" },
+});
+
+// An agent then picks the form with the `form` argument:
+await host.callTool("form_list", {});                     // [{ id: "billing", … }, { id: "shipping", … }]
+await host.callTool("form_set_value", { form: "shipping", field: "street", value: "2 Ship Rd" });
+await host.callTool("form_set_value", { field: "street", value: "?" });
+// → error: 2 forms are mounted, so pass "form" with one of: "billing", "shipping". form_list describes them.
+
+shipping.dispose(); // removes only shipping; billing keeps working, and `form` is optional again
+billing.dispose();  // the last form: every form tool is withdrawn
+```
+
+- **`form`** is accepted by every form tool. With exactly one form mounted it is
+  optional, so a single-form host and its agent prompts work exactly as before.
+  With two or more, a call without it is refused with the mounted ids listed. An
+  id that is not mounted is always refused, never routed to another form.
+- **`form_list`** returns `{ forms: [{ id, title, screenId, fields }] }`.
+- Each form is identified by `adapter.id`, which must be a non-empty string.
+  Registering an id that is already mounted replaces it (a remount); the earlier
+  registration's `dispose()` then leaves the newer one in place.
+- `pendingMode`, `adapter.confirm`, `agent` and the presence target stay **per
+  form**; activity names `<formId>:<field>` on the form's own `screenId`.
+- `dispose()` settles only that form's pending writes, with the "outcome
+  unknown" error described above.
+- The tools are held by one registrant (`"form-bridge"`), so an unrelated
+  registrant claiming a form tool name is still refused.
+
+`<BridgedForm>` needs no change: several of them may now share one `server`.
+Background and the alternatives considered:
 [`docs/multi-form-hosts.md`](./docs/multi-form-hosts.md).
 
 `registerScreenDocBridge` edits the nodes inside one screen and exports its

package/dist/bridges/forms.d.cts

@@ -129,13 +129,20 @@ type FormBridgeOptions = {
     pendingMode?: boolean;
 };
 /**
- * registerFormBridge — wires schema-driven MCP access to a single form.
+ * registerFormBridge — wires schema-driven MCP access to a form.
  *
- * ONE form bridge per host. The tool names (`form_set_value`, …) are not
- * scoped to the form id, so since 0.51.0 a second form bridge with a different
- * adapter id on the same host throws (the duplicate-registrant refusal); a
- * remount of the SAME form re-registers fine. For several forms, give each its
- * own host for now — see `docs/multi-form-hosts.md`.
+ * Several forms may share one host. The first form on a host registers the
+ * form tools; later ones JOIN them (since 0.53.0; before, a second form threw).
+ * Each tool takes an optional `form` argument naming the form by `adapter.id`:
+ * optional while exactly one form is mounted, so a single-form host behaves as
+ * it always did, and required once two or more are. `form_list` lists what is
+ * mounted. The returned `dispose()` removes only this form; the tools are
+ * withdrawn when the last form on the host is disposed. A second registration
+ * with an id that is already mounted replaces it (a remount); the earlier
+ * registration's `dispose()` then leaves the newer one in place.
+ *
+ * `pendingMode`, the confirm gate, the agent identity and the activity target
+ * stay per form. See `docs/multi-form-hosts.md`.
  */
 declare function registerFormBridge(host: ToolHost, options: FormBridgeOptions): Bridge;
 

package/dist/bridges/forms.d.ts

@@ -129,13 +129,20 @@ type FormBridgeOptions = {
     pendingMode?: boolean;
 };
 /**
- * registerFormBridge — wires schema-driven MCP access to a single form.
+ * registerFormBridge — wires schema-driven MCP access to a form.
  *
- * ONE form bridge per host. The tool names (`form_set_value`, …) are not
- * scoped to the form id, so since 0.51.0 a second form bridge with a different
- * adapter id on the same host throws (the duplicate-registrant refusal); a
- * remount of the SAME form re-registers fine. For several forms, give each its
- * own host for now — see `docs/multi-form-hosts.md`.
+ * Several forms may share one host. The first form on a host registers the
+ * form tools; later ones JOIN them (since 0.53.0; before, a second form threw).
+ * Each tool takes an optional `form` argument naming the form by `adapter.id`:
+ * optional while exactly one form is mounted, so a single-form host behaves as
+ * it always did, and required once two or more are. `form_list` lists what is
+ * mounted. The returned `dispose()` removes only this form; the tools are
+ * withdrawn when the last form on the host is disposed. A second registration
+ * with an id that is already mounted replaces it (a remount); the earlier
+ * registration's `dispose()` then leaves the newer one in place.
+ *
+ * `pendingMode`, the confirm gate, the agent identity and the activity target
+ * stay per form. See `docs/multi-form-hosts.md`.
  */
 declare function registerFormBridge(host: ToolHost, options: FormBridgeOptions): Bridge;
 

package/dist/bridges-forms.cjs

@@ -151,16 +151,184 @@ async function commit(run, fallback) {
   }
 }
 
+// src/bridges/multi-instance.ts
+var routers = /* @__PURE__ */ new WeakMap();
+var quoteAll = (ids) => ids.map((id) => `"${id}"`).join(", ");
+function joinInstanceRouter(host, options, id, instance) {
+  if (typeof id !== "string" || id.trim() === "") {
+    throw new Error(
+      `A ${options.family} on a shared host needs a non-empty string id (got ${JSON.stringify(id)}); agents select it by that id through the "${options.argument}" argument.`
+    );
+  }
+  let byFamily = routers.get(host);
+  if (!byFamily) {
+    byFamily = /* @__PURE__ */ new Map();
+    routers.set(host, byFamily);
+  }
+  let state = byFamily.get(options.family);
+  if (!state) {
+    const instances = /* @__PURE__ */ new Map();
+    const router = {
+      ids: () => [...instances.keys()],
+      entries: () => [...instances.entries()],
+      resolve: (requested) => resolve(options, instances, requested)
+    };
+    const uninstall = options.install(router);
+    state = { instances, router, uninstall };
+    byFamily.set(options.family, state);
+  }
+  const current = state;
+  current.instances.set(id, instance);
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    if (current.instances.get(id) !== instance) return;
+    current.instances.delete(id);
+    if (current.instances.size === 0 && byFamily.get(options.family) === current) {
+      byFamily.delete(options.family);
+      current.uninstall();
+    }
+  };
+  return { router: current.router, leave };
+}
+function resolve(options, instances, requested) {
+  const ids = [...instances.keys()];
+  const { family, argument, listTool } = options;
+  if (requested === void 0 || requested === null || requested === "") {
+    if (ids.length === 1) return { ok: true, id: ids[0], instance: instances.get(ids[0]) };
+    if (ids.length === 0) return { ok: false, error: `No ${family} is mounted.` };
+    return {
+      ok: false,
+      error: `${ids.length} ${family}s are mounted, so pass "${argument}" with one of: ${quoteAll(ids)}. ${listTool} describes them.`
+    };
+  }
+  if (typeof requested !== "string") {
+    return { ok: false, error: `"${argument}" must be a ${family} id string. Mounted: ${quoteAll(ids)}.` };
+  }
+  if (!instances.has(requested)) {
+    return {
+      ok: false,
+      error: `No ${family} "${requested}" is mounted. ` + (ids.length ? `Mounted: ${quoteAll(ids)}. ` : "") + `${listTool} lists what is open.`
+    };
+  }
+  return { ok: true, id: requested, instance: instances.get(requested) };
+}
+
 // src/bridges/forms.ts
 var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
+var FORM_TOOLS_OWNER = "form-bridge";
+var FORM_ARG = {
+  type: "string",
+  description: "Id of the form to act on (see form_list). Optional while exactly one form is mounted; required when several are."
+};
+var FORM_TOOL_DEFS = [
+  {
+    name: "form_describe",
+    description: "Describe a form \u2014 fields, types, options, required flags. Call this first to know what's fillable.",
+    properties: {},
+    required: []
+  },
+  { name: "form_get_value", description: "Read a single field's current value.", properties: { field: { type: "string" } }, required: ["field"] },
+  { name: "form_get_values", description: "Read every field's current value as a JSON object.", properties: {}, required: [] },
+  {
+    name: "form_set_value",
+    description: "Set one field's value. The host's controlled state updates and the human sees the field change.",
+    properties: {
+      field: { type: "string" },
+      value: { description: "Value to set. Type depends on the field's `type`." }
+    },
+    required: ["field", "value"]
+  },
+  {
+    name: "form_set_values",
+    description: "Set multiple fields atomically. Pass a `values` object keyed by field name.",
+    properties: { values: { type: "object" } },
+    required: ["values"]
+  },
+  {
+    name: "form_focus",
+    description: "Move browser focus to a field (host-implemented). Useful before streaming text into it.",
+    properties: { field: { type: "string" } },
+    required: ["field"]
+  },
+  {
+    name: "form_submit",
+    description: "Submit the form. Host returns ok + values (or an error). In pendingMode this is staged for the human to confirm first.",
+    properties: {},
+    required: []
+  }
+];
+function installFormTools(host, router) {
+  const disposers = [];
+  try {
+    for (const def of FORM_TOOL_DEFS) {
+      disposers.push(
+        host.registerTool(
+          {
+            name: def.name,
+            description: def.description,
+            inputSchema: {
+              type: "object",
+              properties: { form: FORM_ARG, ...def.properties },
+              required: def.required,
+              additionalProperties: false
+            }
+          },
+          async (args) => {
+            const target = router.resolve(args?.form);
+            if (!target.ok) return errorResult(target.error);
+            return target.instance.handlers[def.name](args);
+          },
+          { owner: FORM_TOOLS_OWNER }
+        )
+      );
+    }
+    disposers.push(
+      host.registerTool(
+        {
+          name: "form_list",
+          description: "List the forms mounted on this host \u2014 id, title, screen and fields. Pass an id as `form` to the other form tools when more than one is mounted.",
+          inputSchema: { type: "object", properties: {}, additionalProperties: false }
+        },
+        () => {
+          try {
+            const forms = router.entries().map(([id, { adapter }]) => ({
+              id,
+              title: adapter.title,
+              screenId: adapter.screenId,
+              fields: adapter.getFields()
+            }));
+            const text = forms.map((f) => `${f.id}${f.title ? ` \u2014 ${f.title}` : ""}: ${f.fields.map((x) => x.name).join(", ") || "(no fields)"}`).join("\n");
+            return textResult(text || "(no forms)", { forms });
+          } catch (e) {
+            return errorResult(hostErrorMessage(e, "form_list failed."));
+          }
+        },
+        { owner: FORM_TOOLS_OWNER }
+      )
+    );
+  } catch (e) {
+    for (const d of disposers) d();
+    throw e;
+  }
+  return () => {
+    for (const d of disposers) d();
+  };
+}
 function registerFormBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
   const pendingMode = options.pendingMode ?? true;
-  const disposers = [];
-  const bridgeId = `form:${adapter.id}`;
+  const formId = adapter?.id == null ? "" : String(adapter.id);
+  if (formId.trim() === "") {
+    throw new Error(
+      "registerFormBridge: adapter.id must be a non-empty string. It is how agents pick this form (the `form` argument) when several forms share a host."
+    );
+  }
+  const bridgeId = `form:${formId}`;
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
-  const formId = adapter.id;
+  const handlers = {};
   let disposed = false;
   const onDispose = /* @__PURE__ */ new Set();
   const CLOSED = /* @__PURE__ */ Symbol("form-closed");
@@ -170,13 +338,13 @@ function registerFormBridge(host, options) {
       });
       return Promise.resolve(CLOSED);
     }
-    return new Promise((resolve, reject) => {
-      const close = () => resolve(CLOSED);
+    return new Promise((resolve2, reject) => {
+      const close = () => resolve2(CLOSED);
       onDispose.add(close);
       p.then(
         (v) => {
           onDispose.delete(close);
-          resolve(v);
+          resolve2(v);
         },
         (e) => {
           onDispose.delete(close);
@@ -194,7 +362,7 @@ function registerFormBridge(host, options) {
     elementId: typeof args?.field === "string" ? `${formId}:${args.field}` : formId,
     label: typeof args?.field === "string" ? `${adapter.title ?? formId} \u2192 ${args.field}` : adapter.title ?? formId
   });
-  const reg = (name, description, properties, required, handler, isMutation) => {
+  const reg = (name, handler, isMutation) => {
     const wrapped = async (args) => {
       try {
         return await handler(args);
@@ -209,23 +377,10 @@ function registerFormBridge(host, options) {
       screenId: adapter.screenId,
       resolveTarget: ({ args }) => target(args)
     }) : wrapped;
-    disposers.push(
-      host.registerTool(
-        {
-          name,
-          description,
-          inputSchema: { type: "object", properties, required, additionalProperties: false }
-        },
-        final,
-        { owner: bridgeId }
-      )
-    );
+    handlers[name] = final;
   };
   reg(
     "form_describe",
-    `Describe the form "${formId}" \u2014 fields, types, options, required flags. Call this first to know what's fillable.`,
-    {},
-    [],
     () => {
       const fields = adapter.getFields();
       const text = fields.map((f) => `${f.name}${f.required ? "*" : ""} (${f.type})${f.label ? ` \u2014 ${f.label}` : ""}`).join("\n");
@@ -235,9 +390,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_get_value",
-    "Read a single field's current value.",
-    { field: { type: "string" } },
-    ["field"],
     (args) => {
       const name = String(args.field ?? "");
       if (!adapter.getFields().find((f) => f.name === name)) {
@@ -250,9 +402,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_get_values",
-    "Read every field's current value as a JSON object.",
-    {},
-    [],
     () => {
       const values = adapter.getValues();
       return textResult(JSON.stringify(values, null, 2), values);
@@ -261,12 +410,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_set_value",
-    "Set one field's value. The host's controlled state updates and the human sees the field change.",
-    {
-      field: { type: "string" },
-      value: { description: "Value to set. Type depends on the field's `type`." }
-    },
-    ["field", "value"],
     async (args) => {
       const name = String(args.field ?? "");
       const fieldDef = adapter.getFields().find((f) => f.name === name);
@@ -282,9 +425,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_set_values",
-    "Set multiple fields atomically. Pass a `values` object keyed by field name.",
-    { values: { type: "object" } },
-    ["values"],
     async (args) => {
       const values = args.values && typeof args.values === "object" ? args.values : {};
       const fields = adapter.getFields();
@@ -338,9 +478,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_focus",
-    "Move browser focus to a field (host-implemented). Useful before streaming text into it.",
-    { field: { type: "string" } },
-    ["field"],
     (args) => {
       const name = String(args.field ?? "");
       if (!adapter.focus) return errorResult("Host did not provide a focus implementation.");
@@ -354,9 +491,6 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_submit",
-    "Submit the form. Host returns ok + values (or an error). In pendingMode this is staged for the human to confirm first.",
-    {},
-    [],
     async () => {
       if (!adapter.submit) return errorResult("Host did not provide a submit implementation.");
       if (pendingMode && adapter.confirm) {
@@ -380,12 +514,19 @@ function registerFormBridge(host, options) {
     },
     true
   );
+  const membership = joinInstanceRouter(
+    host,
+    { family: "form", argument: "form", listTool: "form_list", install: (router) => installFormTools(host, router) },
+    formId,
+    { adapter, handlers }
+  );
   return {
     id: bridgeId,
     title: adapter.title ?? formId,
     dispose: () => {
+      if (disposed) return;
       disposed = true;
-      for (const d of disposers) d();
+      membership.leave();
       for (const close of [...onDispose]) close();
       onDispose.clear();
     }