trusted-user-agent 0.0.0-stage → 0.4.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.
Files changed (100) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +232 -2
  3. package/dist/acp/agent.js +719 -0
  4. package/dist/acp/agents/connection.js +298 -0
  5. package/dist/acp/agents/manager.js +363 -0
  6. package/dist/acp/agents/registry.js +201 -0
  7. package/dist/acp/agents/relay-session.js +371 -0
  8. package/dist/acp/agents/session-index.js +102 -0
  9. package/dist/acp/backend.js +2 -0
  10. package/dist/acp/config-options.js +26 -0
  11. package/dist/acp/mock-backend.js +277 -0
  12. package/dist/acp/sdk-backend.js +495 -0
  13. package/dist/browser/mcp-acp-client.js +81 -0
  14. package/dist/browser/provider.js +1049 -0
  15. package/dist/browser/schemas.js +221 -0
  16. package/dist/capability-registry.js +92 -0
  17. package/dist/client-heartbeat.js +118 -0
  18. package/dist/compose/schemas.js +90 -0
  19. package/dist/contacts/schemas.js +26 -0
  20. package/dist/installer/cli.js +70 -0
  21. package/dist/installer/common.js +93 -0
  22. package/dist/installer/index.js +366 -0
  23. package/dist/installer/mcp-clients.js +555 -0
  24. package/dist/installer/mcp.js +166 -0
  25. package/dist/installer/platforms.js +277 -0
  26. package/dist/logger.js +54 -0
  27. package/dist/mail/schemas.js +98 -0
  28. package/dist/mutation/schemas.js +31 -0
  29. package/dist/native-host/broker-ipc.js +344 -0
  30. package/dist/native-host/framing.js +76 -0
  31. package/dist/native-host/main.js +545 -0
  32. package/dist/native-host/mcp-server.js +333 -0
  33. package/dist/native-host/mcp-stdio-bridge.js +184 -0
  34. package/dist/native-host/mcp-stdio-main.js +13 -0
  35. package/dist/native-host/relay.js +84 -0
  36. package/dist/native-host/skills-startup.js +167 -0
  37. package/dist/native-host/transport.js +248 -0
  38. package/dist/permission-store.js +207 -0
  39. package/dist/repl/fs-sandbox.js +187 -0
  40. package/dist/repl/provider.js +252 -0
  41. package/dist/repl/runtime.js +436 -0
  42. package/dist/repl/types.js +10 -0
  43. package/dist/repl/worker.js +731 -0
  44. package/dist/skills/extension.js +99 -0
  45. package/dist/skills/grants-file.js +145 -0
  46. package/dist/skills/isolated-runner.js +259 -0
  47. package/dist/skills/mock-session-factory.js +49 -0
  48. package/dist/skills/package-roots.js +25 -0
  49. package/dist/skills/pi-bridge.js +8 -0
  50. package/dist/skills/pi-integration.js +110 -0
  51. package/dist/skills/planner.js +128 -0
  52. package/dist/skills/registry.js +104 -0
  53. package/dist/skills/skills-protocol.js +253 -0
  54. package/dist/skills/skills-service.js +195 -0
  55. package/dist/tool-bridge.js +8 -0
  56. package/dist/workspace.js +70 -0
  57. package/extensions/pi-browser-tools.ts +65 -0
  58. package/extensions/pi-browser.ts +60 -0
  59. package/extensions/pi-skills.ts +14 -0
  60. package/native/pi-agent-host +2 -0
  61. package/native/pi-browser-host +5 -0
  62. package/native/pi-browser-host.cmd +3 -0
  63. package/node_modules/@pi-browser/protocol/.bundled-by-trusted-user-agent +0 -0
  64. package/node_modules/@pi-browser/protocol/dist/acp.d.ts +10 -0
  65. package/node_modules/@pi-browser/protocol/dist/acp.js +9 -0
  66. package/node_modules/@pi-browser/protocol/dist/agents.d.ts +51 -0
  67. package/node_modules/@pi-browser/protocol/dist/agents.js +44 -0
  68. package/node_modules/@pi-browser/protocol/dist/browser-tools.d.ts +33 -0
  69. package/node_modules/@pi-browser/protocol/dist/browser-tools.js +478 -0
  70. package/node_modules/@pi-browser/protocol/dist/callers.d.ts +123 -0
  71. package/node_modules/@pi-browser/protocol/dist/callers.js +58 -0
  72. package/node_modules/@pi-browser/protocol/dist/compose-tools.d.ts +30 -0
  73. package/node_modules/@pi-browser/protocol/dist/compose-tools.js +175 -0
  74. package/node_modules/@pi-browser/protocol/dist/contacts-tools.d.ts +23 -0
  75. package/node_modules/@pi-browser/protocol/dist/contacts-tools.js +63 -0
  76. package/node_modules/@pi-browser/protocol/dist/control-tools.d.ts +32 -0
  77. package/node_modules/@pi-browser/protocol/dist/control-tools.js +201 -0
  78. package/node_modules/@pi-browser/protocol/dist/errors.d.ts +63 -0
  79. package/node_modules/@pi-browser/protocol/dist/errors.js +109 -0
  80. package/node_modules/@pi-browser/protocol/dist/index.d.ts +17 -0
  81. package/node_modules/@pi-browser/protocol/dist/index.js +17 -0
  82. package/node_modules/@pi-browser/protocol/dist/integration.d.ts +414 -0
  83. package/node_modules/@pi-browser/protocol/dist/integration.js +270 -0
  84. package/node_modules/@pi-browser/protocol/dist/jsonrpc.d.ts +33 -0
  85. package/node_modules/@pi-browser/protocol/dist/jsonrpc.js +31 -0
  86. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.d.ts +27 -0
  87. package/node_modules/@pi-browser/protocol/dist/mail-mutation-tools.js +88 -0
  88. package/node_modules/@pi-browser/protocol/dist/mail-tools.d.ts +133 -0
  89. package/node_modules/@pi-browser/protocol/dist/mail-tools.js +245 -0
  90. package/node_modules/@pi-browser/protocol/dist/permission.d.ts +113 -0
  91. package/node_modules/@pi-browser/protocol/dist/permission.js +257 -0
  92. package/node_modules/@pi-browser/protocol/dist/skills.d.ts +304 -0
  93. package/node_modules/@pi-browser/protocol/dist/skills.js +473 -0
  94. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.d.ts +18 -0
  95. package/node_modules/@pi-browser/protocol/dist/tool-capabilities.js +52 -0
  96. package/node_modules/@pi-browser/protocol/dist/transport.d.ts +17 -0
  97. package/node_modules/@pi-browser/protocol/dist/transport.js +17 -0
  98. package/node_modules/@pi-browser/protocol/package.json +14 -0
  99. package/package.json +69 -4
  100. package/skills/browser-walk/SKILL.md +98 -0
@@ -0,0 +1,478 @@
1
+ /**
2
+ * MCP-compatible browser tool definitions (PRODUCT.md §25).
3
+ *
4
+ * These schemas are transport-independent: the same names, arguments, and
5
+ * results are used whether tools are invoked over the private
6
+ * x-pi-browser/tool compatibility transport or over MCP (stdio/HTTP or
7
+ * MCP-over-ACP). The Firefox side implements the tools; the Pi side
8
+ * registers them as agent tools.
9
+ */
10
+ const OBJECT_SCHEMA_BASE = {
11
+ type: "object",
12
+ additionalProperties: false,
13
+ };
14
+ /**
15
+ * Optional frame target for tools that run in a frame's content script.
16
+ * A frameId (number) or a URL substring (string) — the frames list in
17
+ * browser_get_dom's result is what the agent picks from. Absent = top frame.
18
+ */
19
+ export const BROWSER_FRAME_DESCRIPTION = "Optional frame to operate in: a frameId (number) or a URL substring (string) — see the frames list in browser_get_dom. " +
20
+ "Default: the top frame. Frame ids stay valid until the page navigates.";
21
+ const FRAME_PROPERTY = {
22
+ anyOf: [{ type: "number" }, { type: "string" }],
23
+ description: BROWSER_FRAME_DESCRIPTION,
24
+ };
25
+ export const BROWSER_TOOLS = [
26
+ {
27
+ name: "browser_get_page",
28
+ description: "Get basic information about the page in the Firefox tab bound to this session: URL, title, and viewport size.",
29
+ inputSchema: { ...OBJECT_SCHEMA_BASE, properties: {} },
30
+ readOnly: true,
31
+ },
32
+ {
33
+ name: "browser_get_selection",
34
+ description: "Get the current text selection in the bound tab. Returns empty text when nothing is selected.",
35
+ inputSchema: {
36
+ ...OBJECT_SCHEMA_BASE,
37
+ properties: {
38
+ frame: { ...FRAME_PROPERTY },
39
+ },
40
+ },
41
+ readOnly: true,
42
+ },
43
+ {
44
+ name: "browser_get_dom",
45
+ description: "Get a compact semantic representation of the page in the bound tab with stable element references (ref). " +
46
+ "Covers headings, paragraphs, list items, tables, forms, buttons, links, labels, and any element with an ARIA role, " +
47
+ "tabindex, aria-label, or data-testid; open web-component shadow roots are traversed. Each element carries its tag, " +
48
+ "role, visible text, and (where relevant) name, href, input type, checked state, heading level, and short class list. " +
49
+ "The result includes stats (scanned/matched/shadow roots) and, when the frame contains iframes, a frames list — if few " +
50
+ "elements match, the page content likely lives in a child frame: re-run with the frame parameter (frameId or URL from the " +
51
+ "frames list). References are valid until the page navigates or the DOM changes significantly; after that, call this " +
52
+ "tool again. Use the returned refs with browser_click and browser_type.",
53
+ inputSchema: {
54
+ ...OBJECT_SCHEMA_BASE,
55
+ properties: {
56
+ maxElements: {
57
+ type: "number",
58
+ description: "Maximum number of elements to return (default 600, hard cap 2000).",
59
+ },
60
+ frame: { ...FRAME_PROPERTY },
61
+ },
62
+ },
63
+ readOnly: true,
64
+ },
65
+ {
66
+ name: "browser_screenshot",
67
+ description: "Capture a screenshot of the bound tab as an image. Returns image data the agent can see.",
68
+ inputSchema: {
69
+ ...OBJECT_SCHEMA_BASE,
70
+ properties: {
71
+ format: {
72
+ anyOf: [{ type: "string", const: "png" }, { type: "string", const: "jpeg" }],
73
+ description: "Image format (default png).",
74
+ },
75
+ quality: { type: "number", description: "JPEG quality 1-100 (jpeg only, default 80)." },
76
+ },
77
+ },
78
+ readOnly: true,
79
+ },
80
+ {
81
+ name: "browser_reload",
82
+ description: "Reload the page in the bound tab.",
83
+ inputSchema: { ...OBJECT_SCHEMA_BASE, properties: {} },
84
+ readOnly: false,
85
+ },
86
+ {
87
+ name: "browser_click",
88
+ description: "Click an element referenced by a stable ref from browser_get_dom in the bound tab. " +
89
+ "The ref becomes stale after navigation; refresh with browser_get_dom if a ref fails.",
90
+ inputSchema: {
91
+ ...OBJECT_SCHEMA_BASE,
92
+ properties: {
93
+ ref: { type: "string", description: "Element reference, e.g. el-183 (from browser_get_dom)." },
94
+ frame: { ...FRAME_PROPERTY },
95
+ },
96
+ required: ["ref"],
97
+ },
98
+ readOnly: false,
99
+ },
100
+ {
101
+ name: "browser_type",
102
+ description: "Type text into an element referenced by a stable ref from browser_get_dom in the bound tab. " +
103
+ "Focuses the element, replaces any existing value for text inputs, and appends for other elements. " +
104
+ "Optionally submits the surrounding form.",
105
+ inputSchema: {
106
+ ...OBJECT_SCHEMA_BASE,
107
+ properties: {
108
+ ref: { type: "string", description: "Element reference, e.g. el-183 (from browser_get_dom)." },
109
+ text: { type: "string", description: "Text to type." },
110
+ submit: { type: "boolean", description: "Submit the element's form after typing (default false)." },
111
+ frame: { ...FRAME_PROPERTY },
112
+ },
113
+ required: ["ref", "text"],
114
+ },
115
+ readOnly: false,
116
+ },
117
+ {
118
+ name: "browser_wait_for",
119
+ description: "Wait in the bound tab until a CSS selector matches (or stops matching) or a timeout elapses. " +
120
+ "Use after actions that trigger async page changes (e.g. after browser_click on a submit button).",
121
+ inputSchema: {
122
+ ...OBJECT_SCHEMA_BASE,
123
+ properties: {
124
+ selector: { type: "string", description: "CSS selector to wait for." },
125
+ state: {
126
+ anyOf: [{ type: "string", const: "visible" }, { type: "string", const: "hidden" }],
127
+ description: "Wait until the element is visible (default) or hidden.",
128
+ },
129
+ timeoutMs: { type: "number", description: "Maximum wait in milliseconds (default 10000, max 60000)." },
130
+ frame: { ...FRAME_PROPERTY },
131
+ },
132
+ required: ["selector"],
133
+ },
134
+ readOnly: true,
135
+ },
136
+ {
137
+ name: "browser_evaluate",
138
+ description: "Run a JavaScript expression in the bound tab and return its JSON-serializable result. " +
139
+ "Runs in the page's JS world when available (page globals such as window.* are visible); otherwise it falls back to " +
140
+ "the extension's isolated world (shared DOM, no page JS globals) — the result says which world ran. " +
141
+ "Functions are supported: pass a function and an arg, e.g. expression \"(sel) => document.querySelectorAll(sel).length\" " +
142
+ "with arg \".nav a\". Promises are awaited. Use to inspect page state the DOM tools do not expose.",
143
+ inputSchema: {
144
+ ...OBJECT_SCHEMA_BASE,
145
+ properties: {
146
+ expression: {
147
+ type: "string",
148
+ description: "JavaScript expression or function, e.g. \"document.title\" or \"(sel) => document.querySelector(sel)?.value\".",
149
+ },
150
+ arg: {
151
+ description: "Optional JSON value passed as the single argument when the expression is a function.",
152
+ },
153
+ frame: { ...FRAME_PROPERTY },
154
+ },
155
+ required: ["expression"],
156
+ },
157
+ readOnly: false,
158
+ },
159
+ {
160
+ name: "browser_get_accessibility_tree",
161
+ description: "Get an indented, accessibility-style outline of the page in the bound tab: semantic roles with accessible names " +
162
+ "and hierarchy. More compact than browser_get_dom and better for understanding page structure; interactive nodes " +
163
+ "carry stable refs usable with browser_click and browser_type. Open web-component shadow roots are traversed; " +
164
+ "iframes appear as leaf lines with their src — if the outline is thin, the content likely lives in a child frame: " +
165
+ "re-run with the frame parameter (see the frames list in browser_get_dom). " +
166
+ "format \"text\" (default) = the indented outline; format \"nodes\" = the same walk as a flat list of structured " +
167
+ "node objects ({ref, role, name, rect, ...}); format \"tree\" = the same walk as a nested node tree " +
168
+ "({role, name, children[]}) — used by the javascript REPL's page.snapshot() (its default format).",
169
+ inputSchema: {
170
+ ...OBJECT_SCHEMA_BASE,
171
+ properties: {
172
+ format: {
173
+ anyOf: [{ const: "text" }, { const: "tree" }, { const: "nodes" }],
174
+ description: '"text" (default) = the indented outline; "tree" = nested node objects ({role, name, children[]}); "nodes" = flat structured node list with refs and rects.',
175
+ },
176
+ maxNodes: {
177
+ type: "number",
178
+ description: "Maximum outline nodes to return (default 300, hard cap 2000).",
179
+ },
180
+ maxDepth: {
181
+ type: "number",
182
+ description: "Maximum outline depth (default 60, hard cap 80).",
183
+ },
184
+ frame: { ...FRAME_PROPERTY },
185
+ },
186
+ },
187
+ readOnly: true,
188
+ },
189
+ {
190
+ name: "browser_get_console",
191
+ description: "Read the console of the bound tab: console output captured since page load, plus window errors, failed resource " +
192
+ "loads, and unhandled promise rejections. Best for finding why a page interaction is broken. Returns the most recent messages.",
193
+ inputSchema: {
194
+ ...OBJECT_SCHEMA_BASE,
195
+ properties: {
196
+ level: {
197
+ anyOf: [
198
+ { type: "string", const: "all" },
199
+ { type: "string", const: "error" },
200
+ { type: "string", const: "warn" },
201
+ { type: "string", const: "log" },
202
+ { type: "string", const: "info" },
203
+ { type: "string", const: "debug" },
204
+ ],
205
+ description: 'Only messages at this level (default "all"); "error" includes window errors and unhandled rejections.',
206
+ },
207
+ limit: { type: "number", description: "Maximum messages to return, newest first (default 50, max 200)." },
208
+ since: { type: "number", description: "Only messages captured at or after this Unix timestamp (ms)." },
209
+ clear: { type: "boolean", description: "Clear the captured buffer after reading (default false)." },
210
+ frame: { ...FRAME_PROPERTY },
211
+ },
212
+ },
213
+ readOnly: true,
214
+ },
215
+ {
216
+ name: "browser_get_network",
217
+ description: "Read recent network requests made by the bound tab (XHR/fetch and resource loads, covering ALL frames of the tab) " +
218
+ "with URL, method, status, and duration. Best for spotting failed API calls (4xx/5xx), blocked requests, or slow endpoints.",
219
+ inputSchema: {
220
+ ...OBJECT_SCHEMA_BASE,
221
+ properties: {
222
+ filter: { type: "string", description: "Only requests whose URL contains this substring (case-insensitive)." },
223
+ method: { type: "string", description: 'Only requests with this HTTP method, e.g. "POST".' },
224
+ errorsOnly: {
225
+ type: "boolean",
226
+ description: "Only failed requests or responses with status >= 400 (default false).",
227
+ },
228
+ limit: { type: "number", description: "Maximum requests to return, newest first (default 50, max 200)." },
229
+ },
230
+ },
231
+ readOnly: true,
232
+ },
233
+ {
234
+ name: "browser_element_at",
235
+ description: "Find the topmost DOM element at viewport coordinates in the bound tab and return its summary plus a stable ref " +
236
+ "usable with browser_click and browser_type. Use when an element is visible in a screenshot but not easy to select " +
237
+ "by name, or to verify what is under a point.",
238
+ inputSchema: {
239
+ ...OBJECT_SCHEMA_BASE,
240
+ properties: {
241
+ x: { type: "number", description: "X coordinate in CSS pixels from the viewport's left edge." },
242
+ y: { type: "number", description: "Y coordinate in CSS pixels from the viewport's top edge." },
243
+ frame: { ...FRAME_PROPERTY },
244
+ },
245
+ required: ["x", "y"],
246
+ },
247
+ readOnly: true,
248
+ },
249
+ {
250
+ name: "browser_navigate",
251
+ description: "Navigate the bound tab to an absolute http(s) or file URL and await the tab to be ready: it resolves only " +
252
+ "after the document finishes loading (status 'complete'), so the next tool (evaluate/DOM) sees a settled page. " +
253
+ "Element refs become stale after navigation; call browser_get_dom again afterwards.",
254
+ inputSchema: {
255
+ ...OBJECT_SCHEMA_BASE,
256
+ properties: {
257
+ url: { type: "string", description: 'Absolute URL to navigate to, e.g. "http://localhost:5173/login".' },
258
+ timeoutMs: {
259
+ type: "number",
260
+ description: "Max milliseconds to wait for the load to settle (default 30000, cap 120000).",
261
+ },
262
+ },
263
+ required: ["url"],
264
+ },
265
+ readOnly: false,
266
+ },
267
+ {
268
+ name: "browser_download",
269
+ description: "Download a file (image, video, or any resource) from an absolute http(s) URL using the browser's own network " +
270
+ "state: the request is issued with the user's cookies for the target origin, so authenticated resources that a " +
271
+ "shell curl cannot reach download correctly. Returns the content base64-encoded with its name, MIME type, and " +
272
+ "size; the bound tab is only used as the Referer and is not navigated. Files larger than maxBytes are rejected " +
273
+ "(BROWSER_DOWNLOAD_TOO_LARGE), never truncated.",
274
+ inputSchema: {
275
+ ...OBJECT_SCHEMA_BASE,
276
+ properties: {
277
+ url: { type: "string", description: 'Absolute http(s) URL to download, e.g. the src of an image on the current page.' },
278
+ maxBytes: { type: "number", description: "Maximum bytes to download (default 10485760, cap 52428800). Larger files are rejected, not truncated." },
279
+ },
280
+ required: ["url"],
281
+ },
282
+ readOnly: true,
283
+ },
284
+ // ---------------------------------------------------------------------
285
+ // REPL interaction primitives (BROWSER-USE-REPL-PLAN.md Phase 2).
286
+ // Atomic content-script operations behind the javascript tool's page.*
287
+ // primitives; the REPL is their only v1 consumer.
288
+ // ---------------------------------------------------------------------
289
+ {
290
+ name: "browser_click_at",
291
+ description: "Click at viewport coordinates in the bound tab: elementFromPoint + focus + click in ONE atomic run (an overlay " +
292
+ "that appears between inspect and click still gets the click). Returns what was hit, with a stable ref.",
293
+ inputSchema: {
294
+ ...OBJECT_SCHEMA_BASE,
295
+ properties: {
296
+ x: { type: "number", description: "X coordinate in CSS pixels from the viewport's left edge." },
297
+ y: { type: "number", description: "Y coordinate in CSS pixels from the viewport's top edge." },
298
+ frame: { ...FRAME_PROPERTY },
299
+ },
300
+ required: ["x", "y"],
301
+ },
302
+ readOnly: false,
303
+ },
304
+ {
305
+ name: "browser_focus",
306
+ description: "Focus an element by ref (from browser_get_dom / the a11y tree) in the bound tab.",
307
+ inputSchema: {
308
+ ...OBJECT_SCHEMA_BASE,
309
+ properties: {
310
+ ref: { type: "string", description: "Element reference, e.g. el-183." },
311
+ frame: { ...FRAME_PROPERTY },
312
+ },
313
+ required: ["ref"],
314
+ },
315
+ readOnly: false,
316
+ },
317
+ {
318
+ name: "browser_scroll",
319
+ description: "Scroll an element by ref into view (centered) in the bound tab.",
320
+ inputSchema: {
321
+ ...OBJECT_SCHEMA_BASE,
322
+ properties: {
323
+ ref: { type: "string", description: "Element reference, e.g. el-183." },
324
+ frame: { ...FRAME_PROPERTY },
325
+ },
326
+ required: ["ref"],
327
+ },
328
+ readOnly: false,
329
+ },
330
+ {
331
+ name: "browser_type_focused",
332
+ description: "Type text into the currently focused element of the bound tab (no ref needed) — the same proven typing path as " +
333
+ "browser_type (value-setter + input/change events, insertText fallback).",
334
+ inputSchema: {
335
+ ...OBJECT_SCHEMA_BASE,
336
+ properties: {
337
+ text: { type: "string", description: "Text to type into the focused element." },
338
+ frame: { ...FRAME_PROPERTY },
339
+ },
340
+ required: ["text"],
341
+ },
342
+ readOnly: false,
343
+ },
344
+ {
345
+ name: "browser_open_tab",
346
+ description: "Open a new tab (REPL-owned) and bind the session to it — works even when the session has no bound tab yet " +
347
+ "(create + bind in one step; this is how an agent acquires its first tab). Awaits the tab to be ready: it " +
348
+ "resolves only after the document finishes loading, so the next tool sees a settled page. The previously bound " +
349
+ "tab stays open and is restored when the REPL tab is closed or the session unbinds. REPL-owned tabs are closed " +
350
+ "automatically at session unbind.",
351
+ inputSchema: {
352
+ ...OBJECT_SCHEMA_BASE,
353
+ properties: {
354
+ url: { type: "string", description: 'URL for the new tab (default about:blank), e.g. "https://example.com".' },
355
+ timeoutMs: {
356
+ type: "number",
357
+ description: "Max milliseconds to wait for the load to settle (default 30000, cap 120000).",
358
+ },
359
+ },
360
+ required: ["url"],
361
+ },
362
+ readOnly: false,
363
+ },
364
+ {
365
+ name: "browser_close_tab",
366
+ description: "Close a REPL-owned tab (one opened via browser_open_tab). Closing the currently bound REPL tab restores the " +
367
+ "session's previous (user-bound) tab. Non-REPL tabs are rejected — unbind in the sidebar instead.",
368
+ inputSchema: {
369
+ ...OBJECT_SCHEMA_BASE,
370
+ properties: {
371
+ tabId: { type: "number", description: "Firefox tab id (from browser_list_tabs / browser_open_tab)." },
372
+ },
373
+ required: ["tabId"],
374
+ },
375
+ readOnly: false,
376
+ },
377
+ {
378
+ name: "browser_list_tabs",
379
+ description: "List all open tabs of the browser: {tabs: [{id, url, title, bound}]} — bound marks the session's current tab. " +
380
+ "Works without a bound tab; use it to find a tab id for browser_bind_tab.",
381
+ inputSchema: { ...OBJECT_SCHEMA_BASE, properties: {} },
382
+ readOnly: true,
383
+ },
384
+ {
385
+ name: "browser_bind_tab",
386
+ description: "Bind an existing tab (from browser_list_tabs) to this session — works even when the session has no bound tab. " +
387
+ "Replaces the session's current binding and releases the tab from any other session bound to it.",
388
+ inputSchema: {
389
+ ...OBJECT_SCHEMA_BASE,
390
+ properties: {
391
+ tabId: { type: "number", description: "Firefox tab id (from browser_list_tabs)." },
392
+ },
393
+ required: ["tabId"],
394
+ },
395
+ readOnly: false,
396
+ },
397
+ {
398
+ name: "browser_unbind_tab",
399
+ description: "Unbind this session from its tab — no user tab is closed, but the session's own REPL-owned tabs are reaped. " +
400
+ "Idempotent; works without a bound tab.",
401
+ inputSchema: { ...OBJECT_SCHEMA_BASE, properties: {} },
402
+ readOnly: false,
403
+ },
404
+ ];
405
+ const TOOL_BY_NAME = new Map(BROWSER_TOOLS.map((t) => [t.name, t]));
406
+ export function getBrowserTool(name) {
407
+ return TOOL_BY_NAME.get(name);
408
+ }
409
+ export function isBrowserTool(name) {
410
+ return TOOL_BY_NAME.has(name);
411
+ }
412
+ export function isMutatingBrowserTool(name) {
413
+ const tool = TOOL_BY_NAME.get(name);
414
+ return tool !== undefined && !tool.readOnly;
415
+ }
416
+ export const BROWSER_TOOL_NAMES = BROWSER_TOOLS.map((t) => t.name);
417
+ // ---------------------------------------------------------------------------
418
+ // Host-side REPL tools (BROWSER-USE-REPL-PLAN.md, option C)
419
+ //
420
+ // These tools are EXECUTED BY THE NATIVE HOST, not by the add-on: the
421
+ // `javascript` tool runs a persistent V8 cell interpreter (one child process
422
+ // per session) whose `page.*`/`tabs.*` primitives execute the regular browser
423
+ // tools against the session's current tab over the same transports. They are
424
+ // kept in a separate export so the add-on's MCP surface does not advertise a
425
+ // tool it cannot execute.
426
+ // ---------------------------------------------------------------------------
427
+ export const REPL_TOOLS = [
428
+ {
429
+ name: "javascript",
430
+ description: "Drive the real Firefox tab bound to this session with JavaScript — use this tool (not shell commands) for " +
431
+ "multi-step browser work. If the session has no bound tab yet, every primitive fails with BROWSER_NOT_BOUND — " +
432
+ "call the pi_open_tab control tool (create + bind a new tab) or pi_bind_tab first. " +
433
+ "Work in a loop: OBSERVE (snapshot/screenshot/evaluate) -> ACT (goto/click/type, one " +
434
+ "transaction per cell) -> VERIFY (re-snapshot; element refs go stale after navigation) -> PERSIST (checkpoint " +
435
+ "between steps of longer tasks). " +
436
+ "State (variables, helpers) persists across calls; top-level await is supported; the last expression is printed. " +
437
+ "Primitives: page.goto(url), page.info(), page.evaluate(fn|expr, arg?), page.waitFor(fn, arg?, {timeoutMs?}), " +
438
+ "page.snapshot({maxNodes?,maxDepth?,format?:\"tree\"|\"flat\"}) -> {url,title,tree:{role,name,children[]}} (default, " +
439
+ "nested) or {nodes:[...]} with format:\"flat\" (legacy flat node list), " +
440
+ "page.snapshotVisible({maxNodes?,maxDepth?}) -> only nodes in the current viewport, " +
441
+ "page.snapshotDiff(before, after, {key?:\"content\"|\"structural\"}) -> {added,removed,changed,unchangedCount} (no extra browser call), " +
442
+ "page.click(ref), page.clickAt(x,y), " +
443
+ "page.type(ref,text), page.typeFocused(text), page.focus(ref), page.scroll(ref), page.close(), tabs.list(), tabs.open(url), " +
444
+ "tabs.get(targetId), screenshot(), snapshot(), artifact(name, data), checkpoint(name, value), reconnect(). " +
445
+ "Downloads: page.download(url, path?) saves a file (image/video/anything) into the task workspace using the " +
446
+ "browser's own cookies — authenticated resources that a shell curl cannot fetch; returns { path, bytes, mimeType }. " +
447
+ "Filesystem: fs (read, write, append, list, stat, exists, mkdir, rename, unlink, rm) — confined to this session's task workspace " +
448
+ "(the directory artifact()/checkpoint() write into, global `workspace` prints it); paths are relative to that root, " +
449
+ "absolute paths outside it and `..` escapes are rejected. " +
450
+ "Screenshots are user-facing evidence; text-only models must rely on page.snapshot()/page.evaluate(), not image contents. " +
451
+ "screenshot() may pause while the user answers its permission prompt (Allow once / Always / Deny); a denial " +
452
+ "rejects the call — rely on snapshot/evaluate instead. " +
453
+ "A cell that runs too long is killed and its state reset — after an abort inspect the page (snapshot/screenshot) " +
454
+ "before retrying any action (it may have partially happened).",
455
+ inputSchema: {
456
+ ...OBJECT_SCHEMA_BASE,
457
+ properties: {
458
+ code: {
459
+ type: "string",
460
+ description: "JavaScript to run as one REPL cell. Top-level await allowed. Example: " +
461
+ "`const s = await page.snapshot(); await page.click(s.tree.children.find(n => n.name === 'Go')?.ref)`",
462
+ },
463
+ timeoutMs: {
464
+ type: "number",
465
+ description: "Kill the cell after this many milliseconds (default 30000, max 120000).",
466
+ },
467
+ },
468
+ required: ["code"],
469
+ },
470
+ readOnly: false,
471
+ },
472
+ ];
473
+ export const REPL_TOOL_NAMES = REPL_TOOLS.map((t) => t.name);
474
+ /** True for tools executed by the host REPL (never routed to the add-on). */
475
+ export function isReplTool(name) {
476
+ return REPL_TOOL_NAMES.includes(name);
477
+ }
478
+ //# sourceMappingURL=browser-tools.js.map
@@ -0,0 +1,123 @@
1
+ /**
2
+ * External MCP callers (openspec change `external-mcp-callers`).
3
+ *
4
+ * Any stdio MCP client (Claude Code, Codex, Cursor, a separate pi, ...) can
5
+ * reach the broker's MCP server through the stdio bridge. Each such
6
+ * connection runs as its own *caller session*: its own approvals, its own
7
+ * REPL state, routed to whichever connected app serves the tool, and with no
8
+ * add-on chat session needed.
9
+ *
10
+ * - The bridge names the caller with the `pi-browser/caller` notification
11
+ * (the MCP client's `clientInfo` from `initialize`, plus process ids).
12
+ * Direct socket clients are named from their own `initialize`.
13
+ * - Processes the host itself spawned (pi subagents and their MCP servers)
14
+ * inherit `PI_BROWSER_HOST_CHILD=<broker instance id>`; when the value the
15
+ * bridge reports matches the running broker, the call keeps the old
16
+ * "most recently active add-on session" routing.
17
+ * - Permission prompts for caller sessions carry `_meta.piBrowser.caller`.
18
+ * Add-ons show those in an approval window instead of the sidebar/Space.
19
+ * - Before a caller's first tool call in an app, the user approves the
20
+ * caller for that app (stored per app + caller name). A global
21
+ * external-access switch (on by default) refuses every caller call.
22
+ */
23
+ import type { AgentApplication } from "./integration.js";
24
+ /** MCP notification the stdio bridge sends to the broker after each connect. */
25
+ export declare const MCP_CALLER_NOTIFICATION = "pi-browser/caller";
26
+ /** Environment variable the broker sets for every process it spawns. */
27
+ export declare const HOST_CHILD_ENV = "PI_BROWSER_HOST_CHILD";
28
+ /** Caller name used when a client never identified itself. */
29
+ export declare const UNKNOWN_CALLER_NAME = "unknown MCP client";
30
+ /** Params of the `pi-browser/caller` notification. */
31
+ export interface CallerInfo {
32
+ /** The MCP client's self-reported name (`clientInfo.name`). Not authenticated. */
33
+ name: string;
34
+ /** The MCP client's self-reported version. */
35
+ version?: string;
36
+ /** Process id of the stdio bridge. */
37
+ pid?: number;
38
+ /** Parent process id of the stdio bridge (the MCP client process). */
39
+ ppid?: number;
40
+ /** Value of PI_BROWSER_HOST_CHILD the bridge inherited, if any. */
41
+ hostChild?: string;
42
+ /**
43
+ * Value of PI_BROWSER_PARENT_SESSION: the sidebar session an external ACP
44
+ * agent's bridge belongs to (sidebar-acp-agents). Honoured only together
45
+ * with a matching `hostChild`.
46
+ */
47
+ parentSession?: string;
48
+ }
49
+ /** `_meta.piBrowser.caller` on a session/request_permission for a caller session. */
50
+ export interface PermissionCallerMeta {
51
+ name: string;
52
+ version?: string;
53
+ }
54
+ /**
55
+ * `_meta.piBrowser` of a session/request_permission. `tool` is set for tool
56
+ * prompts; `callerApproval` marks the one-time "allow <caller> to use <App>
57
+ * tools?" prompt (then `tool` is absent and `triggerTool` names the tool call
58
+ * that needs it).
59
+ */
60
+ export interface PermissionRequestPiBrowserMeta {
61
+ tool?: string;
62
+ triggerTool?: string;
63
+ caller?: PermissionCallerMeta;
64
+ callerApproval?: boolean;
65
+ /** The application the caller approval is for. */
66
+ application?: AgentApplication;
67
+ /**
68
+ * Set on an external ACP agent's own permission request, relayed from the
69
+ * agent (sidebar-acp-agents): shown in the session's own UI, labelled with
70
+ * the agent's name, never remembered by the add-on.
71
+ */
72
+ agent?: {
73
+ id: string;
74
+ name: string;
75
+ };
76
+ }
77
+ /**
78
+ * Host → client notification: a permission request the client may still be
79
+ * showing no longer needs an answer (it timed out, or its caller session
80
+ * ended). The approval window drops it. Older add-ons ignore it.
81
+ */
82
+ export declare const PERMISSION_WITHDRAWN_METHOD = "x-pi-browser/permission_withdrawn";
83
+ export interface PermissionWithdrawnParams {
84
+ sessionId: string;
85
+ toolCallId: string;
86
+ reason: "timeout" | "session_closed" | "cancelled";
87
+ }
88
+ /**
89
+ * Host → every client: a caller session ended (its MCP connection closed).
90
+ * Firefox releases the session's tab binding and closes its REPL-owned
91
+ * tabs. Older add-ons ignore it.
92
+ */
93
+ export declare const SESSION_ENDED_METHOD = "x-pi-browser/session_ended";
94
+ export interface SessionEndedParams {
95
+ sessionId: string;
96
+ }
97
+ /** Caller session ids are `mcp:<uuid>`. */
98
+ export declare function isCallerSessionId(sessionId: string): boolean;
99
+ /** A caller's remembered decision for one app. */
100
+ export type CallerPermissionState = "allow" | "deny";
101
+ /** Identifies one remembered caller decision. */
102
+ export interface CallerRef {
103
+ application: AgentApplication;
104
+ name: string;
105
+ }
106
+ /** One remembered caller decision (x-pi-browser/permissions `callers`). */
107
+ export interface CallerPermissionEntry extends CallerRef {
108
+ state: CallerPermissionState;
109
+ }
110
+ /** Option ids of the caller-approval prompt (same ids as tool prompts). */
111
+ export declare const CALLER_ALLOW_ONCE = "allow_once";
112
+ export declare const CALLER_ALLOW_ALWAYS = "allow_always";
113
+ export declare const CALLER_DENY = "reject_once";
114
+ /** Human name of an app in caller prompts ("Firefox", "Thunderbird"). */
115
+ export declare function applicationShortName(app: AgentApplication): string;
116
+ /**
117
+ * Normalize a self-reported caller name: trimmed, control characters
118
+ * removed, at most 64 characters; empty becomes UNKNOWN_CALLER_NAME.
119
+ */
120
+ export declare function normalizeCallerName(raw: unknown): string;
121
+ /** Parse `pi-browser/caller` params (or `initialize` clientInfo) defensively. */
122
+ export declare function parseCallerInfo(raw: unknown): CallerInfo;
123
+ //# sourceMappingURL=callers.d.ts.map
@@ -0,0 +1,58 @@
1
+ /** MCP notification the stdio bridge sends to the broker after each connect. */
2
+ export const MCP_CALLER_NOTIFICATION = "pi-browser/caller";
3
+ /** Environment variable the broker sets for every process it spawns. */
4
+ export const HOST_CHILD_ENV = "PI_BROWSER_HOST_CHILD";
5
+ /** Caller name used when a client never identified itself. */
6
+ export const UNKNOWN_CALLER_NAME = "unknown MCP client";
7
+ /**
8
+ * Host → client notification: a permission request the client may still be
9
+ * showing no longer needs an answer (it timed out, or its caller session
10
+ * ended). The approval window drops it. Older add-ons ignore it.
11
+ */
12
+ export const PERMISSION_WITHDRAWN_METHOD = "x-pi-browser/permission_withdrawn";
13
+ /**
14
+ * Host → every client: a caller session ended (its MCP connection closed).
15
+ * Firefox releases the session's tab binding and closes its REPL-owned
16
+ * tabs. Older add-ons ignore it.
17
+ */
18
+ export const SESSION_ENDED_METHOD = "x-pi-browser/session_ended";
19
+ /** Caller session ids are `mcp:<uuid>`. */
20
+ export function isCallerSessionId(sessionId) {
21
+ return sessionId.startsWith("mcp:");
22
+ }
23
+ /** Option ids of the caller-approval prompt (same ids as tool prompts). */
24
+ export const CALLER_ALLOW_ONCE = "allow_once";
25
+ export const CALLER_ALLOW_ALWAYS = "allow_always";
26
+ export const CALLER_DENY = "reject_once";
27
+ /** Human name of an app in caller prompts ("Firefox", "Thunderbird"). */
28
+ export function applicationShortName(app) {
29
+ return app === "thunderbird" ? "Thunderbird" : "Firefox";
30
+ }
31
+ /**
32
+ * Normalize a self-reported caller name: trimmed, control characters
33
+ * removed, at most 64 characters; empty becomes UNKNOWN_CALLER_NAME.
34
+ */
35
+ export function normalizeCallerName(raw) {
36
+ if (typeof raw !== "string")
37
+ return UNKNOWN_CALLER_NAME;
38
+ // eslint-disable-next-line no-control-regex
39
+ const cleaned = raw.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 64);
40
+ return cleaned || UNKNOWN_CALLER_NAME;
41
+ }
42
+ /** Parse `pi-browser/caller` params (or `initialize` clientInfo) defensively. */
43
+ export function parseCallerInfo(raw) {
44
+ const r = typeof raw === "object" && raw !== null ? raw : {};
45
+ const out = { name: normalizeCallerName(r.name) };
46
+ if (typeof r.version === "string" && r.version.trim())
47
+ out.version = r.version.trim().slice(0, 32);
48
+ if (typeof r.pid === "number" && Number.isInteger(r.pid))
49
+ out.pid = r.pid;
50
+ if (typeof r.ppid === "number" && Number.isInteger(r.ppid))
51
+ out.ppid = r.ppid;
52
+ if (typeof r.hostChild === "string" && r.hostChild)
53
+ out.hostChild = r.hostChild;
54
+ if (typeof r.parentSession === "string" && r.parentSession && r.parentSession.length <= 200)
55
+ out.parentSession = r.parentSession;
56
+ return out;
57
+ }
58
+ //# sourceMappingURL=callers.js.map