@particle-academy/agent-integrations 0.52.0 → 0.53.0

package/dist/index.js

@@ -34,8 +34,8 @@ export { registerMapBridge } from './chunk-QEVSNDJW.js';
 export { RelayTransport, attachRelay } from './chunk-G6N2TQVO.js';
 import { attachInProcess } from './chunk-AFUULW5E.js';
 export { InProcessTransport, attachInProcess } from './chunk-AFUULW5E.js';
-import { registerFormBridge } from './chunk-AL77RO25.js';
-export { registerFormBridge } from './chunk-AL77RO25.js';
+import { registerFormBridge } from './chunk-AET2R7DJ.js';
+export { registerFormBridge } from './chunk-AET2R7DJ.js';
 import './chunk-DPBAEWB5.js';
 export { registerSheetsBridge } from './chunk-S4DA2UTJ.js';
 export { clearStack as clearUndoStack, ensureUndoToolsRegistered, pushUndoEntry, readHistory as readUndoHistory, redoOne, registerUndoTools, resetAllUndoStacks, undoOne } from './chunk-ZDKYKJFH.js';

package/docs/multi-form-hosts.md

@@ -1,9 +1,11 @@
 # Several forms on one host — design note
 
-**Status: proposal, not implemented. The choice is the owner's.** Written
-2026-10-30 against 0.51.0, prompted by a consumer asking for the supported model.
+**Status: option A is BUILT (0.53.0).** The owner chose A on 2026-10-30. The
+proposal below is kept as written against 0.51.0 for the reasoning; "Where it
+stands" describes the state before 0.53.0. What was built, and what another
+bridge would need to adopt it, is at the end ("As built").
 
-## Where it stands
+## Where it stood (0.51.0 and 0.52.0)
 
 `registerFormBridge` registers `form_describe`, `form_get_value`,
 `form_get_values`, `form_set_value`, `form_set_values`, `form_focus` and
@@ -20,7 +22,7 @@ surfaces. Whatever is chosen for forms should be the pattern for those too.
 There is already one precedent for scoping: `registerScreenDocBridge` takes a
 `surface` option that prefixes its tool names (`screen_checkout_add`).
 
-Today's supported answer is **one form bridge per host**.
+Until 0.53.0 the supported answer was **one form bridge per host**.
 
 ## Options
 
@@ -95,3 +97,67 @@ form mounted every existing call shape still succeeds; disposing one form leaves
 the other drivable and settles only the disposed form's pending writes; a remount
 of the same id re-joins rather than duplicating; `form_list` reflects mounts and
 unmounts.
+
+## As built (0.53.0)
+
+- `src/bridges/multi-instance.ts` holds the shared piece, `joinInstanceRouter`.
+  It is internal (no entry point). It keeps one router per (host, family) in a
+  `WeakMap`, calls the family's `install` once when the first instance joins,
+  and calls the disposer `install` returned when the last instance leaves. It
+  also resolves the selecting argument by the rules below. If `install` throws
+  because a name is held by an unrelated registrant, no router is left behind.
+- `registerFormBridge` builds its handlers per form, with that form's adapter,
+  `pendingMode`, `agent` and close handling, then joins the `"form"` router. The
+  shared tools are registered once, under the single owner `"form-bridge"`.
+  Each one resolves `form` and then calls the chosen form's handler, so the
+  activity, presence target and outcome-unknown settling stay per form.
+- Resolution: with exactly one form mounted `form` is optional. With two or
+  more, a call without it is an error listing the ids. An id that is not
+  mounted is an error listing the ids, even when only one form is mounted, so a
+  call aimed at a form that has closed never lands on another one.
+- A registration whose `adapter.id` is already mounted **replaces** it. A
+  duplicate cannot be told apart from a remount whose cleanup has not run yet,
+  and 0.51.0 already let the same form re-register, so this keeps that
+  behaviour. The earlier registration's `dispose()` then leaves the newer one
+  in place. A missing or empty `adapter.id` throws.
+- Tool descriptions are now generic (the "Cons" above). `form_describe` still
+  returns the form's `id` and `title` in its result.
+
+Acceptance tests: `src/bridges/__tests__/forms-multi.test.ts` (the form
+behaviour) and `src/bridges/__tests__/multi-instance.test.ts` (the helper).
+
+### Adopting it in another bridge (charts, grids, code, scene, …)
+
+Charts and grids have the same shape as forms did: tools named for the family
+(`chart_set_option`, `grid_sort`), a registrant id carrying `adapter.id`, and
+handlers that close over one adapter. Adopting the router takes four steps:
+
+1. **Lift the tool definitions out of the factory** into a module-level list,
+   and add the selecting argument (`chart`, `grid`) to every tool's schema as
+   an optional string.
+2. **Build the handlers per instance** inside `register<X>Bridge`, wrapped with
+   `wrapToolWithActivity` using that instance's agent and `screenId`, into a
+   `name -> handler` record. Today they are registered directly.
+3. **Write an `install(router)`** that registers each shared tool under one
+   family owner (`"chart-bridge"`). Its handler calls
+   `router.resolve(args.<argument>)`, returns the error if resolution fails,
+   and otherwise calls `instance.handlers[name](args)`. Add a `<family>_list`
+   tool. On a registration failure, withdraw whatever was already registered
+   and rethrow, as `installFormTools` does.
+4. **Join and leave.** Call `joinInstanceRouter(host, { family, argument,
+   listTool, install }, adapter.id, { adapter, handlers })`, and make the
+   bridge's `dispose()` call `leave()` and then settle anything that
+   instance still has pending.
+
+Per-bridge points to check:
+
+- **Undo** (grid, charts): `pushUndoEntry` closes over the instance's own
+  adapter, so it is per instance already. The entry's `bridgeId`
+  (`grid:<id>`) should keep naming the instance.
+- **Descriptions** that name the instance today become generic. The
+  `<family>_list` result carries the names instead.
+- **Census:** `tool-name-census.test.ts` builds each bridge with a proxy
+  adapter whose `id` is not a string. Coerce the id with `String(...)` as
+  `registerFormBridge` does, or the census throws.
+- Bridges that already scope their names (screen-doc's `surface`) or are
+  inherently singletons (navigation, screens, tui) should not adopt it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/agent-integrations",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "MCP-driven agent presence in collab sessions: per-session micro-MCP server, pluggable bridges to fancy-* packages, and agent UX components (panel + on-canvas cursor).",
   "repository": {
     "type": "git",

package/dist/chunk-AL77RO25.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/bridges/forms.ts"],"names":[],"mappings":"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","file":"chunk-AL77RO25.js","sourcesContent":["import { textResult, errorResult } from \"../mcp/server\";\nimport type { ToolHost } from \"../mcp/tool-host\";\nimport type { JsonObject } from \"../mcp/types\";\nimport type { Bridge } from \"./types\";\nimport { wrapToolWithActivity } from \"../presence/wrap-tool-with-activity\";\nimport { ensureUndoToolsRegistered } from \"../undo/undo-tools\";\nimport type { AgentTarget } from \"../presence/types\";\nimport { emitActivity } from \"../presence/registry\";\nimport { commit, hostErrorMessage } from \"./host-commit\";\n\n/**\n * Field descriptor — what the host says about each form field. Mirrors the\n * subset of HTML / react-fancy input shapes agents care about.\n */\nexport type FormFieldDescriptor = {\n  /** Form-local field name. Matches the key the host uses in its values map. */\n  name: string;\n  /** Display label. */\n  label?: string;\n  /** Logical type. Drives validation + agent expectations. */\n  type:\n    | \"text\"\n    | \"textarea\"\n    | \"number\"\n    | \"email\"\n    | \"password\"\n    | \"url\"\n    | \"date\"\n    | \"select\"\n    | \"multi-select\"\n    | \"checkbox\"\n    | \"switch\"\n    | \"radio\"\n    | \"file\"\n    | \"json\";\n  /** Allowed values for select / radio. */\n  options?: Array<{ value: string; label: string }>;\n  /** Whether the field must be filled before submit. */\n  required?: boolean;\n  /** Free-text hint surfaced to the agent. */\n  description?: string;\n  /** Default value (presented in get_value when nothing set). */\n  defaultValue?: unknown;\n};\n\n/**\n * Adapter the host wires per form. Matches the controlled-state pattern\n * react-fancy already uses (`value` / `onValueChange`); this adapter just\n * exposes those state slots in a form-shaped way the bridge can call.\n *\n * `setValue` / `setValues` may be sync (`void`) or async (a Promise); see\n * {@link FormAdapterCommit}. Return a Promise when the host's write is\n * authoritative — a persisted draft, or one the host can refuse or report\n * stale — so the agent is told the truth instead of \"success\" before anything\n * was accepted.\n *\n * This bridge pushes NO undo entries: `agent_undo` cannot revert a form write.\n */\nexport type FormBridgeAdapter = {\n  /** Stable id for the form (used in form_describe + presence target). */\n  id: string;\n  /** Display title for human-readable logs. */\n  title?: string;\n  /** Optional fancy-screens screen id this form belongs to. */\n  screenId?: string;\n  /** Field descriptors. The bridge uses these for schema introspection\n   *  (form_describe). Agents call this first to know what to fill. */\n  getFields: () => FormFieldDescriptor[];\n  /** Read a single field's current value. */\n  getValue: (name: string) => unknown;\n  /** Read all values as { fieldName: value }. */\n  getValues: () => Record<string, unknown>;\n  /**\n   * Set a single field's value. The host wires this to its setState, or to\n   * an authoritative write it awaits. Sync `void` behaves as it always has; a\n   * Promise is awaited, and a rejection or `{ ok: false }` is the tool's error.\n   */\n  setValue: (name: string, value: unknown) => FormAdapterCommit;\n  /**\n   * Set many at once, ideally as one host commit. Same sync/async contract as\n   * `setValue`. When absent, the bridge awaits `setValue` once per field in\n   * order and stops at the first refusal (so that path is NOT atomic).\n   */\n  setValues?: (values: Record<string, unknown>) => FormAdapterCommit;\n  /** Programmatically focus a field (host implements DOM focus). Optional. */\n  focus?: (name: string) => void;\n  /** Submit the form. Returns the values that were submitted (or rejection). */\n  submit?: () => Promise<{ ok: boolean; values?: Record<string, unknown>; error?: string }>;\n  /**\n   * Human confirm gate for `form_submit` (trust-but-verify). When `pendingMode`\n   * is on, the bridge calls this before submitting; return false to decline.\n   * Wire it to a human control — submitting a form is a human-visible,\n   * often-destructive action (checkout, delete, invite).\n   */\n  confirm?: (request: FormConfirmRequest) => Promise<boolean> | boolean;\n};\n\n/**\n * What an async `setValue` / `setValues` may resolve to, to acknowledge (or\n * refuse) a write. `{ ok: false }` is a refusal the agent can act on: `error`\n * is shown to the agent verbatim, so keep it a human-readable sentence (e.g.\n * \"Draft changed since you read it; re-read and retry\"), never a stack trace or\n * an internal path. `code` (e.g. `\"stale\"`, `\"forbidden\"`) is for the host's own\n * use; it is not shown to the agent.\n */\nexport type FormAdapterResult = { ok: true } | { ok: false; error: string; code?: string };\n\n/**\n * Return type of `setValue` / `setValues`. A sync `void` return keeps the\n * original behaviour. A Promise makes the bridge WAIT: the tool reports\n * success, and emits its AgentActivity event, only after the promise resolves\n * (to `void` or `{ ok: true }`). A rejection or `{ ok: false }` becomes that\n * tool call's error result and emits no activity. If the bridge is disposed\n * while the write is pending, the call settles at once as an error saying the\n * outcome is unknown, and a later settle is ignored.\n */\nexport type FormAdapterCommit = void | Promise<void | FormAdapterResult>;\n\n/** What a `form_submit` confirm gate is asked to approve. */\nexport type FormConfirmRequest = {\n  action: \"submit\";\n  form: string;\n  title?: string;\n  values: Record<string, unknown>;\n};\n\nexport type FormBridgeOptions = {\n  adapter: FormBridgeAdapter;\n  /** Identity tagged into activity events. */\n  agent?: { id: string; name?: string; color?: string };\n  /**\n   * Stage `form_submit` for human confirmation via `adapter.confirm` instead of\n   * submitting immediately. **Default: ON** (matches the navigation bridge and\n   * the Human+ trust-but-verify contract). Set false only when auto-submit is\n   * safe. If on without an `adapter.confirm`, submit proceeds (nothing to gate).\n   */\n  pendingMode?: boolean;\n};\n\nconst DEFAULT_AGENT = { id: \"agent\", name: \"Agent\", color: \"#a855f7\" };\n\n/**\n * registerFormBridge — wires schema-driven MCP access to a single form.\n *\n * ONE form bridge per host. The tool names (`form_set_value`, …) are not\n * scoped to the form id, so since 0.51.0 a second form bridge with a different\n * adapter id on the same host throws (the duplicate-registrant refusal); a\n * remount of the SAME form re-registers fine. For several forms, give each its\n * own host for now — see `docs/multi-form-hosts.md`.\n */\nexport function registerFormBridge(\n  host: ToolHost,\n  options: FormBridgeOptions,\n): Bridge {\n  const { adapter } = options;\n  const agent = { ...DEFAULT_AGENT, ...(options.agent ?? {}) };\n  const pendingMode = options.pendingMode ?? true;\n  const disposers: Array<() => void> = [];\n  // The bridge id is also its registrant identity on the host: the same bridge\n  // may re-register (a remount), a different one claiming a name is refused.\n  const bridgeId = `form:${adapter.id}`;\n\n  // agent_undo / agent_redo / agent_history are registered whenever any bridge\n  // mounts, so undo availability doesn't hinge on which bridges are co-present.\n  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });\n  const formId = adapter.id;\n\n  // Close handling. A host may dispose the bridge (the form unmounts) while a\n  // write or a human confirm is still pending; its promise may then never\n  // settle. Every awaited host call is raced against dispose, so the tool call\n  // settles at once instead of hanging, and a late settle is ignored.\n  let disposed = false;\n  const onDispose = new Set<() => void>();\n  const CLOSED: unique symbol = Symbol(\"form-closed\");\n  const untilClosed = <T>(p: Promise<T>): Promise<T | typeof CLOSED> => {\n    if (disposed) {\n      p.catch(() => {}); // a late rejection must never be unhandled\n      return Promise.resolve(CLOSED);\n    }\n    return new Promise<T | typeof CLOSED>((resolve, reject) => {\n      const close = () => resolve(CLOSED);\n      onDispose.add(close);\n      p.then(\n        (v) => { onDispose.delete(close); resolve(v); },\n        (e) => { onDispose.delete(close); reject(e); },\n      );\n    });\n  };\n  const closedUnknown = (what: string) =>\n    errorResult(\n      `Form \"${formId}\" was closed before the host confirmed ${what}, so whether it was applied is unknown. ` +\n        \"Do not assume it was. If the form is open again, read it back (form_get_values) before retrying.\",\n    );\n\n  const target =(args: any): AgentTarget => ({\n    kind: \"form\",\n    screenId: adapter.screenId,\n    elementId: typeof args?.field === \"string\" ? `${formId}:${args.field}` : formId,\n    label: typeof args?.field === \"string\"\n      ? `${adapter.title ?? formId} → ${args.field}`\n      : adapter.title ?? formId,\n  });\n\n  const reg = (\n    name: string,\n    description: string,\n    properties: Record<string, unknown>,\n    required: string[],\n    handler: (args: JsonObject) => Promise<any> | any,\n    isMutation: boolean,\n  ) => {\n    const wrapped = async (args: JsonObject) => {\n      try {\n        return await handler(args);\n      } catch (e) {\n        return errorResult(hostErrorMessage(e, `${name} failed.`));\n      }\n    };\n    const final = isMutation\n      ? wrapToolWithActivity(wrapped, {\n          toolName: name,\n          agent: { id: agent.id, name: agent.name, color: agent.color },\n          kind: \"form\",\n          screenId: adapter.screenId,\n          resolveTarget: ({ args }) => target(args),\n        })\n      : wrapped;\n    disposers.push(\n      host.registerTool(\n        {\n          name,\n          description,\n          inputSchema: { type: \"object\", properties: properties as any, required, additionalProperties: false },\n        },\n        final as any,\n        { owner: bridgeId },\n      ),\n    );\n  };\n\n  // ───────────── Read tools ─────────────\n\n  reg(\n    \"form_describe\",\n    `Describe the form \"${formId}\" — fields, types, options, required flags. Call this first to know what's fillable.`,\n    {},\n    [],\n    () => {\n      const fields = adapter.getFields();\n      const text = fields\n        .map((f) => `${f.name}${f.required ? \"*\" : \"\"} (${f.type})${f.label ? ` — ${f.label}` : \"\"}`)\n        .join(\"\\n\");\n      return textResult(text || \"(no fields)\", { id: formId, title: adapter.title, fields });\n    },\n    false,\n  );\n\n  reg(\n    \"form_get_value\",\n    \"Read a single field's current value.\",\n    { field: { type: \"string\" } },\n    [\"field\"],\n    (args) => {\n      const name = String(args.field ?? \"\");\n      if (!adapter.getFields().find((f) => f.name === name)) {\n        return errorResult(`Unknown field: ${name}`);\n      }\n      const value = adapter.getValue(name);\n      return textResult(JSON.stringify(value), { field: name, value });\n    },\n    false,\n  );\n\n  reg(\n    \"form_get_values\",\n    \"Read every field's current value as a JSON object.\",\n    {},\n    [],\n    () => {\n      const values = adapter.getValues();\n      return textResult(JSON.stringify(values, null, 2), values);\n    },\n    false,\n  );\n\n  // ───────────── Mutation tools ─────────────\n\n  reg(\n    \"form_set_value\",\n    \"Set one field's value. The host's controlled state updates and the human sees the field change.\",\n    {\n      field: { type: \"string\" },\n      value: { description: \"Value to set. Type depends on the field's `type`.\" },\n    },\n    [\"field\", \"value\"],\n    async (args) => {\n      const name = String(args.field ?? \"\");\n      const fieldDef = adapter.getFields().find((f) => f.name === name);\n      if (!fieldDef) return errorResult(`Unknown field: ${name}`);\n      const done = await untilClosed(\n        commit(() => adapter.setValue(name, args.value), `Host refused the write to \"${name}\".`),\n      );\n      if (done === CLOSED) return closedUnknown(`the write to \"${name}\"`);\n      if (!done.ok) return errorResult(done.error);\n      return textResult(`${name} ← ${JSON.stringify(args.value)}`, { field: name, value: args.value });\n    },\n    true,\n  );\n\n  reg(\n    \"form_set_values\",\n    \"Set multiple fields atomically. Pass a `values` object keyed by field name.\",\n    { values: { type: \"object\" } },\n    [\"values\"],\n    async (args) => {\n      const values = (args.values && typeof args.values === \"object\") ? args.values as Record<string, unknown> : {};\n      const fields = adapter.getFields();\n      const known = new Set(fields.map((f) => f.name));\n      const unknownKeys = Object.keys(values).filter((k) => !known.has(k));\n      if (unknownKeys.length) return errorResult(`Unknown fields: ${unknownKeys.join(\", \")}`);\n      const setValues = adapter.setValues;\n      if (setValues) {\n        const done = await untilClosed(commit(() => setValues(values), \"Host refused the write.\"));\n        if (done === CLOSED) return closedUnknown(\"the write\");\n        if (!done.ok) return errorResult(done.error);\n      } else {\n        // No batch setter: one host commit per field, in order, stopping at the\n        // first refusal. Earlier fields stay committed, so say exactly which.\n        const keys = Object.keys(values);\n        const committed: string[] = [];\n        for (const [i, k] of keys.entries()) {\n          const done = await untilClosed(\n            commit(() => adapter.setValue(k, values[k]), `Host refused the write to \"${k}\".`),\n          );\n          if (done === CLOSED) {\n            return {\n              ...closedUnknown(`the write to \"${k}\"`),\n              structuredContent: { committed, pending: k, notAttempted: keys.slice(i + 1) },\n            };\n          }\n          if (!done.ok) {\n            const state = { committed, failed: k, notAttempted: keys.slice(i + 1) };\n            if (committed.length) {\n              // Those writes DID commit; every committed mutation is observable,\n              // and wrapToolWithActivity skips error results, so emit it here.\n              emitActivity({\n                agentId: agent.id,\n                agentName: agent.name,\n                agentColor: agent.color,\n                target: target({}),\n                action: \"form_set_values\",\n                timestamp: Date.now(),\n                meta: state,\n              });\n            }\n            return {\n              ...errorResult(\n                `\"${k}\" was refused: ${done.error} ` +\n                  (committed.length\n                    ? `Already committed and NOT rolled back: ${committed.join(\", \")}. `\n                    : \"Nothing was committed. \") +\n                  (state.notAttempted.length ? `Not attempted: ${state.notAttempted.join(\", \")}.` : \"\"),\n              ),\n              structuredContent: state,\n            };\n          }\n          committed.push(k);\n        }\n      }\n      return textResult(`Set ${Object.keys(values).length} field(s)`, { values });\n    },\n    true,\n  );\n\n  reg(\n    \"form_focus\",\n    \"Move browser focus to a field (host-implemented). Useful before streaming text into it.\",\n    { field: { type: \"string\" } },\n    [\"field\"],\n    (args) => {\n      const name = String(args.field ?? \"\");\n      if (!adapter.focus) return errorResult(\"Host did not provide a focus implementation.\");\n      if (!adapter.getFields().find((f) => f.name === name)) {\n        return errorResult(`Unknown field: ${name}`);\n      }\n      adapter.focus(name);\n      return textResult(`Focused ${name}`, { field: name });\n    },\n    true,\n  );\n\n  reg(\n    \"form_submit\",\n    \"Submit the form. Host returns ok + values (or an error). In pendingMode this is staged for the human to confirm first.\",\n    {},\n    [],\n    async () => {\n      if (!adapter.submit) return errorResult(\"Host did not provide a submit implementation.\");\n      // Trust-but-verify: a form submit is a human-visible / often-destructive\n      // action, so gate it on a human confirm when one is wired.\n      if (pendingMode && adapter.confirm) {\n        const confirm = adapter.confirm;\n        const ok = await untilClosed(Promise.resolve().then(() => confirm({\n          action: \"submit\",\n          form: formId,\n          title: adapter.title,\n          values: adapter.getValues(),\n        })));\n        // The form went away while the human was deciding: never submit a\n        // form that is no longer on screen, whatever the late answer is.\n        if (ok === CLOSED) {\n          return errorResult(`Form \"${formId}\" was closed before the submit was confirmed. Nothing was submitted.`);\n        }\n        if (!ok) return errorResult(\"Declined by user\");\n      }\n      const submit = adapter.submit;\n      const result = await untilClosed(Promise.resolve().then(() => submit()));\n      if (result === CLOSED) return closedUnknown(\"the submit\");\n      if (!result.ok) return errorResult(hostErrorMessage(result.error, \"Submit failed\"));\n      return textResult(\"Submitted\", { values: result.values });\n    },\n    true,\n  );\n\n  return {\n    id: bridgeId,\n    title: adapter.title ?? formId,\n    dispose: () => {\n      disposed = true;\n      for (const d of disposers) d();\n      // Settle every call still waiting on the host; see untilClosed.\n      for (const close of [...onDispose]) close();\n      onDispose.clear();\n    },\n  };\n}\n"]}