turno-browser 0.3.0 → 0.5.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 (131) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +95 -123
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +117 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +600 -0
  7. package/dist/api.d.ts +90 -2
  8. package/dist/api.js +41 -4
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/background-state.d.ts +54 -0
  12. package/dist/background-state.js +97 -0
  13. package/dist/background.d.ts +69 -0
  14. package/dist/background.js +458 -0
  15. package/dist/batch.d.ts +5 -0
  16. package/dist/batch.js +3 -3
  17. package/dist/bin/mcp.js +103 -6
  18. package/dist/captcha.d.ts +77 -0
  19. package/dist/captcha.js +334 -0
  20. package/dist/cdp-relay.d.ts +20 -0
  21. package/dist/cdp-relay.js +101 -0
  22. package/dist/chrome-features.d.ts +23 -0
  23. package/dist/chrome-features.js +44 -0
  24. package/dist/cli/background.d.ts +11 -0
  25. package/dist/cli/background.js +132 -0
  26. package/dist/cli/commands.d.ts +16 -0
  27. package/dist/cli/commands.js +515 -0
  28. package/dist/cli/context.d.ts +75 -0
  29. package/dist/cli/context.js +44 -0
  30. package/dist/cli/do-background.d.ts +27 -0
  31. package/dist/cli/do-background.js +212 -0
  32. package/dist/cli/do.d.ts +85 -0
  33. package/dist/cli/do.js +558 -0
  34. package/dist/cli/flows.d.ts +28 -0
  35. package/dist/cli/flows.js +303 -0
  36. package/dist/cli/identity.d.ts +37 -0
  37. package/dist/cli/identity.js +906 -0
  38. package/dist/cli/live.d.ts +7 -0
  39. package/dist/cli/live.js +99 -0
  40. package/dist/cli/main.d.ts +16 -0
  41. package/dist/cli/main.js +171 -0
  42. package/dist/cli/secret.d.ts +4 -0
  43. package/dist/cli/secret.js +151 -0
  44. package/dist/cli/session.d.ts +6 -0
  45. package/dist/cli/session.js +106 -0
  46. package/dist/cli/setup.d.ts +7 -0
  47. package/dist/cli/setup.js +180 -0
  48. package/dist/cli/vault.d.ts +5 -0
  49. package/dist/cli/vault.js +192 -0
  50. package/dist/client.d.ts +82 -0
  51. package/dist/client.js +303 -0
  52. package/dist/diagnose.d.ts +7 -0
  53. package/dist/diagnose.js +61 -6
  54. package/dist/doctor.d.ts +37 -3
  55. package/dist/doctor.js +264 -6
  56. package/dist/engine-attach.d.ts +27 -0
  57. package/dist/engine-attach.js +165 -0
  58. package/dist/engine-camoufox.d.ts +32 -0
  59. package/dist/engine-camoufox.js +271 -0
  60. package/dist/engine-lightpanda.d.ts +72 -0
  61. package/dist/engine-lightpanda.js +293 -0
  62. package/dist/engine.d.ts +63 -11
  63. package/dist/engine.js +106 -29
  64. package/dist/flows.d.ts +127 -0
  65. package/dist/flows.js +294 -0
  66. package/dist/governor.d.ts +42 -7
  67. package/dist/governor.js +82 -32
  68. package/dist/health.js +2 -1
  69. package/dist/host.d.ts +38 -2
  70. package/dist/host.js +689 -52
  71. package/dist/human-input.d.ts +84 -0
  72. package/dist/human-input.js +448 -0
  73. package/dist/humanize.d.ts +123 -0
  74. package/dist/humanize.js +241 -0
  75. package/dist/identities.js +4 -1
  76. package/dist/idle-timer.d.ts +12 -0
  77. package/dist/idle-timer.js +25 -0
  78. package/dist/index.d.ts +13 -4
  79. package/dist/index.js +7 -1
  80. package/dist/lifecycle.d.ts +11 -1
  81. package/dist/lifecycle.js +11 -2
  82. package/dist/live-client.d.ts +22 -0
  83. package/dist/live-client.js +95 -0
  84. package/dist/live-page.d.ts +4 -0
  85. package/dist/live-page.js +144 -0
  86. package/dist/live-server.d.ts +173 -0
  87. package/dist/live-server.js +643 -0
  88. package/dist/live.d.ts +120 -0
  89. package/dist/live.js +204 -0
  90. package/dist/login-tool.d.ts +13 -0
  91. package/dist/login-tool.js +8 -3
  92. package/dist/login.d.ts +4 -1
  93. package/dist/login.js +12 -2
  94. package/dist/names.d.ts +28 -0
  95. package/dist/names.js +25 -0
  96. package/dist/network-chrome.d.ts +74 -0
  97. package/dist/network-chrome.js +178 -0
  98. package/dist/network.d.ts +125 -0
  99. package/dist/network.js +264 -0
  100. package/dist/opt-in-settings.d.ts +69 -0
  101. package/dist/opt-in-settings.js +152 -0
  102. package/dist/recorder.d.ts +88 -0
  103. package/dist/recorder.js +538 -0
  104. package/dist/recordings.d.ts +116 -0
  105. package/dist/recordings.js +474 -0
  106. package/dist/redact.d.ts +7 -0
  107. package/dist/redact.js +18 -0
  108. package/dist/replay.d.ts +20 -0
  109. package/dist/replay.js +383 -0
  110. package/dist/reputation.d.ts +24 -2
  111. package/dist/reputation.js +63 -17
  112. package/dist/runtime-lock.js +3 -2
  113. package/dist/session-export.js +1 -1
  114. package/dist/session.d.ts +10 -2
  115. package/dist/session.js +10 -2
  116. package/dist/settings.d.ts +104 -2
  117. package/dist/settings.js +204 -6
  118. package/dist/sharing.d.ts +96 -0
  119. package/dist/sharing.js +269 -0
  120. package/dist/snippet.d.ts +8 -2
  121. package/dist/snippet.js +10 -4
  122. package/dist/tab-locks.d.ts +63 -0
  123. package/dist/tab-locks.js +179 -0
  124. package/dist/tools.d.ts +38 -0
  125. package/dist/tools.js +20 -1
  126. package/dist/tuning.d.ts +14 -0
  127. package/dist/tuning.js +9 -0
  128. package/dist/upstream.d.ts +11 -0
  129. package/dist/vault.js +5 -4
  130. package/npm-shrinkwrap.json +6 -5
  131. package/package.json +13 -7
package/dist/host.js CHANGED
@@ -5,17 +5,26 @@ import { fileURLToPath } from "node:url";
5
5
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
6
6
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
7
7
  import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
8
- import { explainFailure } from "./diagnose.js";
9
- import { createUpstreamEngine, selectEngine } from "./engine.js";
8
+ import { refuseWhileBackground } from "./background-state.js";
9
+ import { coveredBeforeCall, explainFailure } from "./diagnose.js";
10
+ import { createEngine, engineChoice, } from "./engine.js";
10
11
  import { TabGovernor } from "./governor.js";
11
12
  import { NEEDS_AUTH_HOLD_MS, healthDue, needsAuthMessage, readHealth, runHealthCheck, writeHealth, } from "./health.js";
13
+ import { HumanInput, adaptiveSites, humanizeTools } from "./human-input.js";
12
14
  import { identityStateDir } from "./ids.js";
15
+ import { idleMs } from "./idle-timer.js";
16
+ import { describeChanges, resolveLive, resumeNote, timeoutMessage, viewRefusal } from "./live.js";
17
+ import { LiveServer } from "./live-server.js";
18
+ import { FlowRecorder, secretValues } from "./recorder.js";
19
+ import { Recording, tracesTmpDir } from "./recordings.js";
13
20
  import { Redactor, SCRIPT_TOOLS, VaultGuard } from "./redact.js";
14
21
  import { recordChallenge, watchChallenges } from "./reputation.js";
15
22
  import { installResources } from "./resources.js";
16
- import { sessionFromMeta } from "./session.js";
23
+ import { SESSION_CAPABILITY, SESSION_ENDED_METHOD, SESSION_META_KEY, sessionFromMeta } from "./session.js";
24
+ import { TabSharing, viewConfig } from "./sharing.js";
25
+ import { DEFAULT_TAB_LOCKS, DIRECT_SESSION } from "./tab-locks.js";
17
26
  import { readIdentitySettings } from "./settings.js";
18
- import { TURNO_TOOLS, checkTurnoTools, parseArguments } from "./tools.js";
27
+ import { TURNO_TOOLS, checkTurnoTools, optInTools, parseArguments, } from "./tools.js";
19
28
  import { resolveTuning } from "./tuning.js";
20
29
  import { vaultHasSites } from "./vault.js";
21
30
  import { backendContext, toMcpTool, upstream, } from "./upstream.js";
@@ -38,7 +47,14 @@ import { backendContext, toMcpTool, upstream, } from "./upstream.js";
38
47
  * added to the result; a click or type that fails because of the element gets an error that
39
48
  * says what is in the way (`diagnose.ts`);
40
49
  * - gives each browser its own copy of the config, so the identity's `settle` and a batch's
41
- * snapshot-free steps change only that session.
50
+ * snapshot-free steps change only that session;
51
+ * - with `"sharing": "tabs"`, serves several agent sessions (mcpd's `_meta["io.turno/session"]`)
52
+ * in that one browser, each with its own backend, current tab and tab locks (`sharing.ts`);
53
+ * - lists the opt-in tools of the identity (natural language actions, captcha solving) only when
54
+ * identity.json turns them on when the server starts, and hands those tools MCP sampling,
55
+ * routed to the calling session, when the client offers it;
56
+ * - with the live view on (identity.json `live`, `--live`), holds every browser call while the
57
+ * user has paused the agent, and tells the held call what changed (`live.ts`, `live-server.ts`).
42
58
  *
43
59
  * stdio, the transport mcpd and every agent use, is served by turno with the MCP SDK.
44
60
  * `--port` keeps upstream's HTTP server (Host check, streamable HTTP and SSE) serving the
@@ -70,12 +86,12 @@ export function mergeTextParts(result) {
70
86
  * Adds what the tab governor did to a stock tool's result: parked tabs are marked in a tab list,
71
87
  * and closed or parked tabs are listed in a last section (under `turno.tabs` in JSON).
72
88
  */
73
- function withGovernor(result, governor, json) {
74
- const notes = governor.takeNotes();
89
+ function withGovernor(result, governor, json, owner, view) {
90
+ const notes = governor.takeNotes(owner);
75
91
  const first = result.content[0];
76
92
  if (!first || first.type !== "text")
77
93
  return result;
78
- let text = governor.annotateTabs(first.text);
94
+ let text = governor.annotateTabs(first.text, view);
79
95
  if (notes.length) {
80
96
  if (json) {
81
97
  try {
@@ -91,6 +107,30 @@ function withGovernor(result, governor, json) {
91
107
  }
92
108
  return { ...result, content: [{ ...first, text }, ...result.content.slice(1)] };
93
109
  }
110
+ /** What a step of a batch, a replay or an act run meets once the user pauses the agent. */
111
+ const PAUSED_STEP = "The user paused the browser";
112
+ /** A held call's result with the resume note first (under `turno.live` in JSON). */
113
+ function withNote(result, note, json) {
114
+ const first = result.content[0];
115
+ if (!first || first.type !== "text")
116
+ return { ...result, content: [{ type: "text", text: note }, ...result.content] };
117
+ const text = first.text;
118
+ if (json) {
119
+ try {
120
+ const payload = JSON.parse(text);
121
+ const turno = (payload.turno ?? {});
122
+ const out = JSON.stringify({ ...payload, turno: { ...turno, live: note } }, null, 2);
123
+ return { ...result, content: [{ ...first, text: out }, ...result.content.slice(1)] };
124
+ }
125
+ catch {
126
+ /* not JSON after all: put the note first */
127
+ }
128
+ }
129
+ return { ...result, content: [{ ...first, text: `${note}\n\n${text}` }, ...result.content.slice(1)] };
130
+ }
131
+ function errorResultOf(text) {
132
+ return { content: [{ type: "text", text }], isError: true };
133
+ }
94
134
  function errorResult(message, json) {
95
135
  return {
96
136
  content: [
@@ -154,6 +194,10 @@ class SessionBackend extends EventEmitter {
154
194
  live;
155
195
  launched;
156
196
  disposed = false;
197
+ /** identity.json `record` as of the last launch. */
198
+ recordSettings;
199
+ /** Each client session's flow recorder: a recording belongs to the session that started it. */
200
+ recorders = new Map();
157
201
  constructor(host, title) {
158
202
  super();
159
203
  this.host = host;
@@ -162,6 +206,19 @@ class SessionBackend extends EventEmitter {
162
206
  async initialize(clientInfo) {
163
207
  this.clientInfo = clientInfo;
164
208
  }
209
+ /** The flow recorder of a client session (identities only). */
210
+ recorderFor(session) {
211
+ const identity = this.host.identity;
212
+ if (!identity)
213
+ return undefined;
214
+ const key = session ?? DIRECT_SESSION;
215
+ let recorder = this.recorders.get(key);
216
+ if (!recorder) {
217
+ recorder = new FlowRecorder(identity, this.host.redactor, () => this.recordSettings?.flows === true);
218
+ this.recorders.set(key, recorder);
219
+ }
220
+ return recorder;
221
+ }
165
222
  dynamicTools() {
166
223
  return this.live?.dynamicTools() ?? [];
167
224
  }
@@ -186,20 +243,52 @@ class SessionBackend extends EventEmitter {
186
243
  const clientInfo = this.info();
187
244
  const { config, cliOptions, stock, engine, identity } = this.host;
188
245
  const promise = (async () => {
189
- if (identity)
246
+ if (identity) {
247
+ // While the identity's background server runs, it alone launches its browser.
248
+ refuseWhileBackground(identity);
190
249
  refuseWhileNeedsAuth(identity);
191
- const tuning = resolveTuning(identity ? readIdentitySettings(identity.id, identity.env) : undefined, this.host.tuning);
250
+ }
251
+ const settings = identity ? readIdentitySettings(identity.id, identity.env) : undefined;
252
+ const tuning = resolveTuning(settings, this.host.tuning);
253
+ this.recordSettings = settings?.record;
254
+ const noTraces = config.capabilities?.includes("devtools")
255
+ ? "the devtools capability records traces of its own"
256
+ : undefined;
257
+ const traces = identity && settings?.record?.traces && !noTraces;
258
+ const title = this.title(clientInfo);
192
259
  const launched = await engine.launch({
193
- config,
260
+ // Playwright writes a trace's raw files to tracesDir as it records: an identity's
261
+ // recording keeps them in its own folder instead of the workspace (`recordings.ts`).
262
+ config: traces
263
+ ? {
264
+ ...config,
265
+ browser: {
266
+ ...config.browser,
267
+ launchOptions: { ...config.browser.launchOptions, tracesDir: tracesTmpDir(identity.id, identity.env) },
268
+ },
269
+ }
270
+ : config,
194
271
  clientInfo,
195
272
  cliOptions,
196
- title: this.title(clientInfo),
273
+ title,
197
274
  tuning,
275
+ // Proxy credentials read at launch leave no tool result or saved trace unredacted.
276
+ secret: (value, label) => this.host.redactor.add(value, label),
198
277
  ...(identity ? { identity } : {}),
199
278
  });
200
- if (identity) {
279
+ // Human-like input (off by default): the input tools of this browser run on humanized tabs.
280
+ const input = tuning.humanize.level === "off"
281
+ ? undefined
282
+ : new HumanInput(tuning.humanize, {
283
+ ...(identity ? { persona: identity.id, challenged: adaptiveSites(identity.id, identity.env) } : {}),
284
+ });
285
+ // Read mode and attach mode never use the identity's Chrome profile, so the profile's
286
+ // health check, challenge log and resource rules do not apply to them. Camoufox keeps a
287
+ // profile of its own, so they do.
288
+ const profile = launched.engine !== "lightpanda" && launched.engine !== "attach";
289
+ if (identity && profile) {
201
290
  try {
202
- await afterIdentityLaunch(identity, launched);
291
+ await afterIdentityLaunch(identity, launched, (event) => input?.noteChallenge(event.site));
203
292
  }
204
293
  catch (error) {
205
294
  await launched.close().catch(() => { });
@@ -209,8 +298,13 @@ class SessionBackend extends EventEmitter {
209
298
  const { BrowserBackend } = upstream().tools;
210
299
  const isCurrent = () => this.current === promise;
211
300
  let governor;
301
+ let sharing;
302
+ let recording;
303
+ let unbindLive;
212
304
  const gone = () => {
305
+ unbindLive?.();
213
306
  governor?.dispose();
307
+ sharing?.dispose();
214
308
  if (isCurrent()) {
215
309
  this.current = undefined;
216
310
  this.live = undefined;
@@ -219,10 +313,13 @@ class SessionBackend extends EventEmitter {
219
313
  };
220
314
  const sessionConfig = configForSession(config, cliOptions, tuning);
221
315
  const idle = launched.idleTimer ? new CallIdleTimer(launched.idleTimer, () => launched.isOpen()) : undefined;
222
- const backend = new BrowserBackend(sessionConfig, launched.context, stock, {
316
+ // Every backend of this browser (each session's too, with "sharing": "tabs") runs these tools.
317
+ const tools = input ? humanizeTools(stock, input) : stock;
318
+ const backend = new BrowserBackend(sessionConfig, launched.context, tools, {
223
319
  ...(idle ? { idleTimer: idle } : {}),
224
320
  dispose: async () => {
225
321
  gone();
322
+ await recording?.close().catch(() => { });
226
323
  await launched.close();
227
324
  },
228
325
  });
@@ -230,22 +327,96 @@ class SessionBackend extends EventEmitter {
230
327
  await backend.initialize(clientInfo);
231
328
  // After upstream's own routes (--allowed-origins, --blocked-origins), so this one runs
232
329
  // first and hands every request it does not block or serve on to them.
233
- if (identity)
330
+ if (identity && profile)
234
331
  await installResources(launched.context, tuning.resources, join(identityStateDir(identity.id, identity.env), "resource-cache"));
332
+ // Never in read or attach mode: the engine refuses traces and screenshots there first.
333
+ const idleLimit = idleMs(sessionConfig);
334
+ if (identity && profile && settings?.record)
335
+ recording = await Recording.open({
336
+ identity,
337
+ settings: settings.record,
338
+ context: launched.context,
339
+ redactor: this.host.redactor,
340
+ guard: this.host.guard,
341
+ title,
342
+ ...(noTraces ? { noTraces } : {}),
343
+ ...(idleLimit ? { idleMs: idleLimit } : {}),
344
+ });
235
345
  }
236
346
  catch (error) {
237
347
  await launched.close();
238
348
  throw error;
239
349
  }
350
+ if (tuning.sharing === "tabs") {
351
+ const forViews = viewConfig(sessionConfig);
352
+ sharing = new TabSharing({
353
+ context: launched.context,
354
+ root: { backend, config: sessionConfig },
355
+ policy: { ...DEFAULT_TAB_LOCKS, ...tuning.tabLocks, ...this.host.tabLocks },
356
+ createView: async () => {
357
+ const config = viewConfig(forViews);
358
+ const view = new BrowserBackend(config, launched.context, tools, {});
359
+ await view.initialize(clientInfo);
360
+ return { backend: view, config };
361
+ },
362
+ });
363
+ }
364
+ const shared = sharing;
240
365
  governor = new TabGovernor(launched.context, tuning.tabs, {
241
366
  current: () => backendContext(backend)?.currentTab()?.page,
242
367
  tabs: () => backendContext(backend)
243
368
  ?.tabs()
244
369
  .map((t) => t.page) ?? [],
370
+ ...(shared
371
+ ? {
372
+ protected: () => shared.protectedPages(),
373
+ owner: (page) => shared.owner(page),
374
+ adopt: (page) => shared.adopt(page),
375
+ }
376
+ : {}),
377
+ ...(launched.userBrowser ? { ownedOnly: true, onOwn: (page) => launched.own?.(page) } : {}),
245
378
  });
246
379
  governor.start();
380
+ if (launched.userBrowser) {
381
+ // The user's browser: the agent starts in a tab of its own, so its first navigation
382
+ // never replaces one of the user's pages (upstream would pick the first open tab).
383
+ try {
384
+ const tab = await backendContext(backend)?.newTab();
385
+ if (tab)
386
+ governor.own(tab.page);
387
+ }
388
+ catch (error) {
389
+ governor.dispose();
390
+ await launched.close();
391
+ throw error;
392
+ }
393
+ }
394
+ if (this.host.live) {
395
+ const tabs = governor;
396
+ let endIdle;
397
+ unbindLive = this.host.live.bind({
398
+ context: launched.context,
399
+ engine: launched.engine,
400
+ userBrowser: launched.userBrowser === true,
401
+ ...(shared ? { owner: (page) => shared.owner(page) } : {}),
402
+ urlOf: (page) => tabs.parkedUrl(page) ?? page.url(),
403
+ // While the user has the browser, the idle limit does not close it, the tab governor
404
+ // parks and closes nothing (a popup the user opens stays), and no trace records it.
405
+ onPause: async () => {
406
+ tabs.beginCall();
407
+ endIdle = idle?.begin();
408
+ await recording?.pauseForUser();
409
+ },
410
+ onResume: () => {
411
+ endIdle?.();
412
+ endIdle = undefined;
413
+ tabs.endCall();
414
+ },
415
+ });
416
+ }
247
417
  backend.on("dynamictoolschange", () => this.emit("dynamictoolschange"));
248
418
  backend.once("disconnected", () => {
419
+ recording?.abandon();
249
420
  gone();
250
421
  void backend.dispose().catch(() => { });
251
422
  });
@@ -253,7 +424,17 @@ class SessionBackend extends EventEmitter {
253
424
  this.live = backend;
254
425
  this.launched = launched;
255
426
  }
256
- return { backend, config: sessionConfig, launched, governor, tuning, ...(idle ? { idle } : {}) };
427
+ return {
428
+ backend,
429
+ config: sessionConfig,
430
+ launched,
431
+ governor,
432
+ tuning,
433
+ ...(idle ? { idle } : {}),
434
+ ...(sharing ? { sharing } : {}),
435
+ ...(recording ? { recording } : {}),
436
+ ...(input ? { input } : {}),
437
+ };
257
438
  })();
258
439
  promise.catch(() => {
259
440
  if (this.current === promise)
@@ -266,15 +447,95 @@ class SessionBackend extends EventEmitter {
266
447
  * `session` is the client session mcpd put in the call's `_meta`. Only turno tools
267
448
  * see it; stock tools run exactly as before. Upstream's HTTP server (`--port`) never passes it.
268
449
  */
269
- async callTool(name, args, signal, session) {
450
+ async callTool(name, args, signal, session, sample) {
270
451
  // Every result and error of this server leaves through the redactor.
271
- return this.host.redactor.result(await this.callAny(name, args, signal, session));
452
+ return this.host.redactor.result(await this.callLive(name, args, signal, session, sample));
272
453
  }
273
- async callAny(name, args, signal, session) {
454
+ /** True when a call needs the browser, so a pause holds it. */
455
+ touchesBrowser(name) {
456
+ const tool = this.host.turno.get(name);
457
+ return tool ? tool.browser !== false : true;
458
+ }
459
+ /**
460
+ * A call through the live view's pause gate (`live.ts`): it runs at once unless the user
461
+ * paused the agent; then it waits, and on resume it runs, or returns an error with a fresh
462
+ * snapshot when the browser changed and the call does more than read.
463
+ */
464
+ async callLive(name, args, signal, session, sample) {
465
+ const live = this.host.live;
466
+ if (!live || !this.touchesBrowser(name))
467
+ return await this.callAny(name, args, signal, session, sample);
468
+ const json = !!args._meta?.json;
469
+ const key = session ?? DIRECT_SESSION;
470
+ const outcome = await live.gate.wait(live.waitMs, signal);
471
+ if (outcome.kind === "timeout")
472
+ return errorResult(timeoutMessage(this.host.identity?.id ?? "", name, outcome.pausedMs, outcome.by, live.waitMs), json);
473
+ if (outcome.kind === "aborted")
474
+ return errorResult(`${name} was cancelled while the user had the browser`, json);
475
+ const end = live.begin();
476
+ try {
477
+ if (outcome.kind === "open") {
478
+ const result = await this.callAny(name, args, signal, session, sample);
479
+ if (!live.paused)
480
+ return result;
481
+ return withNote(result, "### Paused by the user\nThe user paused this browser while this call ran. Your next call waits until they resume.", json);
482
+ }
483
+ const beforePage = live.lastPage(key);
484
+ const afterPage = beforePage ? await this.currentPageOf(key) : undefined;
485
+ const after = await live.tabStates();
486
+ const { changed, lines } = describeChanges(outcome.before, after, beforePage ? live.idOf(beforePage) : undefined, afterPage ? live.idOf(afterPage) : undefined, outcome.inputs);
487
+ const note = {
488
+ pausedMs: outcome.pausedMs,
489
+ by: outcome.by,
490
+ lines,
491
+ tool: name,
492
+ recordingFlow: this.recorderFor(session)?.recording !== undefined,
493
+ };
494
+ if (!changed || this.readsOnly(name)) {
495
+ const result = await this.callAny(name, args, signal, session, sample);
496
+ return withNote(result, resumeNote({ ...note, ran: true }), json);
497
+ }
498
+ // A call that was not run is an error, so a client that reads only the outcome (a script,
499
+ // turno browser do) does not take it for done.
500
+ const notRun = `### Error\n${name} was not run: the user changed the browser while you waited (below).`;
501
+ if (!this.launched?.isOpen()) {
502
+ const text = `${notRun}\n\n${resumeNote({ ...note, ran: false, noBrowser: true })}`;
503
+ return errorResultOf(json ? JSON.stringify({ isError: true, error: text }, null, 2) : text);
504
+ }
505
+ const snapshot = await this.callAny("browser_snapshot", {}, signal, session);
506
+ const noted = withNote(snapshot, resumeNote({ ...note, ran: false }), json);
507
+ return { ...(json ? noted : withNote(noted, notRun, false)), isError: true };
508
+ }
509
+ finally {
510
+ end();
511
+ }
512
+ }
513
+ /** True for a call that changes nothing on the page (a snapshot, the tab list, `browser_extract`). */
514
+ readsOnly(name) {
515
+ return (this.host.stockTypes.get(name) ?? this.host.turno.get(name)?.schema.type) === "readOnly";
516
+ }
517
+ /** The tab a session's backend calls current now, without starting anything. */
518
+ async currentPageOf(key) {
519
+ const running = await this.current?.catch(() => undefined);
520
+ if (!running || !running.launched.isOpen())
521
+ return undefined;
522
+ if (!running.sharing)
523
+ return backendContext(running.backend)?.currentTab()?.page;
524
+ const view = await running.sharing.view(key).catch(() => undefined);
525
+ return view ? running.sharing.tabView(view).current() : undefined;
526
+ }
527
+ async callAny(name, args, signal, session, sample) {
274
528
  const tool = this.host.turno.get(name);
275
529
  if (!tool)
276
- return await this.callStock(name, args, signal);
530
+ return await this.callStock(name, args, signal, {}, session);
277
531
  const json = !!args._meta?.json;
532
+ // A batch is refused up front when one of its steps would be, before the browser launches.
533
+ const steps = name === "browser_batch" && Array.isArray(args.actions) ? args.actions : [];
534
+ for (const tool of [name, ...steps.map((s) => s?.tool).filter((t) => typeof t === "string")]) {
535
+ const refusal = this.host.engine.refuse?.(tool, this.host.identity);
536
+ if (refusal)
537
+ return errorResult(refusal, json);
538
+ }
278
539
  const parsed = parseArguments(tool, args);
279
540
  if ("error" in parsed)
280
541
  return errorResult(parsed.error, json);
@@ -282,13 +543,44 @@ class SessionBackend extends EventEmitter {
282
543
  let browserContext;
283
544
  let stock;
284
545
  let endCall;
546
+ let shared;
547
+ let recording;
548
+ let engine;
549
+ let input;
285
550
  if (tool.browser !== false) {
286
551
  const running = await this.browser();
552
+ engine = running.launched.engine;
553
+ input = running.input;
287
554
  endCall = running.idle?.begin();
288
555
  browserContext = running.launched.context;
289
- stock = this.stockAccess(running, signal);
556
+ let view = { backend: running.backend, config: running.config };
557
+ if (running.sharing) {
558
+ // The tool works in the session's own tab, locked like a stock call's.
559
+ const key = session ?? DIRECT_SESSION;
560
+ running.sharing.locks.begin(key, name);
561
+ try {
562
+ view = await running.sharing.view(key);
563
+ const refused = await running.sharing.before(key, name, {}, view, signal);
564
+ if (refused) {
565
+ running.sharing.locks.end(key);
566
+ endCall?.();
567
+ return errorResult(refused, json);
568
+ }
569
+ }
570
+ catch (error) {
571
+ running.sharing.locks.end(key);
572
+ endCall?.();
573
+ throw error;
574
+ }
575
+ shared = { sharing: running.sharing, view, key };
576
+ }
577
+ stock = this.stockAccess(view, signal, session);
578
+ recording = running.recording;
290
579
  }
580
+ const recorder = this.recorderFor(session);
581
+ const secretHook = this.secretHook(recording);
291
582
  try {
583
+ await recording?.beforeCall();
292
584
  const context = {
293
585
  config: this.host.config,
294
586
  clientInfo,
@@ -296,6 +588,11 @@ class SessionBackend extends EventEmitter {
296
588
  ...(stock ? { stock } : {}),
297
589
  ...(signal ? { signal } : {}),
298
590
  ...(session ? { session } : {}),
591
+ ...(recorder ? { recorder } : {}),
592
+ ...(secretHook ? { recording: { pauseForSecret: secretHook } } : {}),
593
+ ...(sample ? { sample } : {}),
594
+ ...(engine ? { engine } : {}),
595
+ ...(this.host.providers ? { providers: this.host.providers } : {}),
299
596
  ...(this.host.identity
300
597
  ? {
301
598
  vault: {
@@ -303,16 +600,31 @@ class SessionBackend extends EventEmitter {
303
600
  redactor: this.host.redactor,
304
601
  guard: this.host.guard,
305
602
  ...(this.host.vaultStore ? { store: this.host.vaultStore } : {}),
603
+ ...(secretHook ? { beforeFill: (page) => secretHook(page) } : {}),
604
+ ...(input ? { input } : {}),
306
605
  },
307
606
  }
308
607
  : {}),
309
608
  };
310
- return await tool.handle(context, parsed.params);
609
+ const result = await tool.handle(context, parsed.params);
610
+ if (stock)
611
+ this.host.live?.follow(session ?? DIRECT_SESSION, stock.currentPage());
612
+ if (name === "browser_login") {
613
+ if (!result.isError)
614
+ recorder?.record("browser_login", { site: parsed.params.site });
615
+ await recording?.afterStep({ tool: name, ok: !result.isError, screenshot: false });
616
+ }
617
+ return result;
311
618
  }
312
619
  catch (error) {
313
620
  return errorResult(String(error), json);
314
621
  }
315
622
  finally {
623
+ recording?.callEnded();
624
+ if (shared) {
625
+ shared.sharing.after(shared.key, shared.view);
626
+ shared.sharing.locks.end(shared.key);
627
+ }
316
628
  endCall?.();
317
629
  }
318
630
  }
@@ -322,13 +634,22 @@ class SessionBackend extends EventEmitter {
322
634
  * comes to the front (a tab in the background would not render, and an action on it would
323
635
  * wait for its timeout).
324
636
  */
325
- async callStock(name, args, signal, options = {}) {
326
- const { backend, config, governor, tuning, idle } = await this.browser();
327
- const endCall = idle?.begin();
637
+ async callStock(name, args, signal, options = {}, session) {
638
+ const refusal = this.host.engine.refuse?.(name, this.host.identity);
639
+ if (refusal)
640
+ return errorResult(refusal, !!args._meta?.json);
641
+ const running = await this.browser();
642
+ const { governor, tuning, idle, sharing, launched } = running;
328
643
  const json = !!args._meta?.json;
644
+ if (sharing)
645
+ return await this.callShared(running, sharing, session ?? DIRECT_SESSION, name, args, signal, options);
646
+ const endCall = idle?.begin();
647
+ const { backend, config } = running;
329
648
  const refused = this.refuseScript(name, backend);
330
- if (refused)
649
+ if (refused) {
650
+ endCall?.();
331
651
  return errorResult(refused, json);
652
+ }
332
653
  const snapshot = config.snapshot ?? {};
333
654
  const mode = snapshot.mode;
334
655
  if (options.snapshot === false)
@@ -336,18 +657,26 @@ class SessionBackend extends EventEmitter {
336
657
  governor.beginCall();
337
658
  let result;
338
659
  try {
660
+ await governor.quiet();
661
+ const pending = await this.beforeStock(running, session, name, args, backendContext(backend)?.currentTab()?.page);
339
662
  await governor.prepare(name, args);
340
- if (tuning.backgroundThrottling && name !== "browser_tabs")
663
+ if (tuning.backgroundThrottling && !launched.userBrowser && name !== "browser_tabs")
341
664
  await backendContext(backend)
342
665
  ?.currentTab()
343
666
  ?.page.bringToFront()
344
667
  .catch(() => { });
345
- result = await backend.callTool(name, args, signal);
668
+ const page = backendContext(backend)?.currentTab()?.page;
669
+ result =
670
+ (launched.engine === "lightpanda" ? undefined : await coveredBeforeCall(page, name, args, json)) ??
671
+ (await backend.callTool(name, args, signal));
672
+ this.host.live?.follow(session ?? DIRECT_SESSION, backendContext(backend)?.currentTab()?.page);
346
673
  if (result.isError)
347
674
  result = await explainFailure(backendContext(backend)?.currentTab()?.page, name, args, result, json);
675
+ await this.afterStock(running, session, name, args, pending, result, backendContext(backend)?.currentTab()?.page);
348
676
  await governor.afterCall();
349
677
  }
350
678
  finally {
679
+ running.recording?.callEnded();
351
680
  endCall?.();
352
681
  governor.endCall();
353
682
  if (options.snapshot === false)
@@ -355,6 +684,136 @@ class SessionBackend extends EventEmitter {
355
684
  }
356
685
  return withGovernor(result, governor, json);
357
686
  }
687
+ /**
688
+ * A stock call with `"sharing": "tabs"`: the same steps as `callStock`, on the session's own
689
+ * backend, after its tab is locked (`sharing.ts`). `browser_close` closes only its tabs.
690
+ */
691
+ async callShared(running, sharing, key, name, args, signal, options) {
692
+ const { governor, tuning, idle } = running;
693
+ const json = !!args._meta?.json;
694
+ // Counted first, so the session is active (and its backend kept) from the first await on.
695
+ sharing.locks.begin(key, name);
696
+ const endCall = idle?.begin();
697
+ governor.beginCall();
698
+ let view;
699
+ let result;
700
+ let restore;
701
+ try {
702
+ await governor.quiet();
703
+ view = await sharing.view(key);
704
+ const { backend, config } = view;
705
+ const refused = name === "browser_close" ? undefined : await sharing.before(key, name, args, view, signal);
706
+ if (refused)
707
+ result = errorResult(refused, json);
708
+ else if (name === "browser_close")
709
+ result = await sharing.close(key);
710
+ else {
711
+ const why = this.refuseScript(name, backend);
712
+ if (why)
713
+ result = errorResult(why, json);
714
+ else {
715
+ const snapshot = config.snapshot ?? {};
716
+ const mode = snapshot.mode;
717
+ if (options.snapshot === false) {
718
+ config.snapshot = { ...snapshot, mode: "none" };
719
+ restore = () => {
720
+ config.snapshot = { ...snapshot, ...(mode === undefined ? {} : { mode }) };
721
+ };
722
+ }
723
+ const tabs = sharing.tabView(view);
724
+ const pending = await this.beforeStock(running, key, name, args, tabs.current());
725
+ await governor.prepare(name, args, tabs);
726
+ if (tuning.backgroundThrottling && name !== "browser_tabs")
727
+ await tabs
728
+ .current()
729
+ ?.bringToFront()
730
+ .catch(() => { });
731
+ result =
732
+ (running.launched.engine === "lightpanda"
733
+ ? undefined
734
+ : await coveredBeforeCall(tabs.current(), name, args, json)) ??
735
+ (await backend.callTool(name, args, signal));
736
+ this.host.live?.follow(key, tabs.current());
737
+ if (result.isError)
738
+ result = await explainFailure(tabs.current(), name, args, result, json);
739
+ await this.afterStock(running, key, name, args, pending, result, tabs.current());
740
+ // The tab the call left current is the session's before the cap counts its tabs.
741
+ sharing.after(key, view);
742
+ await governor.afterCall();
743
+ }
744
+ }
745
+ }
746
+ finally {
747
+ running.recording?.callEnded();
748
+ if (view && name !== "browser_close")
749
+ sharing.after(key, view);
750
+ sharing.locks.end(key);
751
+ endCall?.();
752
+ governor.endCall(view ? sharing.tabView(view) : undefined);
753
+ restore?.();
754
+ }
755
+ if (!view || name === "browser_close")
756
+ return result;
757
+ const tabs = sharing.tabView(view);
758
+ const annotated = withGovernor(result, governor, json, key, tabs);
759
+ const first = annotated.content[0];
760
+ if (!first || first.type !== "text")
761
+ return annotated;
762
+ const text = sharing.annotate(first.text, key, view);
763
+ return { ...annotated, content: [{ ...first, text }, ...annotated.content.slice(1)] };
764
+ }
765
+ /**
766
+ * Before a stock call: the flow step it may become (`recorder.ts`), and a trace stopped and
767
+ * saved before a value goes into a secret field, as before a vault fill (`recordings.ts`).
768
+ */
769
+ async beforeStock(running, session, name, args, page) {
770
+ const { recording } = running;
771
+ await recording?.beforeCall();
772
+ const recorder = this.recorderFor(session);
773
+ const pending = recorder?.active ? await recorder.capture(name, args, page).catch(() => undefined) : undefined;
774
+ const secretHook = this.secretHook(recording);
775
+ if (secretHook && page && (name === "browser_type" || name === "browser_fill_form")) {
776
+ const secrets = await secretValues(page, name, args);
777
+ if (secrets.length) {
778
+ for (const v of secrets)
779
+ this.host.redactor.add(v, "sensitive value");
780
+ await secretHook(page);
781
+ }
782
+ }
783
+ return pending;
784
+ }
785
+ /**
786
+ * What runs before a secret goes into a page (a vault fill, a password typed, a sensitive
787
+ * parameter of a replay), when something could show it: the page is held by the vault guard,
788
+ * the live view stops showing it, and a recording saves its trace. Undefined when neither a
789
+ * recording nor the live view is on.
790
+ */
791
+ secretHook(recording) {
792
+ const live = this.host.live;
793
+ if (!recording && !live)
794
+ return undefined;
795
+ return async (page) => {
796
+ if (page) {
797
+ this.host.guard.mark(page);
798
+ live?.hide(page);
799
+ }
800
+ await recording?.pauseForSecret(page);
801
+ };
802
+ }
803
+ /** After a stock call: keep the flow step when it worked, and the recording's screenshot. */
804
+ async afterStock(running, session, name, args, pending, result, page) {
805
+ if (pending && !result.isError)
806
+ this.recorderFor(session)?.commit(pending);
807
+ const type = this.host.stockTypes.get(name);
808
+ if (running.recording && type !== "readOnly" && type !== "assertion")
809
+ await running.recording.afterStep({
810
+ tool: name,
811
+ element: args.element ?? args.startElement,
812
+ ok: !result.isError,
813
+ ...(page ? { page } : {}),
814
+ screenshot: true,
815
+ });
816
+ }
358
817
  /**
359
818
  * The script tools near the vault: `browser_evaluate` and `browser_run_code_unsafe`
360
819
  * are refused on a page browser_login filled, until it navigates; `browser_run_code_unsafe`
@@ -369,25 +828,40 @@ class SessionBackend extends EventEmitter {
369
828
  return `${name} is refused for browser identity "${identity.id}" because it has vault credentials: it runs code in the server process, which can read the secret store. Use the other browser tools, or an identity without a vault.`;
370
829
  }
371
830
  if (this.host.guard.holds(backendContext(backend)?.currentTab()?.page)) {
372
- return `${name} is refused on this page: it holds values browser_login filled from the vault. Submit the form or navigate away first.`;
831
+ return `${name} is refused on this page: it holds values browser_login filled from the vault (or a password typed while recording or with the live view on). Submit the form or navigate away first.`;
373
832
  }
374
833
  return undefined;
375
834
  }
376
835
  /** The stock tools of this session, for a turno tool that runs them (`browser_batch`). */
377
- stockAccess(running, signal) {
836
+ stockAccess(view, signal, session) {
378
837
  return {
379
838
  schemas: this.host.stockSchemas,
380
839
  formatError: (error) => upstream().utils.z.prettifyError(error),
381
- call: (name, args, options) => this.callStock(name, args, signal, options),
840
+ // A batch, a replay or an act run stops at its next step once the user pauses the agent.
841
+ call: (name, args, options) => this.host.live?.paused
842
+ ? Promise.resolve(errorResult(`${PAUSED_STEP}: this step and the ones after it were not run. Your next call waits until they resume.`, !!args._meta?.json))
843
+ : this.callStock(name, args, signal, options, session),
844
+ held: () => (this.host.live?.paused ? PAUSED_STEP : undefined),
382
845
  page: async () => {
383
- const page = backendContext(running.backend)?.currentTab()?.page;
846
+ const page = backendContext(view.backend)?.currentTab()?.page;
384
847
  if (!page)
385
848
  return undefined;
386
849
  return { url: page.url(), title: await page.title().catch(() => "") };
387
850
  },
388
- currentPage: () => backendContext(running.backend)?.currentTab()?.page,
851
+ currentPage: () => backendContext(view.backend)?.currentTab()?.page,
389
852
  };
390
853
  }
854
+ /** mcpd said a client session ended: with `"sharing": "tabs"` its tabs are free at once. */
855
+ async endSession(session) {
856
+ // A flow the session was recording and never stopped is dropped with it.
857
+ this.recorders.get(session)?.cancel();
858
+ this.recorders.delete(session);
859
+ const current = this.current;
860
+ if (!current)
861
+ return;
862
+ const running = await current.catch(() => undefined);
863
+ await running?.sharing?.endSession(session);
864
+ }
391
865
  async dispose() {
392
866
  if (this.disposed)
393
867
  return;
@@ -441,9 +915,10 @@ function refuseWhileNeedsAuth(identity) {
441
915
  * log) and, when identity.json has a health check that is due, run it; a page without the
442
916
  * proof of a signed-in session throws NEEDS_AUTH, and the call fails with that message.
443
917
  */
444
- async function afterIdentityLaunch(identity, launched) {
918
+ async function afterIdentityLaunch(identity, launched, onChallenge) {
445
919
  const { id, env } = identity;
446
920
  watchChallenges(launched.context, (event) => {
921
+ onChallenge?.(event);
447
922
  try {
448
923
  recordChallenge(id, env, event);
449
924
  }
@@ -461,16 +936,33 @@ async function afterIdentityLaunch(identity, launched) {
461
936
  throw new Error(needsAuthMessage(id, record));
462
937
  }
463
938
  }
939
+ /**
940
+ * identity.json's opt-in keys as the server starts. The tool list is fixed for the life of the
941
+ * server, so turning a feature on takes a restart; turning it off is honored at the next call,
942
+ * since each opt-in tool reads identity.json again. An invalid file lists nothing extra (the
943
+ * first launch reports the problem).
944
+ */
945
+ function optInSettings(identity) {
946
+ if (!identity)
947
+ return undefined;
948
+ try {
949
+ return readIdentitySettings(identity.id, identity.env);
950
+ }
951
+ catch {
952
+ return undefined;
953
+ }
954
+ }
464
955
  /** Builds the host for a resolved config: tool list, engine and session factory. */
465
956
  export function createHost(options) {
466
957
  const { tools } = upstream();
467
958
  const { config, cliOptions } = options;
468
959
  const stock = tools.filteredTools(config);
469
960
  const stockSchemas = new Map(stock.map((t) => [t.schema.name, t.schema.inputSchema]));
470
- const turnoTools = options.turnoTools ?? TURNO_TOOLS;
961
+ const stockTypes = new Map(stock.map((t) => [t.schema.name, t.schema.type]));
962
+ const turnoTools = [...(options.turnoTools ?? TURNO_TOOLS), ...optInTools(optInSettings(options.identity))];
471
963
  checkTurnoTools(turnoTools, tools.browserTools);
472
964
  const turno = new Map(turnoTools.map((t) => [t.schema.name, t]));
473
- const engine = options.engine ?? selectEngine(config, createUpstreamEngine());
965
+ const engine = options.engine ?? createEngine(config, options.engineFlags);
474
966
  const schemas = [...stock.map((t) => t.schema), ...turnoTools.map((t) => t.schema)];
475
967
  const sessionsByName = new Map();
476
968
  const title = (clientInfo) => {
@@ -479,21 +971,28 @@ export function createHost(options) {
479
971
  return count > 1 ? `${clientInfo.clientName} (${count})` : clientInfo.clientName;
480
972
  };
481
973
  const redactor = new Redactor();
974
+ const guard = new VaultGuard();
975
+ const live = options.identity ? liveServerFor(options, options.identity, redactor, guard) : undefined;
482
976
  const shared = {
483
977
  config,
484
978
  cliOptions,
485
979
  stock,
486
980
  stockSchemas,
981
+ stockTypes,
487
982
  turno,
488
983
  engine,
489
984
  tuning: options.tuning ?? {},
490
985
  redactor,
491
- guard: new VaultGuard(),
986
+ guard,
987
+ tabLocks: options.tabLocks ?? {},
988
+ ...(live ? { live } : {}),
492
989
  ...(options.identity ? { identity: options.identity } : {}),
493
990
  ...(options.vaultStore ? { vaultStore: options.vaultStore } : {}),
991
+ ...(options.providers ? { providers: options.providers } : {}),
494
992
  };
495
993
  return {
496
994
  config,
995
+ ...(live ? { live } : {}),
497
996
  redact: (text) => redactor.text(text),
498
997
  listTools: () => schemas.map(toMcpTool),
499
998
  factory: {
@@ -505,6 +1004,45 @@ export function createHost(options) {
505
1004
  },
506
1005
  };
507
1006
  }
1007
+ /**
1008
+ * The live view server of an identity, when `--live` or identity.json `live.enabled` turns it
1009
+ * on; it starts listening at once, so a pause works before the browser starts.
1010
+ */
1011
+ function liveServerFor(options, identity, redactor, guard) {
1012
+ const settings = () => {
1013
+ try {
1014
+ return readIdentitySettings(identity.id, identity.env);
1015
+ }
1016
+ catch {
1017
+ return undefined; // the first launch reports a bad identity.json
1018
+ }
1019
+ };
1020
+ const policy = resolveLive(settings()?.live, options.live);
1021
+ if (!policy.enabled)
1022
+ return undefined;
1023
+ const log = (line) => process.stderr.write(`turno-browser-mcp: ${line}\n`);
1024
+ const server = new LiveServer({
1025
+ identity,
1026
+ policy,
1027
+ guard,
1028
+ redactor,
1029
+ headless: options.config.browser.launchOptions?.headless === true,
1030
+ // Before a launch, the engine identity.json and the flags would pick.
1031
+ viewRefusal: (engine) => {
1032
+ if (engine)
1033
+ return viewRefusal(engine);
1034
+ try {
1035
+ return viewRefusal(engineChoice(options.engineFlags ?? {}, settings()).kind);
1036
+ }
1037
+ catch {
1038
+ return undefined;
1039
+ }
1040
+ },
1041
+ log,
1042
+ });
1043
+ server.start().catch((error) => log(`the live view did not start: ${error.message}`));
1044
+ return server;
1045
+ }
508
1046
  /** The workspace roots the client offers, as upstream reads them (first root, or cwd). */
509
1047
  async function clientInfoOf(server) {
510
1048
  let cwd = process.cwd();
@@ -522,45 +1060,131 @@ async function clientInfoOf(server) {
522
1060
  }
523
1061
  return { cwd, clientName: server.getClientVersion()?.name ?? "Playwright MCP" };
524
1062
  }
525
- /** An MCP server for one session of this host, on any transport. */
526
- function createServer(host) {
527
- const server = new Server(SERVER_INFO, { capabilities: { tools: { listChanged: true } } });
528
- let backend;
1063
+ /**
1064
+ * MCP sampling for a tool call, when the client declared it. `relatedRequestId` in `_meta` is
1065
+ * how mcpd routes a server's request back to the session whose call is in flight (several
1066
+ * sessions share one server with `"sharing": "tabs"`).
1067
+ */
1068
+ function samplerFor(server, requestId) {
1069
+ if (!server.getClientCapabilities()?.sampling)
1070
+ return undefined;
1071
+ return async (request, signal) => {
1072
+ const result = await server.createMessage({
1073
+ ...request,
1074
+ includeContext: "none",
1075
+ temperature: 0,
1076
+ _meta: { relatedRequestId: requestId },
1077
+ }, { ...(signal ? { signal } : {}), timeout: 600_000 });
1078
+ const content = result.content;
1079
+ const parts = Array.isArray(content) ? content : [content];
1080
+ return {
1081
+ text: parts
1082
+ .filter((p) => p.type === "text")
1083
+ .map((p) => p.text ?? "")
1084
+ .join("\n"),
1085
+ model: result.model,
1086
+ };
1087
+ };
1088
+ }
1089
+ /**
1090
+ * An MCP server for one connection of this host, on any transport: with its own session
1091
+ * backend (stdio, one browser per connection), or on the backend of a shared host.
1092
+ */
1093
+ function createServer(host, shared) {
1094
+ // The experimental capability asks mcpd to say when a client session ends (`session.ts`).
1095
+ const server = new Server(SERVER_INFO, {
1096
+ capabilities: { tools: { listChanged: true }, experimental: { [SESSION_CAPABILITY]: {} } },
1097
+ });
1098
+ let own;
529
1099
  const session = () => {
530
- backend ??= (async () => {
1100
+ if (shared)
1101
+ return shared.get(server);
1102
+ own ??= (async () => {
531
1103
  const clientInfo = await clientInfoOf(server);
532
1104
  const b = (await host.factory.create(clientInfo));
533
1105
  await b.initialize(clientInfo);
534
1106
  b.on("dynamictoolschange", () => void server.sendToolListChanged().catch(() => { }));
535
1107
  return b;
536
1108
  })();
537
- backend.catch(() => {
538
- backend = undefined;
1109
+ own.catch(() => {
1110
+ own = undefined;
539
1111
  });
540
- return backend;
1112
+ return own;
541
1113
  };
1114
+ const existing = () => (shared ? shared.peek() : own);
1115
+ shared?.servers.add(server);
542
1116
  server.setRequestHandler(ListToolsRequestSchema, async () => {
543
- const live = await backend?.catch(() => undefined);
1117
+ const live = await existing()?.catch(() => undefined);
544
1118
  return { tools: [...host.listTools(), ...(live?.dynamicTools() ?? [])] };
545
1119
  });
546
1120
  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
547
1121
  try {
548
1122
  const b = await session();
549
1123
  const args = (request.params.arguments ?? {});
550
- const result = await b.callTool(request.params.name, args, extra.signal, sessionFromMeta(request.params._meta));
1124
+ const result = await b.callTool(request.params.name, args, extra.signal, sessionFromMeta(request.params._meta), samplerFor(server, extra.requestId));
551
1125
  return mergeTextParts(result);
552
1126
  }
553
1127
  catch (error) {
554
1128
  return { content: [{ type: "text", text: `### Error\n${host.redact(String(error))}` }], isError: true };
555
1129
  }
556
1130
  });
1131
+ server.fallbackNotificationHandler = async (notification) => {
1132
+ // On a shared host the sessions are the connections, which the host ends itself.
1133
+ if (shared || notification.method !== SESSION_ENDED_METHOD)
1134
+ return;
1135
+ const session = sessionFromMeta({ [SESSION_META_KEY]: notification.params?.session });
1136
+ if (session !== undefined)
1137
+ await (await own?.catch(() => undefined))?.endSession(session);
1138
+ };
557
1139
  const previous = server.onclose;
558
1140
  server.onclose = () => {
559
1141
  previous?.();
560
- void backend?.then((b) => b.dispose()).catch(() => { });
1142
+ if (shared)
1143
+ shared.servers.delete(server);
1144
+ else
1145
+ void own?.then((b) => b.dispose()).catch(() => { });
561
1146
  };
562
1147
  return server;
563
1148
  }
1149
+ export function shareHost(host) {
1150
+ let backend;
1151
+ const servers = new Set();
1152
+ const shared = {
1153
+ servers,
1154
+ peek: () => backend,
1155
+ get(server) {
1156
+ backend ??= (async () => {
1157
+ const clientInfo = await clientInfoOf(server);
1158
+ const b = (await host.factory.create(clientInfo));
1159
+ await b.initialize(clientInfo);
1160
+ b.on("dynamictoolschange", () => {
1161
+ for (const s of servers)
1162
+ void s.sendToolListChanged().catch(() => { });
1163
+ });
1164
+ return b;
1165
+ })();
1166
+ backend.catch(() => {
1167
+ backend = undefined;
1168
+ });
1169
+ return backend;
1170
+ },
1171
+ };
1172
+ return {
1173
+ async connect(transport) {
1174
+ const server = createServer(host, shared);
1175
+ await server.connect(transport);
1176
+ return server;
1177
+ },
1178
+ async endSession(session) {
1179
+ await (await backend?.catch(() => undefined))?.endSession(session);
1180
+ },
1181
+ async dispose() {
1182
+ const b = await backend?.catch(() => undefined);
1183
+ backend = undefined;
1184
+ await b?.dispose();
1185
+ },
1186
+ };
1187
+ }
564
1188
  /** Serves the host: stdio by turno, `--port` by upstream's HTTP server. */
565
1189
  export async function serve(host, transport) {
566
1190
  if (host.config.server.port !== undefined && !transport) {
@@ -577,12 +1201,14 @@ export async function serve(host, transport) {
577
1201
  */
578
1202
  export async function runHost(args, options = {}) {
579
1203
  const { utils, core, version } = upstream();
580
- const { identity, tuning } = options;
1204
+ const { identity, tuning, engineFlags, live } = options;
1205
+ const serveWith = options.serve;
581
1206
  const Command = utils.program.constructor;
582
1207
  const program = new Command().version(`Version ${version}`).name("Playwright MCP");
583
1208
  upstream().tools.decorateMCPCommand(program);
584
1209
  program.action(async (options) => {
585
- upstream().tools.setupExitWatchdog();
1210
+ if (!serveWith)
1211
+ upstream().tools.setupExitWatchdog();
586
1212
  if (options.vision) {
587
1213
  console.error("The --vision option is deprecated, use --caps=vision instead");
588
1214
  options.caps ??= [];
@@ -591,7 +1217,18 @@ export async function runHost(args, options = {}) {
591
1217
  if (options.caps?.includes("tracing"))
592
1218
  options.caps.push("devtools");
593
1219
  const config = await upstream().tools.resolveCLIConfigForMCP(options);
594
- await serve(createHost({ config, cliOptions: options, ...(identity ? { identity } : {}), ...(tuning ? { tuning } : {}) }));
1220
+ const host = createHost({
1221
+ config,
1222
+ cliOptions: options,
1223
+ ...(identity ? { identity } : {}),
1224
+ ...(tuning ? { tuning } : {}),
1225
+ ...(engineFlags ? { engineFlags } : {}),
1226
+ ...(live ? { live } : {}),
1227
+ });
1228
+ if (serveWith)
1229
+ await serveWith(host);
1230
+ else
1231
+ await serve(host);
595
1232
  });
596
1233
  try {
597
1234
  await program.parseAsync(args, { from: "user" });