@particle-academy/agent-integrations 0.9.0 → 0.10.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
@@ -13,6 +13,7 @@ export { ChartsBridgeAdapter, ChartsBridgeOptions, registerChartsBridge } from '
13
13
  export { SceneBridgeAdapter, SceneBridgeOptions, SceneCamera, SceneObject, SceneObjectKind, SceneState, registerSceneBridge } from './bridges/scene.cjs';
14
14
  export { ScreenSnapshot, ScreensBridgeAdapter, ScreensBridgeOptions, registerScreensBridge } from './bridges/screens.cjs';
15
15
  export { SlidesBridgeAdapter, SlidesBridgeOptions, registerSlidesBridge } from './bridges/slides.cjs';
16
+ export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, registerTerminalBridge } from './bridges/terminal.cjs';
16
17
  import * as react from 'react';
17
18
  import { ReactNode, CSSProperties } from 'react';
18
19
  import { S as SessionDescriptor } from './token-CrJF76oH.cjs';
package/dist/index.d.ts CHANGED
@@ -13,6 +13,7 @@ export { ChartsBridgeAdapter, ChartsBridgeOptions, registerChartsBridge } from '
13
13
  export { SceneBridgeAdapter, SceneBridgeOptions, SceneCamera, SceneObject, SceneObjectKind, SceneState, registerSceneBridge } from './bridges/scene.js';
14
14
  export { ScreenSnapshot, ScreensBridgeAdapter, ScreensBridgeOptions, registerScreensBridge } from './bridges/screens.js';
15
15
  export { SlidesBridgeAdapter, SlidesBridgeOptions, registerSlidesBridge } from './bridges/slides.js';
16
+ export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, registerTerminalBridge } from './bridges/terminal.js';
16
17
  import * as react from 'react';
17
18
  import { ReactNode, CSSProperties } from 'react';
18
19
  import { S as SessionDescriptor } from './token-CrJF76oH.js';
package/dist/index.js CHANGED
@@ -1,13 +1,14 @@
1
+ export { useAgentActivity, useAgentActivityForScreen } from './chunk-UCKJAUBY.js';
1
2
  export { useUndoStack } from './chunk-GHY3PBPN.js';
2
3
  export { registerChartsBridge } from './chunk-SJ7H242B.js';
3
4
  export { registerSceneBridge } from './chunk-VUMFO2UW.js';
4
5
  export { registerScreensBridge } from './chunk-CKK4QKD2.js';
5
6
  export { registerSlidesBridge } from './chunk-R5OA26MJ.js';
7
+ export { registerTerminalBridge } from './chunk-353O6IBR.js';
6
8
  export { useSheetsActivityHighlights, useSheetsAdapter } from './chunk-KHKSQEMC.js';
7
9
  export { AgentActivityHighlight, AgentCursor, AgentPanel, ShareControls } from './chunk-J5KYPEYB.js';
8
10
  import './chunk-IJ6JX5VC.js';
9
11
  export { SseRelayTransport, attachSseRelay, buildShareConfig, buildShareUrl, createSessionDescriptor, describeSession, readSessionFromUrl } from './chunk-CPNOF4HI.js';
10
- export { useAgentActivity, useAgentActivityForScreen } from './chunk-UCKJAUBY.js';
11
12
  export { RelayTransport, attachRelay } from './chunk-G6N2TQVO.js';
12
13
  export { InProcessTransport, attachInProcess } from './chunk-AFUULW5E.js';
13
14
  export { clearStack as clearUndoStack, ensureUndoToolsRegistered, pushUndoEntry, readHistory as readUndoHistory, redoOne, registerUndoTools, resetAllUndoStacks, undoOne } from './chunk-KJ5AOOV7.js';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/components/BridgedForm/BridgedForm.tsx","../src/components/ScreensActivityBridge/ScreensActivityBridge.tsx"],"names":["useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { type ReactNode, useEffect, useMemo, useRef } from \"react\";\nimport type { MicroMcpServer } from \"../../mcp/server\";\nimport { registerFormBridge, type FormBridgeAdapter, type FormFieldDescriptor } from \"../../bridges/forms\";\n\nexport type BridgedFormProps = {\n /** Stable id for this form. Used by agents in `form_*` tool calls. */\n id: string;\n /** Human title (also surfaced as the bridge title). */\n title?: string;\n /** Optional fancy-screens screen id this form lives in. */\n screenId?: string;\n /** Field descriptors — drives the agent-facing schema. */\n fields: FormFieldDescriptor[];\n /** Controlled values. */\n values: Record<string, unknown>;\n /** Setter — hosts pass their setState. */\n onChange: (next: Record<string, unknown>) => void;\n /** Optional submit handler. */\n onSubmit?: () => Promise<{ ok: boolean; values?: Record<string, unknown>; error?: string }>;\n /** The MicroMcpServer the bridge registers against. Pass null/undefined\n * to render without a bridge (useful for stories / non-shared use). */\n server?: MicroMcpServer | null;\n /** Identity used in activity events. */\n agent?: { id: string; name?: string; color?: string };\n children: ReactNode;\n};\n\n/**\n * BridgedForm — wraps a react-fancy form (or any controlled inputs)\n * with a `registerFormBridge` lifecycle. Children render the actual form\n * using `values` + `onChange`; this component only manages the bridge.\n *\n * Hosts use it like:\n *\n * <BridgedForm id=\"signup\" fields={...} values={values} onChange={setValues} server={server}>\n * <Field><Input value={values.email} onValueChange={(v) => onChange({ ...values, email: v })} /></Field>\n * ...\n * </BridgedForm>\n *\n * Agents can then call form_describe, form_set_value, form_submit, etc.\n */\nexport function BridgedForm({\n id,\n title,\n screenId,\n fields,\n values,\n onChange,\n onSubmit,\n server,\n agent,\n children,\n}: BridgedFormProps) {\n // Refs so the adapter sees fresh values without re-installing the bridge.\n const valuesRef = useRef(values);\n const onChangeRef = useRef(onChange);\n const fieldsRef = useRef(fields);\n const submitRef = useRef(onSubmit);\n useEffect(() => { valuesRef.current = values; }, [values]);\n useEffect(() => { onChangeRef.current = onChange; }, [onChange]);\n useEffect(() => { fieldsRef.current = fields; }, [fields]);\n useEffect(() => { submitRef.current = onSubmit; }, [onSubmit]);\n\n const focusElement = (name: string) => {\n if (typeof document === \"undefined\") return;\n const el = document.querySelector(`[data-form-id=\"${id}\"] [name=\"${name}\"]`) as HTMLElement | null;\n el?.focus();\n };\n\n const adapter = useMemo<FormBridgeAdapter>(() => ({\n id,\n title,\n screenId,\n getFields: () => fieldsRef.current,\n getValue: (name) => valuesRef.current[name],\n getValues: () => ({ ...valuesRef.current }),\n setValue: (name, v) => onChangeRef.current({ ...valuesRef.current, [name]: v }),\n setValues: (next) => onChangeRef.current({ ...valuesRef.current, ...next }),\n focus: focusElement,\n submit: async () => {\n if (!submitRef.current) {\n return { ok: true, values: { ...valuesRef.current } };\n }\n return submitRef.current();\n },\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }), [id, title, screenId]);\n\n useEffect(() => {\n if (!server) return;\n const bridge = registerFormBridge(server, { adapter, agent });\n return () => bridge.dispose();\n }, [server, adapter, agent]);\n\n return <div data-form-id={id}>{children}</div>;\n}\n","import { useEffect } from \"react\";\nimport { onActivity } from \"../../presence/registry\";\n\n/**\n * Loose shape of the fancy-screens system context — kept here so this\n * component doesn't hard-import `@particle-academy/fancy-screens`.\n */\ntype ScreenSystemLike = {\n registry: Map<string, { id: string; agentActivity?: unknown }>;\n updateScreen: (id: string, patch: { agentActivity?: unknown }) => void;\n};\n\nexport type ScreensActivityBridgeProps = {\n /** The value returned by `useScreenSystem()` from fancy-screens. */\n system: ScreenSystemLike;\n /** ms to wait after the last activity before clearing the screen's badge. Default 1500. */\n fadeMs?: number;\n};\n\n/**\n * ScreensActivityBridge — subscribe to the in-process activity registry\n * and patch each event into the matching screen's `agentActivity` field.\n * Fade-out clears the badge after `fadeMs`.\n *\n * Use it once near the root of your app, ABOVE every <Screen>:\n *\n * const system = useScreenSystem();\n * <>\n * <ScreensActivityBridge system={system} />\n * <Screen id=\"dashboard\">…</Screen>\n * <Screen id=\"form\">…</Screen>\n * </>\n *\n * Renders nothing; pure side-effect component.\n */\nexport function ScreensActivityBridge({ system, fadeMs = 1500 }: ScreensActivityBridgeProps) {\n useEffect(() => {\n const fadeTimers = new Map<string, ReturnType<typeof setTimeout>>();\n const off = onActivity((event) => {\n const screenId = event.target.screenId;\n if (!screenId) return;\n // Only patch screens that are currently registered.\n if (!system.registry.has(screenId)) return;\n const activity = {\n agentId: event.agentId,\n agentName: event.agentName,\n agentColor: event.agentColor,\n action: event.action,\n timestamp: event.timestamp,\n elementId: event.target.elementId,\n label: event.target.label,\n };\n system.updateScreen(screenId, { agentActivity: activity });\n const prev = fadeTimers.get(screenId);\n if (prev) clearTimeout(prev);\n fadeTimers.set(\n screenId,\n setTimeout(() => {\n system.updateScreen(screenId, { agentActivity: null });\n fadeTimers.delete(screenId);\n }, event.ttlMs ?? fadeMs),\n );\n });\n return () => {\n off();\n for (const t of fadeTimers.values()) clearTimeout(t);\n };\n }, [system, fadeMs]);\n return null;\n}\n"]}
1
+ {"version":3,"sources":["../src/components/BridgedForm/BridgedForm.tsx","../src/components/ScreensActivityBridge/ScreensActivityBridge.tsx"],"names":["useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { type ReactNode, useEffect, useMemo, useRef } from \"react\";\nimport type { MicroMcpServer } from \"../../mcp/server\";\nimport { registerFormBridge, type FormBridgeAdapter, type FormFieldDescriptor } from \"../../bridges/forms\";\n\nexport type BridgedFormProps = {\n /** Stable id for this form. Used by agents in `form_*` tool calls. */\n id: string;\n /** Human title (also surfaced as the bridge title). */\n title?: string;\n /** Optional fancy-screens screen id this form lives in. */\n screenId?: string;\n /** Field descriptors — drives the agent-facing schema. */\n fields: FormFieldDescriptor[];\n /** Controlled values. */\n values: Record<string, unknown>;\n /** Setter — hosts pass their setState. */\n onChange: (next: Record<string, unknown>) => void;\n /** Optional submit handler. */\n onSubmit?: () => Promise<{ ok: boolean; values?: Record<string, unknown>; error?: string }>;\n /** The MicroMcpServer the bridge registers against. Pass null/undefined\n * to render without a bridge (useful for stories / non-shared use). */\n server?: MicroMcpServer | null;\n /** Identity used in activity events. */\n agent?: { id: string; name?: string; color?: string };\n children: ReactNode;\n};\n\n/**\n * BridgedForm — wraps a react-fancy form (or any controlled inputs)\n * with a `registerFormBridge` lifecycle. Children render the actual form\n * using `values` + `onChange`; this component only manages the bridge.\n *\n * Hosts use it like:\n *\n * <BridgedForm id=\"signup\" fields={...} values={values} onChange={setValues} server={server}>\n * <Field><Input value={values.email} onValueChange={(v) => onChange({ ...values, email: v })} /></Field>\n * ...\n * </BridgedForm>\n *\n * Agents can then call form_describe, form_set_value, form_submit, etc.\n */\nexport function BridgedForm({\n id,\n title,\n screenId,\n fields,\n values,\n onChange,\n onSubmit,\n server,\n agent,\n children,\n}: BridgedFormProps) {\n // Refs so the adapter sees fresh values without re-installing the bridge.\n const valuesRef = useRef(values);\n const onChangeRef = useRef(onChange);\n const fieldsRef = useRef(fields);\n const submitRef = useRef(onSubmit);\n useEffect(() => { valuesRef.current = values; }, [values]);\n useEffect(() => { onChangeRef.current = onChange; }, [onChange]);\n useEffect(() => { fieldsRef.current = fields; }, [fields]);\n useEffect(() => { submitRef.current = onSubmit; }, [onSubmit]);\n\n const focusElement = (name: string) => {\n if (typeof document === \"undefined\") return;\n const el = document.querySelector(`[data-form-id=\"${id}\"] [name=\"${name}\"]`) as HTMLElement | null;\n el?.focus();\n };\n\n const adapter = useMemo<FormBridgeAdapter>(() => ({\n id,\n title,\n screenId,\n getFields: () => fieldsRef.current,\n getValue: (name) => valuesRef.current[name],\n getValues: () => ({ ...valuesRef.current }),\n setValue: (name, v) => onChangeRef.current({ ...valuesRef.current, [name]: v }),\n setValues: (next) => onChangeRef.current({ ...valuesRef.current, ...next }),\n focus: focusElement,\n submit: async () => {\n if (!submitRef.current) {\n return { ok: true, values: { ...valuesRef.current } };\n }\n return submitRef.current();\n },\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }), [id, title, screenId]);\n\n useEffect(() => {\n if (!server) return;\n const bridge = registerFormBridge(server, { adapter, agent });\n return () => bridge.dispose();\n }, [server, adapter, agent]);\n\n return <div data-form-id={id}>{children}</div>;\n}\n","import { useEffect } from \"react\";\nimport { onActivity } from \"../../presence/registry\";\n\n/**\n * Loose shape of the fancy-screens system context — kept here so this\n * component doesn't hard-import `@particle-academy/fancy-screens`.\n */\ntype ScreenSystemLike = {\n registry: Map<string, { id: string; agentActivity?: unknown }>;\n updateScreen: (id: string, patch: { agentActivity?: unknown }) => void;\n};\n\nexport type ScreensActivityBridgeProps = {\n /** The value returned by `useScreenSystem()` from fancy-screens. */\n system: ScreenSystemLike;\n /** ms to wait after the last activity before clearing the screen's badge. Default 1500. */\n fadeMs?: number;\n};\n\n/**\n * ScreensActivityBridge — subscribe to the in-process activity registry\n * and patch each event into the matching screen's `agentActivity` field.\n * Fade-out clears the badge after `fadeMs`.\n *\n * Use it once near the root of your app, ABOVE every <Screen>:\n *\n * const system = useScreenSystem();\n * <>\n * <ScreensActivityBridge system={system} />\n * <Screen id=\"dashboard\">…</Screen>\n * <Screen id=\"form\">…</Screen>\n * </>\n *\n * Renders nothing; pure side-effect component.\n */\nexport function ScreensActivityBridge({ system, fadeMs = 1500 }: ScreensActivityBridgeProps) {\n useEffect(() => {\n const fadeTimers = new Map<string, ReturnType<typeof setTimeout>>();\n const off = onActivity((event) => {\n const screenId = event.target.screenId;\n if (!screenId) return;\n // Only patch screens that are currently registered.\n if (!system.registry.has(screenId)) return;\n const activity = {\n agentId: event.agentId,\n agentName: event.agentName,\n agentColor: event.agentColor,\n action: event.action,\n timestamp: event.timestamp,\n elementId: event.target.elementId,\n label: event.target.label,\n };\n system.updateScreen(screenId, { agentActivity: activity });\n const prev = fadeTimers.get(screenId);\n if (prev) clearTimeout(prev);\n fadeTimers.set(\n screenId,\n setTimeout(() => {\n system.updateScreen(screenId, { agentActivity: null });\n fadeTimers.delete(screenId);\n }, event.ttlMs ?? fadeMs),\n );\n });\n return () => {\n off();\n for (const t of fadeTimers.values()) clearTimeout(t);\n };\n }, [system, fadeMs]);\n return null;\n}\n"]}
@@ -41,7 +41,10 @@ Three pieces. You write zero of them yourself if you follow this guide:
41
41
  complete Laravel controller).
42
42
 
43
43
  3. **The agent's client.** Out of your control — visitors paste your session
44
- URL into whatever MCP client they already use.
44
+ URL into whatever MCP client they already use. If they don't have one, point
45
+ them at [`mcp-relay-client`](https://github.com/Particle-Academy/mcp-relay-client):
46
+ a single-file, zero-dependency client (bash / Python / TS / Go) they download
47
+ and aim at the session URL.
45
48
 
46
49
  ## End-user UX
47
50
 
@@ -54,7 +57,9 @@ This is what visitors actually experience. Every demo follows the same shape:
54
57
  4. The page mints a per-session token, registers it with the relay, and shows
55
58
  a copyable share URL.
56
59
  5. Visitor pastes the URL into their MCP client (`.mcp.json` for Claude Code,
57
- Cursor's MCP settings, etc.). The client connects to the relay.
60
+ Cursor's MCP settings, etc.), or downloads
61
+ [`mcp-relay-client`](https://github.com/Particle-Academy/mcp-relay-client)
62
+ and aims it at the URL. The client connects to the relay.
58
63
  6. Agent calls tools → tools mutate the host page's React state → visitor
59
64
  watches the surface change in real time. Optional: agent cursor + tool-call
60
65
  feed render alongside.
@@ -18,6 +18,27 @@ across restarts.
18
18
  Code → the relay is hosted somewhere reachable from both the browser and the
19
19
  agent's machine.
20
20
 
21
+ ## Connecting a client to a session
22
+
23
+ This doc covers running the **broker**. The agent connects from the other end
24
+ with an MCP **client** pointed at a session URL. Two options:
25
+
26
+ - **A generic MCP client you already have** — paste the session URL into Claude
27
+ Code's `.mcp.json`, Cursor's MCP settings, Claude Desktop, etc.
28
+ - **[`mcp-relay-client`](https://github.com/Particle-Academy/mcp-relay-client)** —
29
+ a super-lite, **single-file, zero-dependency** client in bash / Python / TS /
30
+ Go, purpose-built for these relay sessions. Grab the one you have a runtime for
31
+ and point it at the session URL:
32
+
33
+ ```bash
34
+ curl -O https://raw.githubusercontent.com/Particle-Academy/mcp-relay-client/main/connect.sh
35
+ bash connect.sh "https://host/agent-playground?session=ABC&token=XYZ" tools
36
+ bash connect.sh "<session-url>" call whiteboard_add_sticky '{"x":300,"y":200,"text":"hi"}'
37
+ ```
38
+
39
+ It derives the relay endpoints, session id, and token from the URL and runs the
40
+ full `initialize` → `tools/list` → `tools/call` handshake for you.
41
+
21
42
  ## Three ways to run it
22
43
 
23
44
  ### 1. `npx` — local dev / one-off prod
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@particle-academy/agent-integrations",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "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).",
5
5
  "repository": {
6
6
  "type": "git",
@@ -137,6 +137,16 @@
137
137
  "default": "./dist/bridges-slides.cjs"
138
138
  }
139
139
  },
140
+ "./bridges/terminal": {
141
+ "import": {
142
+ "types": "./dist/bridges/terminal.d.ts",
143
+ "default": "./dist/bridges-terminal.js"
144
+ },
145
+ "require": {
146
+ "types": "./dist/bridges/terminal.d.cts",
147
+ "default": "./dist/bridges-terminal.cjs"
148
+ }
149
+ },
140
150
  "./sheets-adapter": {
141
151
  "import": {
142
152
  "types": "./dist/sheets-adapter.d.ts",
@@ -221,11 +231,11 @@
221
231
  "fancy"
222
232
  ],
223
233
  "peerDependencies": {
224
- "@particle-academy/fancy-artboard": "^0.1.0",
225
- "@particle-academy/fancy-flow": "^0.2.0 || ^0.3.0",
226
- "@particle-academy/fancy-sheets": "^0.1.0",
227
- "@particle-academy/fancy-slides": "^0.1.4 || ^0.2.0 || ^0.3.0 || ^0.4.0 || ^0.10.0",
228
- "@particle-academy/fancy-whiteboard": "^0.1.0",
234
+ "@particle-academy/fancy-artboard": ">=0.1.0",
235
+ "@particle-academy/fancy-flow": ">=0.2.0",
236
+ "@particle-academy/fancy-sheets": ">=0.1.0",
237
+ "@particle-academy/fancy-slides": ">=0.1.4",
238
+ "@particle-academy/fancy-whiteboard": ">=0.1.0",
229
239
  "react": "^18.0.0 || ^19.0.0",
230
240
  "react-dom": "^18.0.0 || ^19.0.0"
231
241
  },
@@ -247,8 +257,8 @@
247
257
  }
248
258
  },
249
259
  "devDependencies": {
250
- "@particle-academy/fancy-slides": "^0.10.0",
251
- "@particle-academy/fancy-whiteboard": "^0.1.5",
260
+ "@particle-academy/fancy-slides": "^0.12.0",
261
+ "@particle-academy/fancy-whiteboard": "^0.2.0",
252
262
  "@types/node": "^22.0.0",
253
263
  "@types/react": "^19.0.0",
254
264
  "@types/react-dom": "^19.0.0",