@particle-academy/agent-integrations 0.12.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/README.md +20 -0
- package/dist/chunk-54QEFRMS.js +285 -0
- package/dist/chunk-54QEFRMS.js.map +1 -0
- package/dist/chunk-GO2Y6H6U.js +62 -0
- package/dist/chunk-GO2Y6H6U.js.map +1 -0
- package/dist/connectors/build.d.cts +56 -0
- package/dist/connectors/build.d.ts +56 -0
- package/dist/connectors/index.d.cts +130 -0
- package/dist/connectors/index.d.ts +130 -0
- package/dist/connectors-build.cjs +133 -0
- package/dist/connectors-build.cjs.map +1 -0
- package/dist/connectors-build.js +66 -0
- package/dist/connectors-build.js.map +1 -0
- package/dist/connectors.cjs +366 -0
- package/dist/connectors.cjs.map +1 -0
- package/dist/connectors.js +4 -0
- package/dist/connectors.js.map +1 -0
- package/dist/index.cjs +841 -169
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +199 -6
- package/dist/index.d.ts +199 -6
- package/dist/index.js +325 -7
- package/dist/index.js.map +1 -1
- package/dist/mcpb-BXOrsRnv.d.cts +54 -0
- package/dist/mcpb-BXOrsRnv.d.ts +54 -0
- package/dist/styles.css +156 -0
- package/dist/styles.css.map +1 -1
- package/docs/connectors.md +118 -0
- package/package.json +28 -2
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
|
-
|
|
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
|
-
|
|
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,16 +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
|
|
18
|
-
|
|
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 {
|
|
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';
|
|
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';
|
|
25
30
|
import '@particle-academy/fancy-slides';
|
|
26
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
|
+
|
|
27
198
|
type AgentActivity = {
|
|
28
199
|
id: string;
|
|
29
200
|
/** Wall-clock timestamp; component formats it. */
|
|
@@ -201,4 +372,26 @@ type ShareControlsProps = {
|
|
|
201
372
|
*/
|
|
202
373
|
declare function ShareControls({ session, onStart, onStop, status, shareBaseUrl, className, style, }: ShareControlsProps): react.JSX.Element;
|
|
203
374
|
|
|
204
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,16 +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
|
|
18
|
-
|
|
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 {
|
|
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';
|
|
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';
|
|
25
30
|
import '@particle-academy/fancy-slides';
|
|
26
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
|
+
|
|
27
198
|
type AgentActivity = {
|
|
28
199
|
id: string;
|
|
29
200
|
/** Wall-clock timestamp; component formats it. */
|
|
@@ -201,4 +372,26 @@ type ShareControlsProps = {
|
|
|
201
372
|
*/
|
|
202
373
|
declare function ShareControls({ session, onStart, onStop, status, shareBaseUrl, className, style, }: ShareControlsProps): react.JSX.Element;
|
|
203
374
|
|
|
204
|
-
|
|
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 };
|