@particle-academy/agent-integrations 0.35.0 → 0.36.0

package/dist/index.d.cts

@@ -24,8 +24,10 @@ export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalR
 export { CatalogBridgeAdapter, CatalogBridgeOptions, CatalogCheckoutArgs, CatalogPrice, CatalogProduct, registerCatalogBridge } from './bridges/catalog.cjs';
 export { FeatureDefinition, FeatureGrant, FeaturesBridgeAdapter, FeaturesBridgeOptions, registerFeaturesBridge } from './bridges/features.cjs';
 export { PASSKEY_BRIDGE_TOOLS, PasskeyBridgeAdapter, PasskeyBridgeOptions, PasskeyProposal, PasskeySummaryLike, PasskeySupport, PasskeySurfaceState, registerPasskeyBridge } from './bridges/passkeys.cjs';
-export { DocAdapter, DocBridgeOptions, DocOpTool, registerDocBridge } from './bridges/doc.cjs';
+import { DocAdapter } from './bridges/doc.cjs';
+export { DocBridgeOptions, DocOpTool, registerDocBridge } from './bridges/doc.cjs';
 export { CmsBridgeOptions, CmsOp, cmsReducer, registerCmsBridge } from './bridges/cms.cjs';
+import { DocNode, StagePolicy, TreeOp } from '@particle-academy/fancy-doc-commons';
 import { RelayState } from './sharing/index.cjs';
 export { SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.cjs';
 import { S as SessionDescriptor } from './token-BZ8doMam.cjs';
@@ -40,7 +42,6 @@ export { CLAUDE_CONNECTORS_URL, CONNECTOR_GLYPHS, CONNECTOR_TARGETS, ClaudeMark,
 export { D as DEFAULT_MCPB_ENTRY_POINT, b as MCPB_MANIFEST_VERSION, c as MCPB_MIN_NODE, M as McpbManifestInput, a as McpbTool, d as buildMcpbManifest, e as buildMcpbProxyStub } from './mcpb-BXOrsRnv.cjs';
 import '@particle-academy/fancy-sheets';
 import '@particle-academy/fancy-slides';
-import '@particle-academy/fancy-doc-commons';
 
 /**
  * One interactive element the agent can act on, addressed by a STABLE handle
@@ -159,6 +160,46 @@ type NavigationBridgeOptions = {
  */
 declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
 
+/**
+ * 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;
+
 /** A thing the human did, surfaced so the connected agent stays aware. */
 type CoBrowseUserEvent = {
     kind: "navigation";
@@ -525,4 +566,4 @@ type SimulateUsersButtonProps = {
  */
 declare function SimulateUsersButton({ endpoint, count, label, csrfToken, onTriggered, onError, className, style, }: SimulateUsersButtonProps): react.JSX.Element;
 
-export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, useCoBrowseSession };
+export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };

package/dist/index.d.ts

@@ -24,8 +24,10 @@ export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalR
 export { CatalogBridgeAdapter, CatalogBridgeOptions, CatalogCheckoutArgs, CatalogPrice, CatalogProduct, registerCatalogBridge } from './bridges/catalog.js';
 export { FeatureDefinition, FeatureGrant, FeaturesBridgeAdapter, FeaturesBridgeOptions, registerFeaturesBridge } from './bridges/features.js';
 export { PASSKEY_BRIDGE_TOOLS, PasskeyBridgeAdapter, PasskeyBridgeOptions, PasskeyProposal, PasskeySummaryLike, PasskeySupport, PasskeySurfaceState, registerPasskeyBridge } from './bridges/passkeys.js';
-export { DocAdapter, DocBridgeOptions, DocOpTool, registerDocBridge } from './bridges/doc.js';
+import { DocAdapter } from './bridges/doc.js';
+export { DocBridgeOptions, DocOpTool, registerDocBridge } from './bridges/doc.js';
 export { CmsBridgeOptions, CmsOp, cmsReducer, registerCmsBridge } from './bridges/cms.js';
+import { DocNode, StagePolicy, TreeOp } from '@particle-academy/fancy-doc-commons';
 import { RelayState } from './sharing/index.js';
 export { SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.js';
 import { S as SessionDescriptor } from './token-BZ8doMam.js';
@@ -40,7 +42,6 @@ export { CLAUDE_CONNECTORS_URL, CONNECTOR_GLYPHS, CONNECTOR_TARGETS, ClaudeMark,
 export { D as DEFAULT_MCPB_ENTRY_POINT, b as MCPB_MANIFEST_VERSION, c as MCPB_MIN_NODE, M as McpbManifestInput, a as McpbTool, d as buildMcpbManifest, e as buildMcpbProxyStub } from './mcpb-BXOrsRnv.js';
 import '@particle-academy/fancy-sheets';
 import '@particle-academy/fancy-slides';
-import '@particle-academy/fancy-doc-commons';
 
 /**
  * One interactive element the agent can act on, addressed by a STABLE handle
@@ -159,6 +160,46 @@ type NavigationBridgeOptions = {
  */
 declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
 
+/**
+ * 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;
+
 /** A thing the human did, surfaced so the connected agent stays aware. */
 type CoBrowseUserEvent = {
     kind: "navigation";
@@ -525,4 +566,4 @@ type SimulateUsersButtonProps = {
  */
 declare function SimulateUsersButton({ endpoint, count, label, csrfToken, onTriggered, onError, className, style, }: SimulateUsersButtonProps): react.JSX.Element;
 
-export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, useCoBrowseSession };
+export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };

package/dist/index.js

@@ -12,8 +12,9 @@ export { useUndoStack } from './chunk-BT7HM5I6.js';
 export { registerCatalogBridge } from './chunk-OAFJ53X3.js';
 export { registerFeaturesBridge } from './chunk-ZNGTC4CO.js';
 export { PASSKEY_BRIDGE_TOOLS, registerPasskeyBridge } from './chunk-7THGQUX3.js';
-export { cmsReducer, registerCmsBridge } from './chunk-DKSR4R4O.js';
-export { registerDocBridge } from './chunk-LQZKRBWR.js';
+export { cmsReducer, registerCmsBridge } from './chunk-JJUABMAP.js';
+import { registerDocBridge } from './chunk-XY2TDE6E.js';
+export { registerDocBridge } from './chunk-XY2TDE6E.js';
 export { registerTuiBridge } from './chunk-MFMBR6LN.js';
 import { useAgentActivity } from './chunk-UCKJAUBY.js';
 export { useAgentActivity, useAgentActivityForScreen } from './chunk-UCKJAUBY.js';
@@ -39,8 +40,9 @@ import { wrapToolWithActivity } from './chunk-2VENWGLZ.js';
 export { wrapToolWithActivity } from './chunk-2VENWGLZ.js';
 import { emitActivity, onActivity } from './chunk-C3TYI5TJ.js';
 export { emitActivity, onActivity, readActivityHistory, resetActivityRegistry } from './chunk-C3TYI5TJ.js';
-import { MicroMcpServer, textResult, errorResult } from './chunk-DF3PLL2E.js';
+import { textResult, MicroMcpServer, errorResult } from './chunk-DF3PLL2E.js';
 export { MCP_PROTOCOL_VERSION, MicroMcpServer, ToolRegistry, errorResult, rpcError, textResult } from './chunk-DF3PLL2E.js';
+import { childrenOf, appendOrder } from '@particle-academy/fancy-doc-commons';
 import { useRef, useState, useEffect, useCallback, useMemo } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { createPortal } from 'react-dom';
@@ -308,6 +310,90 @@ function registerNavigationBridge(host, options) {
     }
   };
 }
+var SCREEN_TEXT_NODE_TYPE = "#text";
+function registerScreenDocBridge(host, options) {
+  const { adapter } = options;
+  const surface = options.surface ?? "screen";
+  const setText = {
+    verb: "set_text",
+    description: "Replace the literal text of an element node \u2014 the natural way to change a label, heading or paragraph. Pass the ELEMENT's id, not the text node's.",
+    properties: {
+      id: { type: "string", description: "Id of the element whose text to set." },
+      text: { type: "string" }
+    },
+    required: ["id", "text"],
+    build: (args, tree) => {
+      const id = String(args.id);
+      const node = tree.nodes[id];
+      if (!node) return { error: `No node ${id}` };
+      if (node.type === SCREEN_TEXT_NODE_TYPE) {
+        return { t: "set_props", id, patch: { value: String(args.text) } };
+      }
+      const texts = childrenOf(tree, id).filter((c) => c.type === SCREEN_TEXT_NODE_TYPE);
+      if (texts.length === 1) {
+        return { t: "set_props", id: texts[0].id, patch: { value: String(args.text) } };
+      }
+      if (texts.length === 0) {
+        return {
+          t: "insert",
+          node: {
+            id: `${id}-text`,
+            type: SCREEN_TEXT_NODE_TYPE,
+            parent: id,
+            order: appendOrder(tree, id),
+            props: { value: String(args.text) }
+          }
+        };
+      }
+      return {
+        error: `Node ${id} has ${texts.length} text children (${texts.map((t) => t.id).join(", ")}) \u2014 set_text on the one you mean`
+      };
+    },
+    targetId: (args) => String(args.id)
+  };
+  const bridge = registerDocBridge(host, {
+    adapter,
+    surface,
+    agent: options.agent,
+    stagePolicy: options.stagePolicy,
+    onPending: options.onPending,
+    // Anything the AGENT adds is authored by definition — it chose or was given
+    // the id — so it must not inherit the synthetic flag from its neighbours.
+    makeNode: ({ id, type, parent, order }, props) => ({ id, type, parent, order, props }),
+    describeNode: (n) => ({
+      id: n.id,
+      type: n.type,
+      parent: n.parent,
+      ...n.synthetic ? { synthetic: true } : {},
+      ...n.type === SCREEN_TEXT_NODE_TYPE ? { text: String(n.props?.value ?? "") } : { props: Object.keys(n.props ?? {}) }
+    }),
+    opTools: [setText]
+  });
+  const disposeAddressable = host.registerTool(
+    {
+      name: `${surface}_addressable`,
+      description: "List the node ids that are safe to remember and use later. Ids NOT listed here were minted from a node's position: they resolve today and silently point at a different node once a sibling is inserted above them. Address those in the same turn you read them, and never store one.",
+      inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false }
+    },
+    (async () => {
+      const nodes = Object.values(adapter.get().nodes);
+      const authored = nodes.filter((n) => !n.synthetic).map((n) => ({ id: n.id, type: n.type }));
+      const syntheticCount = nodes.length - authored.length;
+      return textResult(
+        authored.length ? `${authored.length} addressable, ${syntheticCount} positional` : `no addressable ids \u2014 all ${syntheticCount} nodes are positional`,
+        { addressable: authored, syntheticCount }
+      );
+    })
+  );
+  return {
+    id: surface,
+    title: "Screen content",
+    dispose: () => {
+      disposeAddressable();
+      bridge.dispose();
+    }
+  };
+}
 var DEFAULT_AGENT2 = { id: "agent", name: "Agent", color: "#a855f7" };
 var USER = { id: "human", name: "You" };
 function useCoBrowseSession(options) {
@@ -702,6 +788,6 @@ function SimulateUsersButton({
   );
 }
 
-export { BridgedForm, CoBrowseCursorLayer, CoBrowsePresence, ScreensActivityBridge, SimulateUsersButton, registerNavigationBridge, useCoBrowseSession };
+export { BridgedForm, CoBrowseCursorLayer, CoBrowsePresence, SCREEN_TEXT_NODE_TYPE, ScreensActivityBridge, SimulateUsersButton, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map