@particle-academy/agent-integrations 0.50.0 → 0.52.0

package/CHANGELOG.md

@@ -11,6 +11,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **BREAKING: `registerTool` refuses a tool name already held by a different
+  registrant.** It used to replace the existing tool silently, so when two
+  bridges or two agents in one app registered the same name, the second won.
+  The first stayed in `tools/list`, but every call reached the second handler
+  and nothing reported it. That breaks multi-agent apps. It now throws an
+  `Error` naming the tool and both owners, and leaves the first registration in
+  place.
+  **What to do:**
+  - **If you only use the bridges, nothing.** Every first-party bridge now
+    registers under its bridge id (`"whiteboard"`, `` `chart:${adapter.id}` ``,
+    `` `form:${adapter.id}` ``, …), so a remount of the same bridge still
+    re-registers, with or without a dispose in between. The shared undo tools
+    (`agent_undo` / `agent_redo` / `agent_history`) register under one owner,
+    `"agent-undo"`, so `ensureUndoToolsRegistered` and a direct
+    `registerUndoTools` call on the same host still coexist, as the showcase
+    playground does. A census of every first-party bridge found **no two
+    bridges sharing a tool name**, and all of them mount on one host together.
+  - **If you mount two instances of a multi-instance bridge on ONE host** (two
+    charts, grids, code editors, forms, scenes, catalogs, feature panels or
+    passkey surfaces with different adapter ids), the second now throws. Their
+    tool names were never instance-scoped, so the second instance had already
+    taken over the first's tools and the first was not drivable. Give each
+    instance its own host, or drive both through one adapter.
+  - **If you call `registerTool` yourself**, pass `{ owner: "<your surface>" }`.
+    The same owner may re-register its own names. A registration with no owner
+    can be identified by nothing, so it never counts as the same registrant:
+    registering an unowned name twice without disposing the first now throws.
+    If you re-register by name on purpose to swap a handler, either pass the
+    same `owner` both times or pass `{ replace: true }`, the explicit opt-in for
+    the old behaviour. No first-party consumer relies on overwriting another
+    registrant: `fancy-flow-mcp-js` registers each name once per server, and
+    the only repeat in the showcase is the playground registering the undo
+    tools itself before its bridges ensure them, which is one owner.
+
+### Added
+
+- `RegisterToolOptions` (`owner`, `replace`), the optional third argument of
+  `ToolHost.registerTool`, exported from the package root and `/mcp`. Custom
+  `ToolHost` implementations keep compiling: the argument is optional.
+
+### Fixed
+
+- **A late disposer no longer withdraws the registration that replaced it.** A
+  disposer used to delete whatever held the name, so a remount whose first
+  cleanup ran after the second mount unregistered the live tool. A disposer now
+  removes only the registration it returned from.
+
 ## [0.50.0] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -140,6 +140,64 @@ 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**, 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
+[`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
@@ -198,6 +256,17 @@ ends are delivered before the transport closes.
 Import `/mcp/stdio` only from Node. Browser bundles import `/mcp`, which never
 pulls it in.
 
+**A tool name belongs to whoever registered it.** `registerTool` throws when a
+name is already held by a different registrant, and the error names both. Pass
+`{ owner }` to identify yourself: the same owner may register a name again (a
+React remount does), and every bridge already registers under its bridge id.
+Disposing frees the name. To take over another registrant's tool on purpose,
+pass `{ replace: true }`.
+
+```ts
+server.registerTool(definition, handler, { owner: "support-triage" });
+```
+
 ## Connect an agent to your app — `<ConnectorButtons>`
 
 The step *before* presence: getting your MCP server installed in the user's

package/dist/bridges/artboard.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Transport-level JSON shapes. These intentionally mirror fancy-artboard's

package/dist/bridges/artboard.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Transport-level JSON shapes. These intentionally mirror fancy-artboard's

package/dist/bridges/catalog.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Headless bridge for `@particle-academy/fancy-catalog` — a Stripe catalog with

package/dist/bridges/catalog.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Headless bridge for `@particle-academy/fancy-catalog` — a Stripe catalog with

package/dist/bridges/charts.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Adapter wires a single fancy-echarts chart to the bridge. Charts are

package/dist/bridges/charts.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Adapter wires a single fancy-echarts chart to the bridge. Charts are

package/dist/bridges/cms.d.cts

@@ -1,8 +1,8 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
 import { DocAdapter } from './doc.cjs';
 import { StyledNode, StagePolicy, TreeOp, StyleProps, LayoutMode, DocReducer, DocTree } from '@particle-academy/fancy-doc-commons';
-import '../types-gzIpsUDE.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * registerCmsBridge — the greenfield CMS agent bridge, built entirely on

package/dist/bridges/cms.d.ts

@@ -1,8 +1,8 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
 import { DocAdapter } from './doc.js';
 import { StyledNode, StagePolicy, TreeOp, StyleProps, LayoutMode, DocReducer, DocTree } from '@particle-academy/fancy-doc-commons';
-import '../types-gzIpsUDE.js';
+import '../types-ITRQFAir.js';
 
 /**
  * registerCmsBridge — the greenfield CMS agent bridge, built entirely on

package/dist/bridges/code.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Adapter the host wires to a fancy-code CodeEditor (typically via the

package/dist/bridges/code.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Adapter the host wires to a fancy-code CodeEditor (typically via the

package/dist/bridges/doc.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { J as JsonObject } from '../types-gzIpsUDE.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { J as JsonObject } from '../types-ITRQFAir.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
 import { DocNode, DocTree, TreeOp, DocReducer, StagePolicy } from '@particle-academy/fancy-doc-commons';
 
 /** Host-provided access to the document tree. */

package/dist/bridges/doc.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { J as JsonObject } from '../types-gzIpsUDE.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { J as JsonObject } from '../types-ITRQFAir.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
 import { DocNode, DocTree, TreeOp, DocReducer, StagePolicy } from '@particle-academy/fancy-doc-commons';
 
 /** Host-provided access to the document tree. */

package/dist/bridges/features.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Headless bridge for `@particle-academy/fancy-features` — feature management

package/dist/bridges/features.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Headless bridge for `@particle-academy/fancy-features` — feature management

package/dist/bridges/files.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 type FileKind = "file" | "dir";
 type FileEntry = {

package/dist/bridges/files.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 type FileKind = "file" | "dir";
 type FileEntry = {

package/dist/bridges/flow.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 type FlowNode = {
     id: string;

package/dist/bridges/flow.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 type FlowNode = {
     id: string;

package/dist/bridges/forms.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Field descriptor — what the host says about each form field. Mirrors the
@@ -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";
@@ -89,9 +130,13 @@ type FormBridgeOptions = {
 };
 /**
  * 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`.
+ *
+ * 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`.
  */
 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

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Field descriptor — what the host says about each form field. Mirrors the
@@ -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";
@@ -89,9 +130,13 @@ type FormBridgeOptions = {
 };
 /**
  * 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`.
+ *
+ * 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`.
  */
 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/git.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 type GitProposal = {
     operation: string;

package/dist/bridges/git.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 type GitProposal = {
     operation: string;

package/dist/bridges/grid.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 /**
  * Loose grid types — the public state shape of `@particle-academy/fancy-grid`,

package/dist/bridges/grid.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
-import { B as Bridge } from '../types-VX_9je7w.js';
-import '../types-gzIpsUDE.js';
+import { T as ToolHost } from '../tool-host-BqJRPr_T.js';
+import { B as Bridge } from '../types-D_TzdBsK.js';
+import '../types-ITRQFAir.js';
 
 /**
  * Loose grid types — the public state shape of `@particle-academy/fancy-grid`,

package/dist/bridges/map.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
-import { B as Bridge } from '../types-DP5yQZQU.cjs';
-import '../types-gzIpsUDE.cjs';
+import { T as ToolHost } from '../tool-host-BBSaU7IJ.cjs';
+import { B as Bridge } from '../types-D_H2f-wF.cjs';
+import '../types-ITRQFAir.cjs';
 
 type LatLng = {
     lat: number;