@particle-academy/agent-integrations 0.47.1 → 0.49.0

package/CHANGELOG.md

@@ -11,6 +11,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.49.0] - 2026-10-27
+
+### Added
+
+- **Screens bridge acknowledges host commits.** `setActive`, `createScreen`,
+  `destroyScreen` and `updateScreenContent` on `ScreensBridgeAdapter` may now
+  return a Promise resolving to `void` or the new exported
+  `ScreensAdapterResult` (`{ ok: true } | { ok: false; error; code? }`). The
+  bridge awaits it: success, and the `AgentActivity` event, are reported only
+  after the host commits; a rejection or `{ ok: false }` becomes an error result
+  with the host's message (never a stack) and emits no activity.
+  `ScreensAdapterCommit` and `ScreenCreateSpec` are now exported from the root
+  as well as `…/bridges/screens`. **Nothing to do:** sync `void` adapters behave
+  exactly as before.
+- `screens_create` no longer calls `setActive` when `createScreen` fails. When
+  the create commits but activation fails, it returns an error stating the
+  screen was created but not activated (`structuredContent` carries
+  `created: true, activated: false`) and still emits one activity event for the
+  committed create.
+
+### Fixed
+
+- **Screens bridge reported success before an async host had committed.** The
+  adapter methods were typed `void` and called without `await`, so a host with a
+  persisted or refusable commit got "success" and an activity event first, and a
+  rejection surfaced as an unhandled promise rejection instead of a tool error.
+  The bridge pushes no undo entries; that is unchanged and now documented.
+
+### Security
+
+- Update Vitest to 4.1.12 for security fixes; dev toolchain only, nothing to do.
+
+## [0.48.0] - 2026-10-24
+
+### Added
+
+- **Scoped screen-content bridge:** import `registerScreenDocBridge`,
+  `SCREEN_TEXT_NODE_TYPE`, `DocAdapter`, `ScreenDocBridgeOptions`, `ScreenDocNode`
+  and `ScreenDocOp` from `@particle-academy/agent-integrations/bridges/screen-doc`.
+  Both ESM and CommonJS builds include their type declarations. This complements
+  `bridges/screens`, which navigates between screens rather than editing their
+  contents. **Nothing to do: the root import still works.** The other 22 bridge
+  modules already have scoped exports; no additional missing entry was found.
+- Built-package coverage for every discovered bridge: Node loads all scoped
+  entries through both ESM and CommonJS, and TypeScript checks ESM/CommonJS
+  declaration consumers. `npm test` builds fresh output first, so stale `dist`
+  files cannot hide a missing export.
+
+### Security
+
+- **Dev toolchain only — no runtime change, nothing for consumers to do.** The
+  lockfile now resolves `vite` 8.3.5 (was 8.2.2), whose bundled
+  `launch-editor` fixes GHSA-587h-7wmj-h5pm (HIGH, `fs.existsSync()` check
+  bypassable on Windows), GHSA-698v-4r3x-3vcv (`escapeCmdArgs()` omits `%`
+  escaping on Windows) and GHSA-r825-w8mm-5pxw (editor CLI flag
+  misinterpretation). `vite` is only reached through the test/dev toolchain
+  and the published package does not ship our lockfile, so the exposure was
+  this repo's own dev server.
+
 ## [0.47.1] - 2026-10-21
 
 **What to do — nothing, unless you call `DomNavigationAgent.read()` yourself**

package/README.md

@@ -87,12 +87,65 @@ Every bridge has a matching subpath if you'd rather import surgically:
 | charts              | `…/bridges/charts`                                     |
 | scene               | `…/bridges/scene`                                      |
 | screens             | `…/bridges/screens`                                    |
+| screen contents     | `…/bridges/screen-doc`                                 |
 | passkeys            | `…/bridges/passkeys`                                   |
 | sheets adapter hook | `…/sheets-adapter`                                     |
 | presence            | `…/presence`                                           |
 | undo                | `…/undo`                                               |
 | sharing             | `…/sharing`                                            |
 
+`registerScreensBridge` handles navigation between screens.
+
+### Screens bridge: acknowledge after the host commits
+
+Every mutating screens adapter method (`setActive`, `createScreen`,
+`destroyScreen`, `updateScreenContent`) may return `void` **or** a Promise. A
+sync `void` adapter behaves exactly as it always has. When the host's commit is
+asynchronous and authoritative (persisted state, a possible refusal or
+conflict), return a Promise and the bridge waits for it:
+
+- the tool reports success, and emits its `AgentActivity` event, only after the
+  promise resolves;
+- a rejection, or a resolved `{ ok: false, error }`, becomes an error result
+  carrying the host's `error` text (its message only, never a stack), and emits
+  **no** activity;
+- `screens_create` calls `createScreen` and then `setActive`. If `createScreen`
+  fails, `setActive` is never called. If `setActive` fails after a successful
+  create, the result is an **error** saying the screen was created but not
+  activated (with `structuredContent: { id, kind, created: true, activated: false }`),
+  and one activity event is still emitted because the create did commit.
+
+```ts
+import {
+  registerScreensBridge,
+  type ScreensAdapterResult,
+} from "@particle-academy/agent-integrations/bridges/screens";
+
+registerScreensBridge(host, {
+  adapter: {
+    listScreens: () => store.screens,
+    getActive: () => store.activeId,
+    // Resolve once the server has persisted it; refuse with a reason the agent can act on.
+    setActive: async (id): Promise<ScreensAdapterResult> => {
+      const res = await api.post(`/screens/${id}/activate`);
+      return res.ok ? { ok: true } : { ok: false, error: res.reason, code: "conflict" };
+    },
+    createScreen: async (spec) => {
+      await api.post("/screens", spec); // a throw becomes an error result
+    },
+  },
+});
+```
+
+The screens bridge pushes **no undo entries**: `agent_undo` cannot revert a
+screens tool. Keep your own history if you need to.
+
+`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
+root import still works; nothing to do for existing consumers. Use a distinct
+`surface` tool prefix for each concurrently bridged document.
+
 ## When you don't need an MCP server
 
 If your agent runs in the same JS process as the surfaces it drives (an embedded chat widget, an in-page worker, an SSR-time tool loop), you don't need any of MCP's JSON-RPC framing. Use **`ToolRegistry`** — a plain in-memory tool host that the bridges register against. Agents drive the surface with `host.callTool("sheet_set_cell", { … })` directly.

package/dist/bridges/screen-doc.d.cts

@@ -0,0 +1,47 @@
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import { DocAdapter } from './doc.cjs';
+import { DocNode, StagePolicy, TreeOp } from '@particle-academy/fancy-doc-commons';
+import '../types-gzIpsUDE.cjs';
+
+/**
+ * Reserved node type for a literal string child. Must match fancy-screens'
+ * `TEXT_NODE_TYPE`; duplicated rather than imported to keep this bridge free of
+ * a fancy-screens dependency.
+ */
+declare const SCREEN_TEXT_NODE_TYPE = "#text";
+/** A screen document node — a `DocNode` plus the minted-id flag. */
+interface ScreenDocNode extends DocNode {
+    /**
+     * True when fancy-screens minted this id because the author supplied none.
+     * A synthetic id is derived from position, so it is not a durable handle.
+     */
+    synthetic?: boolean;
+}
+type ScreenDocOp = TreeOp<ScreenDocNode>;
+interface ScreenDocBridgeOptions {
+    adapter: DocAdapter<ScreenDocNode>;
+    /**
+     * Tool-name prefix. Default `"screen"` → `screen_add`, `screen_set_text`, …
+     *
+     * Tool names are global, so a host wiring more than one doc-driven screen at
+     * once must give each a distinct prefix (`"screen_checkout"`).
+     */
+    surface?: string;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /** Auto-apply vs. confirm per op (trust-but-verify). Default: auto. */
+    stagePolicy?: StagePolicy<ScreenDocOp>;
+    onPending?: (staged: {
+        id: string;
+        op: ScreenDocOp;
+        label: string;
+    }) => void;
+}
+/** Register the screen-content bridge (prefix `screen_`) over a screen's `DocTree`. */
+declare function registerScreenDocBridge(host: ToolHost, options: ScreenDocBridgeOptions): Bridge;
+
+export { DocAdapter, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, registerScreenDocBridge };

package/dist/bridges/screen-doc.d.ts

@@ -0,0 +1,47 @@
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import { DocAdapter } from './doc.js';
+import { DocNode, StagePolicy, TreeOp } from '@particle-academy/fancy-doc-commons';
+import '../types-gzIpsUDE.js';
+
+/**
+ * Reserved node type for a literal string child. Must match fancy-screens'
+ * `TEXT_NODE_TYPE`; duplicated rather than imported to keep this bridge free of
+ * a fancy-screens dependency.
+ */
+declare const SCREEN_TEXT_NODE_TYPE = "#text";
+/** A screen document node — a `DocNode` plus the minted-id flag. */
+interface ScreenDocNode extends DocNode {
+    /**
+     * True when fancy-screens minted this id because the author supplied none.
+     * A synthetic id is derived from position, so it is not a durable handle.
+     */
+    synthetic?: boolean;
+}
+type ScreenDocOp = TreeOp<ScreenDocNode>;
+interface ScreenDocBridgeOptions {
+    adapter: DocAdapter<ScreenDocNode>;
+    /**
+     * Tool-name prefix. Default `"screen"` → `screen_add`, `screen_set_text`, …
+     *
+     * Tool names are global, so a host wiring more than one doc-driven screen at
+     * once must give each a distinct prefix (`"screen_checkout"`).
+     */
+    surface?: string;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /** Auto-apply vs. confirm per op (trust-but-verify). Default: auto. */
+    stagePolicy?: StagePolicy<ScreenDocOp>;
+    onPending?: (staged: {
+        id: string;
+        op: ScreenDocOp;
+        label: string;
+    }) => void;
+}
+/** Register the screen-content bridge (prefix `screen_`) over a screen's `DocTree`. */
+declare function registerScreenDocBridge(host: ToolHost, options: ScreenDocBridgeOptions): Bridge;
+
+export { DocAdapter, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, registerScreenDocBridge };

package/dist/bridges/screens.d.cts

@@ -28,6 +28,28 @@ type ScreenCreateSpec = {
     /** Template-specific config. Form: { fields }. Sheet: { headers }. etc. */
     config?: Record<string, unknown>;
 };
+/**
+ * What a mutating adapter method may resolve to, to acknowledge (or refuse)
+ * a commit. `{ ok: false }` is a refusal the agent can act on: `error` is
+ * shown to the agent verbatim, so keep it a human-readable sentence, never a
+ * stack trace or an internal path. `code` is a machine-readable hint
+ * (e.g. `"conflict"`) for the host's own use; it is not shown to the agent.
+ */
+type ScreensAdapterResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * Return type of every mutating adapter method. 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. A rejection or an `{ ok: false }` result becomes an error result
+ * and emits no activity.
+ */
+type ScreensAdapterCommit = void | Promise<void | ScreensAdapterResult>;
 /**
  * Adapter exposes the host's screen-navigation surface to the bridge.
  * Hosts wire this up against react-router, a custom tab state, or the
@@ -35,6 +57,15 @@ type ScreenCreateSpec = {
  *
  * The optional create / destroy / update hooks let agents author screens
  * dynamically against a host-defined template catalog.
+ *
+ * Every mutating method may be sync (`void`) or async (`Promise`); see
+ * {@link ScreensAdapterCommit}. Return a Promise when the host's commit is
+ * authoritative — persisted, or able to refuse or conflict — so the agent is
+ * told the truth instead of "success" before anything was committed.
+ *
+ * This bridge pushes NO undo entries: `agent_undo` cannot revert a screens
+ * tool. A host that needs undo for navigation or screen authoring must keep
+ * its own history.
  */
 type ScreensBridgeAdapter = {
     /** List every available screen. */
@@ -42,13 +73,13 @@ type ScreensBridgeAdapter = {
     /** Read which screen is currently active. */
     getActive: () => string | null;
     /** Navigate to a screen by id. Host updates router / tab state. */
-    setActive: (screenId: string) => void;
+    setActive: (screenId: string) => ScreensAdapterCommit;
     /** Optional: instantiate a new screen from a template + config. */
-    createScreen?: (spec: ScreenCreateSpec) => void;
+    createScreen?: (spec: ScreenCreateSpec) => ScreensAdapterCommit;
     /** Optional: remove a previously-created screen. */
-    destroyScreen?: (screenId: string) => void;
+    destroyScreen?: (screenId: string) => ScreensAdapterCommit;
     /** Optional: shallow-merge new config into an existing screen. */
-    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => void;
+    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => ScreensAdapterCommit;
     /** Optional: enumerate the kinds the host knows how to instantiate. */
     listKinds?: () => Array<{
         kind: string;
@@ -75,4 +106,4 @@ type ScreensBridgeOptions = {
  */
 declare function registerScreensBridge(host: ToolHost, options: ScreensBridgeOptions): Bridge;
 
-export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };
+export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensAdapterCommit, type ScreensAdapterResult, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };

package/dist/bridges/screens.d.ts

@@ -28,6 +28,28 @@ type ScreenCreateSpec = {
     /** Template-specific config. Form: { fields }. Sheet: { headers }. etc. */
     config?: Record<string, unknown>;
 };
+/**
+ * What a mutating adapter method may resolve to, to acknowledge (or refuse)
+ * a commit. `{ ok: false }` is a refusal the agent can act on: `error` is
+ * shown to the agent verbatim, so keep it a human-readable sentence, never a
+ * stack trace or an internal path. `code` is a machine-readable hint
+ * (e.g. `"conflict"`) for the host's own use; it is not shown to the agent.
+ */
+type ScreensAdapterResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * Return type of every mutating adapter method. 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. A rejection or an `{ ok: false }` result becomes an error result
+ * and emits no activity.
+ */
+type ScreensAdapterCommit = void | Promise<void | ScreensAdapterResult>;
 /**
  * Adapter exposes the host's screen-navigation surface to the bridge.
  * Hosts wire this up against react-router, a custom tab state, or the
@@ -35,6 +57,15 @@ type ScreenCreateSpec = {
  *
  * The optional create / destroy / update hooks let agents author screens
  * dynamically against a host-defined template catalog.
+ *
+ * Every mutating method may be sync (`void`) or async (`Promise`); see
+ * {@link ScreensAdapterCommit}. Return a Promise when the host's commit is
+ * authoritative — persisted, or able to refuse or conflict — so the agent is
+ * told the truth instead of "success" before anything was committed.
+ *
+ * This bridge pushes NO undo entries: `agent_undo` cannot revert a screens
+ * tool. A host that needs undo for navigation or screen authoring must keep
+ * its own history.
  */
 type ScreensBridgeAdapter = {
     /** List every available screen. */
@@ -42,13 +73,13 @@ type ScreensBridgeAdapter = {
     /** Read which screen is currently active. */
     getActive: () => string | null;
     /** Navigate to a screen by id. Host updates router / tab state. */
-    setActive: (screenId: string) => void;
+    setActive: (screenId: string) => ScreensAdapterCommit;
     /** Optional: instantiate a new screen from a template + config. */
-    createScreen?: (spec: ScreenCreateSpec) => void;
+    createScreen?: (spec: ScreenCreateSpec) => ScreensAdapterCommit;
     /** Optional: remove a previously-created screen. */
-    destroyScreen?: (screenId: string) => void;
+    destroyScreen?: (screenId: string) => ScreensAdapterCommit;
     /** Optional: shallow-merge new config into an existing screen. */
-    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => void;
+    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => ScreensAdapterCommit;
     /** Optional: enumerate the kinds the host knows how to instantiate. */
     listKinds?: () => Array<{
         kind: string;
@@ -75,4 +106,4 @@ type ScreensBridgeOptions = {
  */
 declare function registerScreensBridge(host: ToolHost, options: ScreensBridgeOptions): Bridge;
 
-export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };
+export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensAdapterCommit, type ScreensAdapterResult, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };