@particle-academy/agent-integrations 0.51.0 → 0.53.0

package/dist/bridges-forms.cjs

@@ -126,28 +126,248 @@ 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/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");
+  const untilClosed = (p) => {
+    if (disposed) {
+      p.catch(() => {
+      });
+      return Promise.resolve(CLOSED);
+    }
+    return new Promise((resolve2, reject) => {
+      const close = () => resolve2(CLOSED);
+      onDispose.add(close);
+      p.then(
+        (v) => {
+          onDispose.delete(close);
+          resolve2(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,
     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);
       } catch (e) {
-        return errorResult(e instanceof Error ? e.message : String(e));
+        return errorResult(hostErrorMessage(e, `${name} failed.`));
       }
     };
     const final = isMutation ? wrapToolWithActivity(wrapped, {
@@ -157,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");
@@ -183,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)) {
@@ -198,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);
@@ -209,36 +410,67 @@ 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"],
-    (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
   );
   reg(
     "form_set_values",
-    "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 });
     },
@@ -246,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.");
@@ -262,31 +491,44 @@ 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) {
-        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
   );
+  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: () => {
-      for (const d of disposers) d();
+      if (disposed) return;
+      disposed = true;
+      membership.leave();
+      for (const close of [...onDispose]) close();
+      onDispose.clear();
     }
   };
 }