@particle-academy/agent-integrations 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -11,6 +11,84 @@ 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
+
+- **Form bridge waits for the host to accept a write.** `setValue` and
+  `setValues` on `FormBridgeAdapter` may now return a Promise resolving to
+  `void` or the new exported `FormAdapterResult`
+  (`{ ok: true } | { ok: false; error; code? }`); the return type is the new
+  exported `FormAdapterCommit`. The bridge awaits it: `form_set_value` and
+  `form_set_values` report success, and emit their `AgentActivity` event, only
+  after the host accepts. A rejection or `{ ok: false }` is that call's error
+  result with the host's message (never a stack) and emits no activity. Use
+  `{ ok: false, code: "stale" }` to refuse a stale draft; the bridge adds no
+  expected-value argument because the host's write is the authority.
+  **Nothing to do:** sync `void` setters behave exactly as before.
+- Without `setValues`, `form_set_values` awaits `setValue` once per field and
+  stops at the first refusal. The error names the fields already committed,
+  `structuredContent` carries `{ committed, failed, notAttempted }`, and one
+  activity event is emitted for the committed fields.
+- `FormAdapterResult`, `FormAdapterCommit` and `FormConfirmRequest` are now
+  exported from the package root as well as `…/bridges/forms`.
+- `docs/multi-form-hosts.md`: a design note on supporting several forms on one
+  host. It is a proposal only; today the supported model is one form bridge per
+  host.
+
+### Fixed
+
+- **Form bridge reported success before an async host had accepted the write.**
+  The setter was typed `void` and called without `await`, so a host with a
+  gated or refusable write got "success" and an activity event first, and a
+  later refusal was never the tool call's result.
+- **Disposing a form bridge mid-call no longer leaves the call hanging.** A
+  write, confirm or submit still pending when the bridge is disposed now settles
+  at once as an error saying the outcome is unknown, with no activity. A late
+  settle from the host is ignored, and a late rejection is never unhandled. A
+  submit whose human confirm was pending when the form closed is never sent.
+- The `registerFormBridge` doc comment still said a host could register several
+  form bridges by giving each a distinct id. That has not worked since 0.51.0.
+  It now says one form bridge per host.
+
 ## [0.51.0] - 2026-10-27
 
 ### Changed

package/README.md

@@ -140,6 +140,106 @@ registerScreensBridge(host, {
 The screens bridge pushes **no undo entries**: `agent_undo` cannot revert a
 screens tool. Keep your own history if you need to.
 
+### Form bridge: acknowledge after the host accepts the write
+
+`setValue` and `setValues` on `FormBridgeAdapter` may return `void` **or** a
+Promise (`FormAdapterCommit`). A sync `void` setter behaves exactly as it always
+has. When the host's write is authoritative (a persisted draft, a server that
+can refuse it or report it stale), return a Promise and the bridge waits for it:
+
+- `form_set_value` / `form_set_values` report success, and emit their
+  `AgentActivity` event, only after the promise resolves to `void` or
+  `{ ok: true }`. Your `getValue` / `getValues` should return the new value by
+  then, so a read straight after a success sees it.
+- A rejection, or a resolved `{ ok: false, error }` (`FormAdapterResult`), is
+  **that call's** error result, carrying the host's `error` text (its message
+  only, never a stack), and emits **no** activity. Leave your state unchanged
+  when you refuse.
+- Without `setValues`, `form_set_values` awaits `setValue` once per field, in
+  order, and stops at the first refusal. Earlier fields stay committed (that
+  path is not atomic): the error names them, `structuredContent` carries
+  `{ committed, failed, notAttempted }`, and one activity event is emitted for
+  the committed part. Provide `setValues` if the batch must be all-or-nothing.
+- If you `dispose()` the bridge (the form closes) while a write, a confirm or a
+  submit is pending, the call settles at once as an error saying the outcome is
+  unknown, emits no activity, and a later settle is ignored. A submit whose
+  human confirm was still pending is never sent.
+
+```ts
+import {
+  registerFormBridge,
+  type FormAdapterResult,
+} from "@particle-academy/agent-integrations/bridges/forms";
+
+registerFormBridge(host, {
+  adapter: {
+    id: "invoice-draft",
+    getFields: () => fields,
+    getValue: (name) => draft.values[name],
+    getValues: () => ({ ...draft.values }),
+    // Resolve once the server has accepted it; refuse with a reason the agent can act on.
+    setValue: async (name, value): Promise<FormAdapterResult> => {
+      const res = await api.patch(`/drafts/${draft.id}`, { [name]: value, version: draft.version });
+      if (!res.ok) return { ok: false, error: res.reason, code: res.status === 409 ? "stale" : undefined };
+      draft = res.draft; // update state BEFORE resolving
+      return { ok: true };
+    },
+  },
+});
+```
+
+**Staleness is the host's call.** The bridge has no expected-value / version
+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**.
+
+### 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
 `DocAdapter`, `ScreenDocBridgeOptions`, `ScreenDocNode` and `ScreenDocOp` types
 from `@particle-academy/agent-integrations/bridges/screen-doc`. The existing

package/dist/bridges/forms.d.cts

@@ -29,6 +29,14 @@ type FormFieldDescriptor = {
  * Adapter the host wires per form. Matches the controlled-state pattern
  * react-fancy already uses (`value` / `onValueChange`); this adapter just
  * exposes those state slots in a form-shaped way the bridge can call.
+ *
+ * `setValue` / `setValues` may be sync (`void`) or async (a Promise); see
+ * {@link FormAdapterCommit}. Return a Promise when the host's write is
+ * authoritative — a persisted draft, or one the host can refuse or report
+ * stale — so the agent is told the truth instead of "success" before anything
+ * was accepted.
+ *
+ * This bridge pushes NO undo entries: `agent_undo` cannot revert a form write.
  */
 type FormBridgeAdapter = {
     /** Stable id for the form (used in form_describe + presence target). */
@@ -44,10 +52,18 @@ type FormBridgeAdapter = {
     getValue: (name: string) => unknown;
     /** Read all values as { fieldName: value }. */
     getValues: () => Record<string, unknown>;
-    /** Set a single field's value. The host wires this to its setState. */
-    setValue: (name: string, value: unknown) => void;
-    /** Set many at once. Defaults to calling setValue in a loop. */
-    setValues?: (values: Record<string, unknown>) => void;
+    /**
+     * Set a single field's value. The host wires this to its setState, or to
+     * an authoritative write it awaits. Sync `void` behaves as it always has; a
+     * Promise is awaited, and a rejection or `{ ok: false }` is the tool's error.
+     */
+    setValue: (name: string, value: unknown) => FormAdapterCommit;
+    /**
+     * Set many at once, ideally as one host commit. Same sync/async contract as
+     * `setValue`. When absent, the bridge awaits `setValue` once per field in
+     * order and stops at the first refusal (so that path is NOT atomic).
+     */
+    setValues?: (values: Record<string, unknown>) => FormAdapterCommit;
     /** Programmatically focus a field (host implements DOM focus). Optional. */
     focus?: (name: string) => void;
     /** Submit the form. Returns the values that were submitted (or rejection). */
@@ -64,6 +80,31 @@ type FormBridgeAdapter = {
      */
     confirm?: (request: FormConfirmRequest) => Promise<boolean> | boolean;
 };
+/**
+ * What an async `setValue` / `setValues` may resolve to, to acknowledge (or
+ * refuse) a write. `{ ok: false }` is a refusal the agent can act on: `error`
+ * is shown to the agent verbatim, so keep it a human-readable sentence (e.g.
+ * "Draft changed since you read it; re-read and retry"), never a stack trace or
+ * an internal path. `code` (e.g. `"stale"`, `"forbidden"`) is for the host's own
+ * use; it is not shown to the agent.
+ */
+type FormAdapterResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * Return type of `setValue` / `setValues`. A sync `void` return keeps the
+ * original behaviour. A Promise makes the bridge WAIT: the tool reports
+ * success, and emits its AgentActivity event, only after the promise resolves
+ * (to `void` or `{ ok: true }`). A rejection or `{ ok: false }` becomes that
+ * tool call's error result and emits no activity. If the bridge is disposed
+ * while the write is pending, the call settles at once as an error saying the
+ * outcome is unknown, and a later settle is ignored.
+ */
+type FormAdapterCommit = void | Promise<void | FormAdapterResult>;
 /** What a `form_submit` confirm gate is asked to approve. */
 type FormConfirmRequest = {
     action: "submit";
@@ -88,10 +129,21 @@ type FormBridgeOptions = {
     pendingMode?: boolean;
 };
 /**
- * registerFormBridge — wires schema-driven MCP access to a single form.
- * Hosts can register multiple bridges (one per form on the screen) by
- * giving each adapter a distinct `id`.
+ * registerFormBridge — wires schema-driven MCP access to a form.
+ *
+ * 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;
 
-export { type FormBridgeAdapter, type FormBridgeOptions, type FormConfirmRequest, type FormFieldDescriptor, registerFormBridge };
+export { type FormAdapterCommit, type FormAdapterResult, type FormBridgeAdapter, type FormBridgeOptions, type FormConfirmRequest, type FormFieldDescriptor, registerFormBridge };

package/dist/bridges/forms.d.ts

@@ -29,6 +29,14 @@ type FormFieldDescriptor = {
  * Adapter the host wires per form. Matches the controlled-state pattern
  * react-fancy already uses (`value` / `onValueChange`); this adapter just
  * exposes those state slots in a form-shaped way the bridge can call.
+ *
+ * `setValue` / `setValues` may be sync (`void`) or async (a Promise); see
+ * {@link FormAdapterCommit}. Return a Promise when the host's write is
+ * authoritative — a persisted draft, or one the host can refuse or report
+ * stale — so the agent is told the truth instead of "success" before anything
+ * was accepted.
+ *
+ * This bridge pushes NO undo entries: `agent_undo` cannot revert a form write.
  */
 type FormBridgeAdapter = {
     /** Stable id for the form (used in form_describe + presence target). */
@@ -44,10 +52,18 @@ type FormBridgeAdapter = {
     getValue: (name: string) => unknown;
     /** Read all values as { fieldName: value }. */
     getValues: () => Record<string, unknown>;
-    /** Set a single field's value. The host wires this to its setState. */
-    setValue: (name: string, value: unknown) => void;
-    /** Set many at once. Defaults to calling setValue in a loop. */
-    setValues?: (values: Record<string, unknown>) => void;
+    /**
+     * Set a single field's value. The host wires this to its setState, or to
+     * an authoritative write it awaits. Sync `void` behaves as it always has; a
+     * Promise is awaited, and a rejection or `{ ok: false }` is the tool's error.
+     */
+    setValue: (name: string, value: unknown) => FormAdapterCommit;
+    /**
+     * Set many at once, ideally as one host commit. Same sync/async contract as
+     * `setValue`. When absent, the bridge awaits `setValue` once per field in
+     * order and stops at the first refusal (so that path is NOT atomic).
+     */
+    setValues?: (values: Record<string, unknown>) => FormAdapterCommit;
     /** Programmatically focus a field (host implements DOM focus). Optional. */
     focus?: (name: string) => void;
     /** Submit the form. Returns the values that were submitted (or rejection). */
@@ -64,6 +80,31 @@ type FormBridgeAdapter = {
      */
     confirm?: (request: FormConfirmRequest) => Promise<boolean> | boolean;
 };
+/**
+ * What an async `setValue` / `setValues` may resolve to, to acknowledge (or
+ * refuse) a write. `{ ok: false }` is a refusal the agent can act on: `error`
+ * is shown to the agent verbatim, so keep it a human-readable sentence (e.g.
+ * "Draft changed since you read it; re-read and retry"), never a stack trace or
+ * an internal path. `code` (e.g. `"stale"`, `"forbidden"`) is for the host's own
+ * use; it is not shown to the agent.
+ */
+type FormAdapterResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * Return type of `setValue` / `setValues`. A sync `void` return keeps the
+ * original behaviour. A Promise makes the bridge WAIT: the tool reports
+ * success, and emits its AgentActivity event, only after the promise resolves
+ * (to `void` or `{ ok: true }`). A rejection or `{ ok: false }` becomes that
+ * tool call's error result and emits no activity. If the bridge is disposed
+ * while the write is pending, the call settles at once as an error saying the
+ * outcome is unknown, and a later settle is ignored.
+ */
+type FormAdapterCommit = void | Promise<void | FormAdapterResult>;
 /** What a `form_submit` confirm gate is asked to approve. */
 type FormConfirmRequest = {
     action: "submit";
@@ -88,10 +129,21 @@ type FormBridgeOptions = {
     pendingMode?: boolean;
 };
 /**
- * registerFormBridge — wires schema-driven MCP access to a single form.
- * Hosts can register multiple bridges (one per form on the screen) by
- * giving each adapter a distinct `id`.
+ * registerFormBridge — wires schema-driven MCP access to a form.
+ *
+ * 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;
 
-export { type FormBridgeAdapter, type FormBridgeOptions, type FormConfirmRequest, type FormFieldDescriptor, registerFormBridge };
+export { type FormAdapterCommit, type FormAdapterResult, type FormBridgeAdapter, type FormBridgeOptions, type FormConfirmRequest, type FormFieldDescriptor, registerFormBridge };