@particle-academy/agent-integrations 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -11,6 +11,46 @@ 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

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

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";
@@ -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

@@ -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.cjs

@@ -126,6 +126,31 @@ function serialize(entry) {
   };
 }
 
+// src/bridges/host-commit.ts
+function hostErrorMessage(e, fallback) {
+  let msg;
+  if (e instanceof Error) msg = e.message;
+  else if (typeof e === "string") msg = e;
+  else if (e && typeof e === "object" && typeof e.message === "string") {
+    msg = e.message;
+  }
+  const firstFrame = msg ? msg.search(/\n\s+at\s/) : -1;
+  if (msg && firstFrame >= 0) msg = msg.slice(0, firstFrame);
+  msg = msg?.trim();
+  return msg ? msg : fallback;
+}
+async function commit(run, fallback) {
+  try {
+    const r = await run();
+    if (r && typeof r === "object" && r.ok === false) {
+      return { ok: false, error: hostErrorMessage(r.error, fallback) };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: hostErrorMessage(e, fallback) };
+  }
+}
+
 // src/bridges/forms.ts
 var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
 function registerFormBridge(host, options) {
@@ -136,6 +161,33 @@ function registerFormBridge(host, options) {
   const bridgeId = `form:${adapter.id}`;
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const formId = adapter.id;
+  let disposed = false;
+  const onDispose = /* @__PURE__ */ new Set();
+  const CLOSED = /* @__PURE__ */ Symbol("form-closed");
+  const untilClosed = (p) => {
+    if (disposed) {
+      p.catch(() => {
+      });
+      return Promise.resolve(CLOSED);
+    }
+    return new Promise((resolve, reject) => {
+      const close = () => resolve(CLOSED);
+      onDispose.add(close);
+      p.then(
+        (v) => {
+          onDispose.delete(close);
+          resolve(v);
+        },
+        (e) => {
+          onDispose.delete(close);
+          reject(e);
+        }
+      );
+    });
+  };
+  const closedUnknown = (what) => errorResult(
+    `Form "${formId}" was closed before the host confirmed ${what}, so whether it was applied is unknown. Do not assume it was. If the form is open again, read it back (form_get_values) before retrying.`
+  );
   const target = (args) => ({
     kind: "form",
     screenId: adapter.screenId,
@@ -147,7 +199,7 @@ function registerFormBridge(host, options) {
       try {
         return await handler(args);
       } catch (e) {
-        return errorResult(e instanceof Error ? e.message : String(e));
+        return errorResult(hostErrorMessage(e, `${name} failed.`));
       }
     };
     const final = isMutation ? wrapToolWithActivity(wrapped, {
@@ -215,11 +267,15 @@ function registerFormBridge(host, options) {
       value: { description: "Value to set. Type depends on the field's `type`." }
     },
     ["field", "value"],
-    (args) => {
+    async (args) => {
       const name = String(args.field ?? "");
       const fieldDef = adapter.getFields().find((f) => f.name === name);
       if (!fieldDef) return errorResult(`Unknown field: ${name}`);
-      adapter.setValue(name, args.value);
+      const done = await untilClosed(
+        commit(() => adapter.setValue(name, args.value), `Host refused the write to "${name}".`)
+      );
+      if (done === CLOSED) return closedUnknown(`the write to "${name}"`);
+      if (!done.ok) return errorResult(done.error);
       return textResult(`${name} \u2190 ${JSON.stringify(args.value)}`, { field: name, value: args.value });
     },
     true
@@ -229,16 +285,52 @@ function registerFormBridge(host, options) {
     "Set multiple fields atomically. Pass a `values` object keyed by field name.",
     { values: { type: "object" } },
     ["values"],
-    (args) => {
+    async (args) => {
       const values = args.values && typeof args.values === "object" ? args.values : {};
       const fields = adapter.getFields();
       const known = new Set(fields.map((f) => f.name));
       const unknownKeys = Object.keys(values).filter((k) => !known.has(k));
       if (unknownKeys.length) return errorResult(`Unknown fields: ${unknownKeys.join(", ")}`);
-      if (adapter.setValues) {
-        adapter.setValues(values);
+      const setValues = adapter.setValues;
+      if (setValues) {
+        const done = await untilClosed(commit(() => setValues(values), "Host refused the write."));
+        if (done === CLOSED) return closedUnknown("the write");
+        if (!done.ok) return errorResult(done.error);
       } else {
-        for (const [k, v] of Object.entries(values)) adapter.setValue(k, v);
+        const keys = Object.keys(values);
+        const committed = [];
+        for (const [i, k] of keys.entries()) {
+          const done = await untilClosed(
+            commit(() => adapter.setValue(k, values[k]), `Host refused the write to "${k}".`)
+          );
+          if (done === CLOSED) {
+            return {
+              ...closedUnknown(`the write to "${k}"`),
+              structuredContent: { committed, pending: k, notAttempted: keys.slice(i + 1) }
+            };
+          }
+          if (!done.ok) {
+            const state = { committed, failed: k, notAttempted: keys.slice(i + 1) };
+            if (committed.length) {
+              fancyAutoCommon.emitActivity({
+                agentId: agent.id,
+                agentName: agent.name,
+                agentColor: agent.color,
+                target: target({}),
+                action: "form_set_values",
+                timestamp: Date.now(),
+                meta: state
+              });
+            }
+            return {
+              ...errorResult(
+                `"${k}" was refused: ${done.error} ` + (committed.length ? `Already committed and NOT rolled back: ${committed.join(", ")}. ` : "Nothing was committed. ") + (state.notAttempted.length ? `Not attempted: ${state.notAttempted.join(", ")}.` : "")
+              ),
+              structuredContent: state
+            };
+          }
+          committed.push(k);
+        }
       }
       return textResult(`Set ${Object.keys(values).length} field(s)`, { values });
     },
@@ -268,16 +360,22 @@ function registerFormBridge(host, options) {
     async () => {
       if (!adapter.submit) return errorResult("Host did not provide a submit implementation.");
       if (pendingMode && adapter.confirm) {
-        const ok = await adapter.confirm({
+        const confirm = adapter.confirm;
+        const ok = await untilClosed(Promise.resolve().then(() => confirm({
           action: "submit",
           form: formId,
           title: adapter.title,
           values: adapter.getValues()
-        });
+        })));
+        if (ok === CLOSED) {
+          return errorResult(`Form "${formId}" was closed before the submit was confirmed. Nothing was submitted.`);
+        }
         if (!ok) return errorResult("Declined by user");
       }
-      const result = await adapter.submit();
-      if (!result.ok) return errorResult(result.error ?? "Submit failed");
+      const submit = adapter.submit;
+      const result = await untilClosed(Promise.resolve().then(() => submit()));
+      if (result === CLOSED) return closedUnknown("the submit");
+      if (!result.ok) return errorResult(hostErrorMessage(result.error, "Submit failed"));
       return textResult("Submitted", { values: result.values });
     },
     true
@@ -286,7 +384,10 @@ function registerFormBridge(host, options) {
     id: bridgeId,
     title: adapter.title ?? formId,
     dispose: () => {
+      disposed = true;
       for (const d of disposers) d();
+      for (const close of [...onDispose]) close();
+      onDispose.clear();
     }
   };
 }