@particle-academy/agent-integrations 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,9 +1,11 @@
1
1
  import { M as MicroMcpServer } from './server-BsSwfemr.cjs';
2
2
  export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-BsSwfemr.cjs';
3
- export { T as ToolHost, a as ToolRegistry } from './tool-host-BQuUygLF.cjs';
3
+ import { T as ToolHost } from './tool-host-BQuUygLF.cjs';
4
+ export { a as ToolRegistry } from './tool-host-BQuUygLF.cjs';
4
5
  export { InProcessTransport, RelayChannel, RelayTransport, attachInProcess, attachRelay } from './mcp/index.cjs';
5
6
  export { C as CallToolResult, d as ContentBlock, I as InitializeResult, c as JsonObject, J as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, a as ServerCapabilities, S as ServerInfo, T as ToolDefinition, b as ToolHandler } from './types-aOQLTW0E.cjs';
6
- export { B as Bridge, a as BridgeFactory } from './types-CCSBGW9T.cjs';
7
+ import { B as Bridge } from './types-CCSBGW9T.cjs';
8
+ export { a as BridgeFactory } from './types-CCSBGW9T.cjs';
7
9
  import { FormFieldDescriptor } from './bridges/forms.cjs';
8
10
  export { FormBridgeAdapter, FormBridgeOptions, registerFormBridge } from './bridges/forms.cjs';
9
11
  export { SheetsBridgeAdapter, SheetsBridgeOptions, registerSheetsBridge } from './bridges/sheets.cjs';
@@ -14,18 +16,185 @@ export { SceneBridgeAdapter, SceneBridgeOptions, SceneCamera, SceneObject, Scene
14
16
  export { ScreenSnapshot, ScreensBridgeAdapter, ScreensBridgeOptions, registerScreensBridge } from './bridges/screens.cjs';
15
17
  export { SlidesBridgeAdapter, SlidesBridgeOptions, registerSlidesBridge } from './bridges/slides.cjs';
16
18
  export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalRef, TerminalShell, registerTerminalBridge } from './bridges/terminal.cjs';
17
- import * as react from 'react';
18
- import { ReactNode, CSSProperties } from 'react';
19
+ import { RelayState } from './sharing/index.cjs';
20
+ export { SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.cjs';
19
21
  import { S as SessionDescriptor } from './token-CrJF76oH.cjs';
20
22
  export { b as buildShareConfig, a as buildShareUrl, c as createSessionDescriptor, d as describeSession, r as readSessionFromUrl } from './token-CrJF76oH.cjs';
23
+ import * as react from 'react';
24
+ import { ReactNode, CSSProperties } from 'react';
21
25
  export { ActivityFilter, AutoActivityEvent as AgentActivityEvent, AutoActivityListener as AgentActivityListener, AutoTarget as AgentTarget, AutoTargetKind as AgentTargetKind, UndoEntry, clearStack as clearUndoStack, emitActivity, onActivity, pushUndoEntry, readActivityHistory, readHistory as readUndoHistory, redoOne, resetActivityRegistry, resetAllUndoStacks, undoOne } from '@particle-academy/fancy-auto-common';
22
26
  export { ActivityAgent, ActivityResolverContext, ActivityTargetResolver, ToolHandler as ActivityWrappedHandler, useAgentActivity, useAgentActivityForScreen, wrapToolWithActivity } from './presence/index.cjs';
23
27
  export { UndoToolsOptions, ensureUndoToolsRegistered, registerUndoTools, useUndoStack } from './undo/index.cjs';
24
- export { RelayState, SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.cjs';
25
28
  export { CLAUDE_CONNECTORS_URL, CONNECTOR_GLYPHS, CONNECTOR_TARGETS, ClaudeMark, ConnectorButtons, ConnectorButtonsProps, ConnectorClient, ConnectorMechanism, ConnectorServer, ConnectorTargetMeta, CursorMark, DesktopMark, ManualMcpConfig, VscodeMark, WrenchMark, buildCursorDeeplink, buildManualConfig, buildManualConfigSnippet, buildVscodeDeeplink, connectorHref, encodeBase64Json, slugifyServerName } from './connectors/index.cjs';
26
29
  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';
27
30
  import '@particle-academy/fancy-slides';
28
31
 
32
+ /**
33
+ * One interactive element the agent can act on, addressed by a STABLE handle
34
+ * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
35
+ * scraping. The host builds these in `describe()` (data-co-handle → name/id →
36
+ * ARIA role + accessible name).
37
+ */
38
+ type PageAction = {
39
+ /** Stable, opaque handle the agent passes back to act on this element. */
40
+ handle: string;
41
+ /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
42
+ role: string;
43
+ /** Accessible name / label. */
44
+ label: string;
45
+ /** Current value for inputs (omitted/masked for sensitive fields). */
46
+ value?: unknown;
47
+ /** True when activating this is destructive / submits (agent should stage). */
48
+ destructive?: boolean;
49
+ };
50
+ /** The page as the agent sees it: where it is + what it can do. */
51
+ type PageSnapshot = {
52
+ url: string;
53
+ title: string;
54
+ actions: PageAction[];
55
+ };
56
+ /** A write the host may want the human to confirm (trust-but-verify). */
57
+ type NavigationConfirmRequest = {
58
+ action: "submit" | "click";
59
+ handle: string;
60
+ label: string;
61
+ };
62
+ /**
63
+ * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
64
+ * a DOM walker (see resources/js/agent/CoBrowseProvider.tsx). Every method
65
+ * works on stable handles, never raw selectors.
66
+ */
67
+ type NavigationBridgeAdapter = {
68
+ /** Optional fancy-screens screen id for presence targeting. */
69
+ screenId?: string;
70
+ /** Current location. */
71
+ getLocation: () => {
72
+ url: string;
73
+ title: string;
74
+ };
75
+ /** Snapshot of the page's actionable elements (stable handles + labels). */
76
+ describe: () => PageSnapshot;
77
+ /** Visible text / heading outline for grounding (optional). */
78
+ read?: () => string;
79
+ /** Navigate to a URL (host wires to router.visit). */
80
+ visit: (url: string) => void | Promise<void>;
81
+ back?: () => void | Promise<void>;
82
+ forward?: () => void | Promise<void>;
83
+ /** Scroll to coords or to a handle's element. */
84
+ scrollTo: (opts: {
85
+ x?: number;
86
+ y?: number;
87
+ handle?: string;
88
+ }) => void;
89
+ scrollBy: (dy: number) => void;
90
+ /** Set a field's value by handle (host dispatches input/change for React). */
91
+ setField: (handle: string, value: unknown) => {
92
+ ok: boolean;
93
+ error?: string;
94
+ };
95
+ /** Activate an element by handle. */
96
+ click: (handle: string) => {
97
+ ok: boolean;
98
+ error?: string;
99
+ };
100
+ /** Submit a form by handle. */
101
+ submit: (handle: string) => Promise<{
102
+ ok: boolean;
103
+ error?: string;
104
+ }> | {
105
+ ok: boolean;
106
+ error?: string;
107
+ };
108
+ /**
109
+ * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
110
+ * destructive `page_click` route through this; the host shows a prompt and
111
+ * resolves true (proceed) / false (declined).
112
+ */
113
+ confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
114
+ };
115
+ type NavigationBridgeOptions = {
116
+ adapter: NavigationBridgeAdapter;
117
+ /** Identity tagged into activity events (so the human sees who's driving). */
118
+ agent?: {
119
+ id: string;
120
+ name?: string;
121
+ color?: string;
122
+ };
123
+ /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
124
+ pendingMode?: boolean;
125
+ };
126
+ /**
127
+ * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
128
+ * navigate, scroll, and (with staged confirm) fill + click any page, addressed
129
+ * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
130
+ * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
131
+ */
132
+ declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
133
+
134
+ /** A thing the human did, surfaced so the connected agent stays aware. */
135
+ type CoBrowseUserEvent = {
136
+ kind: "navigation";
137
+ url: string;
138
+ title?: string;
139
+ } | {
140
+ kind: "scroll";
141
+ y: number;
142
+ } | {
143
+ kind: "form";
144
+ handle: string;
145
+ value?: unknown;
146
+ masked?: boolean;
147
+ };
148
+ type UseCoBrowseSessionOptions = {
149
+ /**
150
+ * The navigation adapter (Inertia + DOM in the sandbox). MUST be stable —
151
+ * its methods should read live state via refs, since the bridge captures it
152
+ * once on mount. Memoize it.
153
+ */
154
+ adapter: NavigationBridgeAdapter;
155
+ /** Identity for the agent's presence (cursor/log color + name). */
156
+ agent?: {
157
+ id: string;
158
+ name?: string;
159
+ color?: string;
160
+ };
161
+ /** Relay base path. Default "/whiteboard-share" (the generic frame broker). */
162
+ relayBaseUrl?: string;
163
+ /** MCP server info advertised to the agent. */
164
+ info?: {
165
+ name: string;
166
+ version: string;
167
+ instructions?: string;
168
+ };
169
+ /** Register extra bridges (forms/screens/…) on the same server. */
170
+ extraBridges?: (server: MicroMcpServer) => void;
171
+ /** CSRF token for the relay register/unregister POSTs. */
172
+ csrfToken?: () => string | null | undefined;
173
+ /** Stage submit + destructive clicks for human confirm. Default true. */
174
+ pendingMode?: boolean;
175
+ };
176
+ type CoBrowseSession = {
177
+ server: MicroMcpServer | null;
178
+ session: SessionDescriptor | null;
179
+ relayState: RelayState;
180
+ startShare: () => Promise<void>;
181
+ stopShare: () => void;
182
+ /**
183
+ * Report a human action so the connected agent is notified. Emits a
184
+ * `source:"user"` activity event, which the SSE relay forwards to the agent
185
+ * as a `notifications/agent_activity` frame.
186
+ */
187
+ observeUser: (event: CoBrowseUserEvent) => void;
188
+ };
189
+ /**
190
+ * Site-wide co-browsing session: one persistent in-page `MicroMcpServer` running
191
+ * the navigation bridge, joinable by an external agent over the relay. Mount it
192
+ * once at the app root; render `<CoBrowsePresence>` to show the agent + a Stop
193
+ * control. The host wires `observeUser(...)` to navigation/scroll/form listeners
194
+ * so the agent sees what the human does.
195
+ */
196
+ declare function useCoBrowseSession(options: UseCoBrowseSessionOptions): CoBrowseSession;
197
+
29
198
  type AgentActivity = {
30
199
  id: string;
31
200
  /** Wall-clock timestamp; component formats it. */
@@ -203,4 +372,26 @@ type ShareControlsProps = {
203
372
  */
204
373
  declare function ShareControls({ session, onStart, onStop, status, shareBaseUrl, className, style, }: ShareControlsProps): react.JSX.Element;
205
374
 
206
- export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, BridgedForm, type BridgedFormProps, FormFieldDescriptor, MicroMcpServer, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps };
375
+ type CoBrowsePresenceProps = {
376
+ /** The session from `useCoBrowseSession`. */
377
+ session: CoBrowseSession;
378
+ /** Public MCP/connect URL shown to the user (for ConnectorButtons), optional. */
379
+ connectUrl?: string;
380
+ /** Base URL used to build the shareable session link. */
381
+ shareBaseUrl?: string;
382
+ className?: string;
383
+ };
384
+ /**
385
+ * The human's view of a site-wide co-browsing session: a "Let an agent drive"
386
+ * starter, the share/connect surface once started, a live "agent is driving"
387
+ * status with the latest action, and a Stop / take-back-control button.
388
+ *
389
+ * Staged-action confirms are rendered by the HOST (via the navigation adapter's
390
+ * `confirm`), so this component stays presentation-only.
391
+ */
392
+ declare function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }: CoBrowsePresenceProps): react.JSX.Element;
393
+ declare namespace CoBrowsePresence {
394
+ var displayName: string;
395
+ }
396
+
397
+ export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, 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, ToolHost, type UseCoBrowseSessionOptions, registerNavigationBridge, useCoBrowseSession };
package/dist/index.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import { M as MicroMcpServer } from './server-Du3-IGqM.js';
2
2
  export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-Du3-IGqM.js';
3
- export { T as ToolHost, a as ToolRegistry } from './tool-host-C8JMMGYq.js';
3
+ import { T as ToolHost } from './tool-host-C8JMMGYq.js';
4
+ export { a as ToolRegistry } from './tool-host-C8JMMGYq.js';
4
5
  export { InProcessTransport, RelayChannel, RelayTransport, attachInProcess, attachRelay } from './mcp/index.js';
5
6
  export { C as CallToolResult, d as ContentBlock, I as InitializeResult, c as JsonObject, J as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, a as ServerCapabilities, S as ServerInfo, T as ToolDefinition, b as ToolHandler } from './types-aOQLTW0E.js';
6
- export { B as Bridge, a as BridgeFactory } from './types-DIVNcIQO.js';
7
+ import { B as Bridge } from './types-DIVNcIQO.js';
8
+ export { a as BridgeFactory } from './types-DIVNcIQO.js';
7
9
  import { FormFieldDescriptor } from './bridges/forms.js';
8
10
  export { FormBridgeAdapter, FormBridgeOptions, registerFormBridge } from './bridges/forms.js';
9
11
  export { SheetsBridgeAdapter, SheetsBridgeOptions, registerSheetsBridge } from './bridges/sheets.js';
@@ -14,18 +16,185 @@ export { SceneBridgeAdapter, SceneBridgeOptions, SceneCamera, SceneObject, Scene
14
16
  export { ScreenSnapshot, ScreensBridgeAdapter, ScreensBridgeOptions, registerScreensBridge } from './bridges/screens.js';
15
17
  export { SlidesBridgeAdapter, SlidesBridgeOptions, registerSlidesBridge } from './bridges/slides.js';
16
18
  export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalRef, TerminalShell, registerTerminalBridge } from './bridges/terminal.js';
17
- import * as react from 'react';
18
- import { ReactNode, CSSProperties } from 'react';
19
+ import { RelayState } from './sharing/index.js';
20
+ export { SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.js';
19
21
  import { S as SessionDescriptor } from './token-CrJF76oH.js';
20
22
  export { b as buildShareConfig, a as buildShareUrl, c as createSessionDescriptor, d as describeSession, r as readSessionFromUrl } from './token-CrJF76oH.js';
23
+ import * as react from 'react';
24
+ import { ReactNode, CSSProperties } from 'react';
21
25
  export { ActivityFilter, AutoActivityEvent as AgentActivityEvent, AutoActivityListener as AgentActivityListener, AutoTarget as AgentTarget, AutoTargetKind as AgentTargetKind, UndoEntry, clearStack as clearUndoStack, emitActivity, onActivity, pushUndoEntry, readActivityHistory, readHistory as readUndoHistory, redoOne, resetActivityRegistry, resetAllUndoStacks, undoOne } from '@particle-academy/fancy-auto-common';
22
26
  export { ActivityAgent, ActivityResolverContext, ActivityTargetResolver, ToolHandler as ActivityWrappedHandler, useAgentActivity, useAgentActivityForScreen, wrapToolWithActivity } from './presence/index.js';
23
27
  export { UndoToolsOptions, ensureUndoToolsRegistered, registerUndoTools, useUndoStack } from './undo/index.js';
24
- export { RelayState, SseRelayOptions, SseRelayTransport, attachSseRelay } from './sharing/index.js';
25
28
  export { CLAUDE_CONNECTORS_URL, CONNECTOR_GLYPHS, CONNECTOR_TARGETS, ClaudeMark, ConnectorButtons, ConnectorButtonsProps, ConnectorClient, ConnectorMechanism, ConnectorServer, ConnectorTargetMeta, CursorMark, DesktopMark, ManualMcpConfig, VscodeMark, WrenchMark, buildCursorDeeplink, buildManualConfig, buildManualConfigSnippet, buildVscodeDeeplink, connectorHref, encodeBase64Json, slugifyServerName } from './connectors/index.js';
26
29
  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';
27
30
  import '@particle-academy/fancy-slides';
28
31
 
32
+ /**
33
+ * One interactive element the agent can act on, addressed by a STABLE handle
34
+ * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
35
+ * scraping. The host builds these in `describe()` (data-co-handle → name/id →
36
+ * ARIA role + accessible name).
37
+ */
38
+ type PageAction = {
39
+ /** Stable, opaque handle the agent passes back to act on this element. */
40
+ handle: string;
41
+ /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
42
+ role: string;
43
+ /** Accessible name / label. */
44
+ label: string;
45
+ /** Current value for inputs (omitted/masked for sensitive fields). */
46
+ value?: unknown;
47
+ /** True when activating this is destructive / submits (agent should stage). */
48
+ destructive?: boolean;
49
+ };
50
+ /** The page as the agent sees it: where it is + what it can do. */
51
+ type PageSnapshot = {
52
+ url: string;
53
+ title: string;
54
+ actions: PageAction[];
55
+ };
56
+ /** A write the host may want the human to confirm (trust-but-verify). */
57
+ type NavigationConfirmRequest = {
58
+ action: "submit" | "click";
59
+ handle: string;
60
+ label: string;
61
+ };
62
+ /**
63
+ * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
64
+ * a DOM walker (see resources/js/agent/CoBrowseProvider.tsx). Every method
65
+ * works on stable handles, never raw selectors.
66
+ */
67
+ type NavigationBridgeAdapter = {
68
+ /** Optional fancy-screens screen id for presence targeting. */
69
+ screenId?: string;
70
+ /** Current location. */
71
+ getLocation: () => {
72
+ url: string;
73
+ title: string;
74
+ };
75
+ /** Snapshot of the page's actionable elements (stable handles + labels). */
76
+ describe: () => PageSnapshot;
77
+ /** Visible text / heading outline for grounding (optional). */
78
+ read?: () => string;
79
+ /** Navigate to a URL (host wires to router.visit). */
80
+ visit: (url: string) => void | Promise<void>;
81
+ back?: () => void | Promise<void>;
82
+ forward?: () => void | Promise<void>;
83
+ /** Scroll to coords or to a handle's element. */
84
+ scrollTo: (opts: {
85
+ x?: number;
86
+ y?: number;
87
+ handle?: string;
88
+ }) => void;
89
+ scrollBy: (dy: number) => void;
90
+ /** Set a field's value by handle (host dispatches input/change for React). */
91
+ setField: (handle: string, value: unknown) => {
92
+ ok: boolean;
93
+ error?: string;
94
+ };
95
+ /** Activate an element by handle. */
96
+ click: (handle: string) => {
97
+ ok: boolean;
98
+ error?: string;
99
+ };
100
+ /** Submit a form by handle. */
101
+ submit: (handle: string) => Promise<{
102
+ ok: boolean;
103
+ error?: string;
104
+ }> | {
105
+ ok: boolean;
106
+ error?: string;
107
+ };
108
+ /**
109
+ * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
110
+ * destructive `page_click` route through this; the host shows a prompt and
111
+ * resolves true (proceed) / false (declined).
112
+ */
113
+ confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
114
+ };
115
+ type NavigationBridgeOptions = {
116
+ adapter: NavigationBridgeAdapter;
117
+ /** Identity tagged into activity events (so the human sees who's driving). */
118
+ agent?: {
119
+ id: string;
120
+ name?: string;
121
+ color?: string;
122
+ };
123
+ /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
124
+ pendingMode?: boolean;
125
+ };
126
+ /**
127
+ * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
128
+ * navigate, scroll, and (with staged confirm) fill + click any page, addressed
129
+ * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
130
+ * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
131
+ */
132
+ declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
133
+
134
+ /** A thing the human did, surfaced so the connected agent stays aware. */
135
+ type CoBrowseUserEvent = {
136
+ kind: "navigation";
137
+ url: string;
138
+ title?: string;
139
+ } | {
140
+ kind: "scroll";
141
+ y: number;
142
+ } | {
143
+ kind: "form";
144
+ handle: string;
145
+ value?: unknown;
146
+ masked?: boolean;
147
+ };
148
+ type UseCoBrowseSessionOptions = {
149
+ /**
150
+ * The navigation adapter (Inertia + DOM in the sandbox). MUST be stable —
151
+ * its methods should read live state via refs, since the bridge captures it
152
+ * once on mount. Memoize it.
153
+ */
154
+ adapter: NavigationBridgeAdapter;
155
+ /** Identity for the agent's presence (cursor/log color + name). */
156
+ agent?: {
157
+ id: string;
158
+ name?: string;
159
+ color?: string;
160
+ };
161
+ /** Relay base path. Default "/whiteboard-share" (the generic frame broker). */
162
+ relayBaseUrl?: string;
163
+ /** MCP server info advertised to the agent. */
164
+ info?: {
165
+ name: string;
166
+ version: string;
167
+ instructions?: string;
168
+ };
169
+ /** Register extra bridges (forms/screens/…) on the same server. */
170
+ extraBridges?: (server: MicroMcpServer) => void;
171
+ /** CSRF token for the relay register/unregister POSTs. */
172
+ csrfToken?: () => string | null | undefined;
173
+ /** Stage submit + destructive clicks for human confirm. Default true. */
174
+ pendingMode?: boolean;
175
+ };
176
+ type CoBrowseSession = {
177
+ server: MicroMcpServer | null;
178
+ session: SessionDescriptor | null;
179
+ relayState: RelayState;
180
+ startShare: () => Promise<void>;
181
+ stopShare: () => void;
182
+ /**
183
+ * Report a human action so the connected agent is notified. Emits a
184
+ * `source:"user"` activity event, which the SSE relay forwards to the agent
185
+ * as a `notifications/agent_activity` frame.
186
+ */
187
+ observeUser: (event: CoBrowseUserEvent) => void;
188
+ };
189
+ /**
190
+ * Site-wide co-browsing session: one persistent in-page `MicroMcpServer` running
191
+ * the navigation bridge, joinable by an external agent over the relay. Mount it
192
+ * once at the app root; render `<CoBrowsePresence>` to show the agent + a Stop
193
+ * control. The host wires `observeUser(...)` to navigation/scroll/form listeners
194
+ * so the agent sees what the human does.
195
+ */
196
+ declare function useCoBrowseSession(options: UseCoBrowseSessionOptions): CoBrowseSession;
197
+
29
198
  type AgentActivity = {
30
199
  id: string;
31
200
  /** Wall-clock timestamp; component formats it. */
@@ -203,4 +372,26 @@ type ShareControlsProps = {
203
372
  */
204
373
  declare function ShareControls({ session, onStart, onStop, status, shareBaseUrl, className, style, }: ShareControlsProps): react.JSX.Element;
205
374
 
206
- export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, BridgedForm, type BridgedFormProps, FormFieldDescriptor, MicroMcpServer, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps };
375
+ type CoBrowsePresenceProps = {
376
+ /** The session from `useCoBrowseSession`. */
377
+ session: CoBrowseSession;
378
+ /** Public MCP/connect URL shown to the user (for ConnectorButtons), optional. */
379
+ connectUrl?: string;
380
+ /** Base URL used to build the shareable session link. */
381
+ shareBaseUrl?: string;
382
+ className?: string;
383
+ };
384
+ /**
385
+ * The human's view of a site-wide co-browsing session: a "Let an agent drive"
386
+ * starter, the share/connect surface once started, a live "agent is driving"
387
+ * status with the latest action, and a Stop / take-back-control button.
388
+ *
389
+ * Staged-action confirms are rendered by the HOST (via the navigation adapter's
390
+ * `confirm`), so this component stays presentation-only.
391
+ */
392
+ declare function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }: CoBrowsePresenceProps): react.JSX.Element;
393
+ declare namespace CoBrowsePresence {
394
+ var displayName: string;
395
+ }
396
+
397
+ export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, BridgedForm, type BridgedFormProps, 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, ToolHost, type UseCoBrowseSessionOptions, registerNavigationBridge, useCoBrowseSession };