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