@xiangyixie/dsh-superagent 0.12.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1151 @@
1
+ /**
2
+ * Runtime control: browser and desktop actions, gated and audited.
3
+ *
4
+ * The layer is opt-in. With `runtime.enabled` off nothing is registered, so a
5
+ * profile that never asked for it behaves exactly as before. When it is on, the
6
+ * rules that matter are enforced here rather than trusted to the model:
7
+ *
8
+ * 1. an emergency stop file refuses every action while it exists;
9
+ * 2. navigation is limited to configured hosts (loopback by default) and never
10
+ * reaches `file://` or another local scheme;
11
+ * 3. an action that looks irreversible — submit, delete, pay — needs the caller
12
+ * to repeat the intent with `confirm: true`;
13
+ * 4. bringing a window to the foreground needs `activate: true` plus a config
14
+ * that allows it, and the activation is recorded.
15
+ *
16
+ * Every attempt, allowed or refused, goes through one wrapper that writes the
17
+ * audit line. A refusal is thrown as {@link RuntimeRefusal} rather than returned
18
+ * as text, so the trail can never claim `result: ok` for an action that the gate
19
+ * stopped.
20
+ *
21
+ * @module dsh-superagent/runtime-control
22
+ */
23
+ import { randomUUID } from 'node:crypto'
24
+ import { existsSync } from 'node:fs'
25
+ import fsp from 'node:fs/promises'
26
+ import path from 'node:path'
27
+
28
+ import { attachBrowser, findBrowserExecutable, openBrowser } from './browser.js'
29
+ import { captureScreenshot, clickAt, listWindows, pressKeys, resolveVirtualKeys, typeText } from './desktop.js'
30
+ import { describeError } from './errors.js'
31
+
32
+ /** Hosts an unconfigured install may still reach: the machine itself. */
33
+ export const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '::1']
34
+
35
+ /**
36
+ * Words that mark an action as irreversible in a button label. The list is
37
+ * about intent, not about any particular site: the caller has to repeat
38
+ * `confirm: true` when one of these shows up.
39
+ */
40
+ export const IRREVERSIBLE_PATTERNS = [
41
+ /\bsubmit\b/i,
42
+ /\bconfirm\b/i,
43
+ /\bdelete\b/i,
44
+ /\bremove\b/i,
45
+ /\bpay\b/i,
46
+ /\bpayment\b/i,
47
+ /\bpurchase\b/i,
48
+ /\bbuy\b/i,
49
+ /\bcheckout\b/i,
50
+ /\bplace\s+order\b/i,
51
+ /\btransfer\b/i,
52
+ /\bwithdraw\b/i,
53
+ /\bsend\b/i,
54
+ /\bpublish\b/i,
55
+ /\bdeploy\b/i,
56
+ /\bunsubscribe\b/i,
57
+ /提交/,
58
+ /确定/,
59
+ /确认/,
60
+ /删除/,
61
+ /移除/,
62
+ /支付/,
63
+ /付款/,
64
+ /购买/,
65
+ /下单/,
66
+ /结算/,
67
+ /转账/,
68
+ /提现/,
69
+ /发布/,
70
+ /发送/,
71
+ /注销/,
72
+ ]
73
+
74
+ /** A gate said no. Carries the rule so the audit line names the policy. */
75
+ export class RuntimeRefusal extends Error {
76
+ constructor({ message, rule, decision = 'deny', target = null, meta = {} }) {
77
+ super(message)
78
+ this.name = 'RuntimeRefusal'
79
+ this.rule = rule
80
+ this.decision = decision
81
+ this.target = target
82
+ this.meta = meta
83
+ }
84
+ }
85
+
86
+ /**
87
+ * The page asked for a person. This is a hand-off, not a failure: the action
88
+ * stopped short of the check, the audit line records `decision: "attention"`,
89
+ * and the caller is told how to let the person finish and continue.
90
+ */
91
+ export class RuntimeAttention extends Error {
92
+ constructor({ message, gate, target = null, meta = {} }) {
93
+ super(message)
94
+ this.name = 'RuntimeAttention'
95
+ this.gate = gate
96
+ this.target = target
97
+ this.meta = meta
98
+ }
99
+ }
100
+
101
+ /**
102
+ * The runtime could not be set up. The message is already actionable, so it is
103
+ * returned as-is instead of being run through the provider-error classifier,
104
+ * which would call an unreachable DevTools port a model-provider failure.
105
+ */
106
+ class RuntimeSetupError extends Error {
107
+ constructor({ message, rule, meta = {} }) {
108
+ super(message)
109
+ this.name = 'RuntimeSetupError'
110
+ this.rule = rule
111
+ this.meta = meta
112
+ }
113
+ }
114
+
115
+ /**
116
+ * Find the irreversible-intent word in a label, if any.
117
+ * @param {string|null|undefined} label
118
+ * @returns {string|null} the matched word, so the refusal can quote it.
119
+ */
120
+ export function irreversibleIntent(label) {
121
+ const text = String(label ?? '')
122
+ if (!text.trim()) return null
123
+ for (const pattern of IRREVERSIBLE_PATTERNS) {
124
+ const match = pattern.exec(text)
125
+ if (match) return match[0]
126
+ }
127
+ return null
128
+ }
129
+
130
+ function hostAllowed(host, allowed) {
131
+ const target = String(host ?? '').toLowerCase()
132
+ if (!target) return false
133
+ return allowed.some(entry => {
134
+ const rule = String(entry ?? '').trim().toLowerCase()
135
+ if (!rule) return false
136
+ if (rule.startsWith('*.')) return target === rule.slice(2) || target.endsWith(rule.slice(1))
137
+ return target === rule
138
+ })
139
+ }
140
+
141
+ /**
142
+ * Decide whether a URL may be opened or navigated to.
143
+ *
144
+ * Only `http:` and `https:` are reachable. `file:` is refused outright: a page
145
+ * that can read local files would bypass the filesystem guard entirely, and
146
+ * that guard is the reason a worker cannot touch the user's disk.
147
+ *
148
+ * @param {string} url
149
+ * @param {{ allowedHosts?: string[] }} [options]
150
+ * @returns {{ allowed: boolean, rule: string|null, reason: string|null, url: string }}
151
+ */
152
+ export function checkNavigation(url, { allowedHosts = [] } = {}) {
153
+ const raw = String(url ?? '').trim()
154
+ if (!raw) return { allowed: false, rule: 'runtime/bad-url', reason: 'a URL is required', url: raw }
155
+ if (raw === 'about:blank') return { allowed: true, rule: null, reason: null, url: raw }
156
+ let parsed
157
+ try {
158
+ parsed = new URL(raw)
159
+ } catch {
160
+ return { allowed: false, rule: 'runtime/bad-url', reason: `${JSON.stringify(raw)} is not an absolute URL`, url: raw }
161
+ }
162
+ if (parsed.protocol === 'file:') {
163
+ return {
164
+ allowed: false,
165
+ rule: 'runtime/file-url',
166
+ reason: 'file:// pages are refused: they would expose local files outside the workspace guard',
167
+ url: raw,
168
+ }
169
+ }
170
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
171
+ return {
172
+ allowed: false,
173
+ rule: 'runtime/scheme',
174
+ reason: `only http and https are reachable; ${parsed.protocol} is refused`,
175
+ url: raw,
176
+ }
177
+ }
178
+ const allowed = allowedHosts.length > 0 ? allowedHosts : LOOPBACK_HOSTS
179
+ if (!hostAllowed(parsed.hostname, allowed)) {
180
+ return {
181
+ allowed: false,
182
+ rule: 'runtime/host-not-allowed',
183
+ reason: `${parsed.hostname} is not an allowed host; add it to runtime.browser.allowedHosts `
184
+ + `(currently: ${allowed.join(', ')})`,
185
+ url: raw,
186
+ }
187
+ }
188
+ return { allowed: true, rule: null, reason: null, url: raw }
189
+ }
190
+
191
+ /** Local-time stamp that is safe in a file name on every platform. */
192
+ function stamp(now = Date.now()) {
193
+ const date = new Date(now)
194
+ const pad = value => String(value).padStart(2, '0')
195
+ return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`
196
+ + `T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
197
+ + `-${String(date.getMilliseconds()).padStart(3, '0')}`
198
+ }
199
+
200
+ function clip(text, limit) {
201
+ const value = String(text ?? '').replace(/\s+/g, ' ').trim()
202
+ return value.length > limit ? `${value.slice(0, limit)}…` : value
203
+ }
204
+
205
+ function boxText(box) {
206
+ if (!box) return 'none'
207
+ return `${Math.round(box.x)},${Math.round(box.y)} ${Math.round(box.width)}×${Math.round(box.height)}`
208
+ }
209
+
210
+ /** Short label for the audit trail when the caller addressed an element several ways. */
211
+ function targetLabel(args) {
212
+ if (args?.text) return clip(args.text, 120)
213
+ if (args?.css) return clip(args.css, 120)
214
+ if (Number.isInteger(args?.index)) return `#${args.index}`
215
+ return ''
216
+ }
217
+
218
+ /**
219
+ * Build the runtime-control layer for one plugin mount.
220
+ *
221
+ * @param {{
222
+ * config: object,
223
+ * stateRoot: string,
224
+ * auditor?: { record: (event: object) => Promise<unknown> } | null,
225
+ * warn?: (message: string) => void,
226
+ * now?: () => number,
227
+ * env?: NodeJS.ProcessEnv,
228
+ * openBrowserImpl?: typeof openBrowser,
229
+ * attachBrowserImpl?: typeof attachBrowser,
230
+ * }} options
231
+ */
232
+ export function createRuntimeControl({
233
+ config = {},
234
+ stateRoot,
235
+ auditor = null,
236
+ warn = () => {},
237
+ now = () => Date.now(),
238
+ env = process.env,
239
+ openBrowserImpl = openBrowser,
240
+ attachBrowserImpl = attachBrowser,
241
+ } = {}) {
242
+ const enabled = config?.enabled === true
243
+ const browserConfig = {
244
+ enabled: true,
245
+ headless: true,
246
+ executablePath: null,
247
+ attachPort: null,
248
+ userDataDir: null,
249
+ allowedHosts: [],
250
+ ...(config?.browser ?? {}),
251
+ }
252
+ const desktopConfig = { enabled: false, allowActivation: false, ...(config?.desktop ?? {}) }
253
+ const allowActivation = desktopConfig.allowActivation === true || config?.allowActivation === true
254
+ const stopFile = typeof config?.stopFile === 'string' && config.stopFile.trim()
255
+ ? path.resolve(config.stopFile.trim())
256
+ : path.join(stateRoot, 'runtime', 'STOP')
257
+ const shotDir = typeof config?.shotDir === 'string' && config.shotDir.trim()
258
+ ? path.resolve(config.shotDir.trim())
259
+ : path.join(stateRoot, 'runtime', 'shots')
260
+
261
+ /** Live browser, created on first use and reused until `browser_close`. */
262
+ let session = null
263
+
264
+ /** True when the emergency stop is set, plus the evidence that says so. */
265
+ function stopState() {
266
+ if (/^(1|true|yes|on)$/i.test(String(env.DSH_RUNTIME_STOP ?? ''))) {
267
+ return { stopped: true, source: 'DSH_RUNTIME_STOP=1' }
268
+ }
269
+ if (existsSync(stopFile)) return { stopped: true, source: stopFile }
270
+ return { stopped: false, source: null }
271
+ }
272
+
273
+ async function record(event) {
274
+ if (!auditor || typeof auditor.record !== 'function') return null
275
+ try {
276
+ return await auditor.record({
277
+ kind: event.kind ?? 'runtime',
278
+ action: event.action,
279
+ target: event.target ?? null,
280
+ decision: event.decision ?? 'allow',
281
+ result: event.result ?? 'ok',
282
+ durationMs: event.durationMs ?? 0,
283
+ rule: event.rule ?? null,
284
+ source: 'runtime',
285
+ meta: event.meta ?? {},
286
+ })
287
+ } catch (error) {
288
+ warn(`audit: cannot record ${event.action}: ${error?.message ?? error}`)
289
+ return null
290
+ }
291
+ }
292
+
293
+ /** Throw when the stop switch is set. The caller's wrapper records the refusal. */
294
+ function assertNotStopped() {
295
+ const state = stopState()
296
+ if (!state.stopped) return
297
+ throw new RuntimeRefusal({
298
+ message: `runtime control is stopped by ${state.source}. The action did not run.\n`
299
+ + 'hint: delete that file (or unset DSH_RUNTIME_STOP) only when you are ready to allow actions again.',
300
+ rule: 'runtime/stopped',
301
+ decision: 'deny',
302
+ meta: { stop: state.source },
303
+ })
304
+ }
305
+
306
+ function shotPath(prefix) {
307
+ return path.join(shotDir, `${prefix}-${stamp(now())}-${randomUUID().slice(0, 6)}.png`)
308
+ }
309
+
310
+ function shotFile(requested, prefix) {
311
+ return typeof requested === 'string' && requested.trim() ? path.resolve(requested.trim()) : shotPath(prefix)
312
+ }
313
+
314
+ function clamp(value, min, max, fallback) {
315
+ const number = Number(value)
316
+ if (!Number.isFinite(number)) return fallback
317
+ return Math.min(max, Math.max(min, Math.trunc(number)))
318
+ }
319
+
320
+ /**
321
+ * Say which connection an action used. Written into every browser audit line,
322
+ * so `attach` and a profile this plugin launched can never be confused.
323
+ */
324
+ function markSession(live, meta) {
325
+ const attach = live.mode === 'attach'
326
+ meta.session = attach ? 'attach' : 'launch'
327
+ meta.port = live.port ?? null
328
+ if (attach) {
329
+ if (live.browser) meta.browser = live.browser
330
+ if (live.attachedUrl) meta.tab = live.attachedUrl
331
+ return
332
+ }
333
+ if (live.userDataDir) meta.profile = live.userDataDir
334
+ meta.persistentProfile = live.persistentProfile === true
335
+ meta.headless = live.headless === true
336
+ }
337
+
338
+ function describeSession(live) {
339
+ if (!live) return 'none'
340
+ if (live.mode === 'attach') {
341
+ return `attached to 127.0.0.1:${live.port}${live.browser ? ` (${live.browser})` : ''}`
342
+ + `${live.attachedUrl ? ` tab ${live.attachedUrl}` : ''}`
343
+ }
344
+ return `launched on port ${live.port} with ${live.persistentProfile ? 'persistent' : 'temporary'} `
345
+ + `profile ${live.userDataDir}`
346
+ }
347
+
348
+ /** Explain an attach failure in terms the user can act on; never fall back. */
349
+ function attachFailure(port, error) {
350
+ const detail = error?.message ?? String(error)
351
+ return new RuntimeSetupError({
352
+ rule: 'runtime/attach-failed',
353
+ meta: { port },
354
+ message: [
355
+ `cannot attach to the browser on 127.0.0.1:${port}: ${detail}`,
356
+ 'hint: that browser must already be listening for DevTools on the port, and an already-running browser ignores the flag; start a separate instance:',
357
+ ` "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=${port} --user-data-dir="%TEMP%\\dsh-attach-profile"`,
358
+ ` or "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe" --remote-debugging-port=${port} --user-data-dir="%TEMP%\\dsh-attach-profile"`,
359
+ `keep runtime.browser.attachPort at ${port}, or set it to null so the plugin launches its own isolated profile.`,
360
+ 'no browser was launched in its place: attach never falls back to a new profile.',
361
+ ].join('\n'),
362
+ })
363
+ }
364
+
365
+ async function currentBrowser() {
366
+ if (session) return session
367
+ if (browserConfig.attachPort !== null && browserConfig.attachPort !== undefined) {
368
+ const port = Number(browserConfig.attachPort)
369
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
370
+ throw new Error(`runtime.browser.attachPort must be a port number, not ${JSON.stringify(browserConfig.attachPort)}`)
371
+ }
372
+ try {
373
+ session = await attachBrowserImpl({ port })
374
+ } catch (error) {
375
+ throw attachFailure(port, error)
376
+ }
377
+ warn(
378
+ `runtime: attached to the browser on 127.0.0.1:${port}`
379
+ + `${session.attachedUrl ? ` (tab ${session.attachedUrl})` : ''}; no new profile was created`,
380
+ )
381
+ return session
382
+ }
383
+ session = await openBrowserImpl({
384
+ executablePath: browserConfig.executablePath ?? null,
385
+ headless: browserConfig.headless !== false,
386
+ userDataDir: browserConfig.userDataDir ?? null,
387
+ })
388
+ warn(
389
+ `runtime: launched ${session.executablePath} on port ${session.port} with `
390
+ + `${session.persistentProfile ? 'persistent' : 'temporary'} profile ${session.userDataDir}`,
391
+ )
392
+ return session
393
+ }
394
+
395
+ /** Report the human check the page is waiting for, or null when it is absent. */
396
+ async function gateOf(page) {
397
+ if (!page || typeof page.humanGate !== 'function') return null
398
+ try {
399
+ return await page.humanGate()
400
+ } catch {
401
+ // A page that is mid-navigation cannot be inspected; the next action retries.
402
+ return null
403
+ }
404
+ }
405
+
406
+ async function pageIdentity(page) {
407
+ try {
408
+ const info = await page.evaluate('({ url: location.href, title: document.title })')
409
+ return { url: info?.url ?? null, title: info?.title ?? null }
410
+ } catch {
411
+ return { url: null, title: null }
412
+ }
413
+ }
414
+
415
+ /** The hand-off text: what stopped, where the person finishes it, what to call next. */
416
+ async function attentionFor({ gate, live, target = null, screenshot = null, waitedMs = null }) {
417
+ const where = await pageIdentity(live.page)
418
+ const mode = live.mode === 'attach'
419
+ ? `this plugin is attached to the browser on 127.0.0.1:${live.port}, so finish the step in that tab`
420
+ : live.headless === false
421
+ ? 'the launched browser window is visible; finish the step in that window'
422
+ : 'the browser was launched headless, so there is no window to use: rerun with browser.headless:false, '
423
+ + 'or start your own browser with --remote-debugging-port and set browser.attachPort'
424
+ const persistent = live.mode !== 'attach' && live.persistentProfile
425
+ ? `this profile is kept at ${live.userDataDir}, so a sign-in completed now is reused on later runs`
426
+ : null
427
+ return [
428
+ `the page is asking for a person: ${gate.label} (matched "${gate.matched}").`,
429
+ `page: ${where.url ?? '(unknown)'}${where.title ? ` — ${where.title}` : ''}`,
430
+ 'why it stopped: automation must not solve a check, type a one-time code, or scan a QR code; the action stopped short of it.',
431
+ `what to do: ${mode}.`,
432
+ persistent,
433
+ 'then: call browser_await_human; it returns ok once the check is gone and the run continues. A pending check is not a failure.',
434
+ target ? `target: ${clip(target, 120)}` : null,
435
+ waitedMs === null || waitedMs === undefined ? null : `waited: ${waitedMs}ms`,
436
+ screenshot ? `screenshot: ${screenshot}` : null,
437
+ ].filter(Boolean).join('\n')
438
+ }
439
+
440
+ /** Throw a hand-off when a state-changing action lands on a human check. */
441
+ async function raiseIfGated(live, { target = null, screenshot = null } = {}) {
442
+ const gate = await gateOf(live.page)
443
+ if (!gate) return
444
+ throw new RuntimeAttention({
445
+ message: await attentionFor({ gate, live, target, screenshot }),
446
+ gate,
447
+ target: target ?? gate.kind,
448
+ })
449
+ }
450
+
451
+ /**
452
+ * The single place an action is allowed to run.
453
+ *
454
+ * The stop switch is checked first, the work runs, and the outcome is written
455
+ * to the audit trail exactly once. A {@link RuntimeRefusal} becomes a blocked
456
+ * audit line plus an `[error]` result the model can read; any other throw
457
+ * becomes a `result: error` line so a crash is never mistaken for success.
458
+ */
459
+ async function guarded({ kind, action, target }, work) {
460
+ const started = now()
461
+ const meta = {}
462
+ try {
463
+ assertNotStopped()
464
+ const value = await work(meta)
465
+ await record({ kind, action, target, decision: 'allow', result: 'ok', durationMs: now() - started, meta })
466
+ return value
467
+ } catch (error) {
468
+ if (error instanceof RuntimeAttention) {
469
+ await record({
470
+ kind: 'attention',
471
+ action,
472
+ target: error.target ?? target,
473
+ decision: 'attention',
474
+ result: 'needs-human',
475
+ rule: 'runtime/needs-human',
476
+ durationMs: now() - started,
477
+ meta: {
478
+ ...meta,
479
+ ...error.meta,
480
+ gate: error.gate?.kind ?? null,
481
+ matched: error.gate?.matched ?? null,
482
+ },
483
+ })
484
+ return `[attention] ${error.message}`
485
+ }
486
+ if (error instanceof RuntimeSetupError) {
487
+ await record({
488
+ kind,
489
+ action,
490
+ target,
491
+ decision: 'allow',
492
+ result: 'error',
493
+ rule: error.rule,
494
+ durationMs: now() - started,
495
+ meta: { ...meta, ...error.meta, error: error.message },
496
+ })
497
+ return `[error] ${error.message}`
498
+ }
499
+ if (error instanceof RuntimeRefusal) {
500
+ await record({
501
+ kind,
502
+ action,
503
+ target: error.target ?? target,
504
+ decision: error.decision,
505
+ result: 'blocked',
506
+ rule: error.rule,
507
+ durationMs: now() - started,
508
+ meta: { ...meta, ...error.meta },
509
+ })
510
+ return `[error] ${error.message}`
511
+ }
512
+ await record({
513
+ kind,
514
+ action,
515
+ target,
516
+ decision: 'allow',
517
+ result: 'error',
518
+ durationMs: now() - started,
519
+ meta: { ...meta, error: String(error?.message ?? error) },
520
+ })
521
+ return describeError(error)
522
+ }
523
+ }
524
+
525
+ /** Browser actions: open or reuse the session, then run against its page. */
526
+ function withPage(action, target, work) {
527
+ return guarded({ kind: 'runtime.browser', action, target }, async meta => {
528
+ const live = await currentBrowser()
529
+ markSession(live, meta)
530
+ return work(live, meta)
531
+ })
532
+ }
533
+
534
+ /** Describe the element a call is about, without needing the caller to know its index. */
535
+ async function pickElement(page, { index = null, css = null, text = null, role = null }) {
536
+ if (Number.isInteger(index) && index >= 0) {
537
+ const found = await page.evaluate(`(() => {
538
+ const el = document.querySelector('[data-dsh-el="${index}"]')
539
+ if (!el) return null
540
+ const rect = el.getBoundingClientRect()
541
+ return { index: ${index}, label: (el.innerText || el.textContent || '').trim().slice(0, 120), type: (el.getAttribute('type') || '').toLowerCase(), box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } }
542
+ })()`)
543
+ if (!found) throw new Error(`element index ${index} is not on the page any more; call browser_elements again`)
544
+ return found
545
+ }
546
+ if (css) {
547
+ const found = await page.evaluate(`(() => {
548
+ const el = document.querySelector(${JSON.stringify(String(css))})
549
+ if (!el) return null
550
+ el.scrollIntoView({ block: 'center', inline: 'center' })
551
+ const rect = el.getBoundingClientRect()
552
+ return { index: null, label: (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim().slice(0, 120), type: (el.getAttribute('type') || '').toLowerCase(), box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } }
553
+ })()`)
554
+ if (!found) throw new Error(`no element matches the selector ${css}`)
555
+ return found
556
+ }
557
+ if (!text && !role) throw new Error('name the target with index, css, text, or role')
558
+ const listing = await page.elements()
559
+ const needle = text ? String(text).toLowerCase() : null
560
+ const wantedRole = role ? String(role).toLowerCase() : null
561
+ const matches = listing.elements.filter(item => {
562
+ if (wantedRole && String(item.role ?? '').toLowerCase() !== wantedRole) return false
563
+ if (!needle) return true
564
+ return `${item.name ?? ''} ${item.value ?? ''}`.toLowerCase().includes(needle)
565
+ })
566
+ if (matches.length === 0) {
567
+ throw new Error(
568
+ `no ${role ? `${role} ` : ''}element containing ${JSON.stringify(text ?? '')}; `
569
+ + 'call browser_elements to see what the page exposes',
570
+ )
571
+ }
572
+ const visible = matches.find(item => item.inViewport) ?? matches[0]
573
+ return {
574
+ index: visible.index,
575
+ label: clip(visible.name, 120),
576
+ role: visible.role,
577
+ type: visible.type,
578
+ box: visible.bbox,
579
+ }
580
+ }
581
+
582
+ async function shoot(page, prefix, fullPage = false) {
583
+ return page.screenshot({ path: shotPath(prefix), fullPage })
584
+ }
585
+
586
+ /** Gate shared by browser and desktop actions whose label may be irreversible. */
587
+ function assertConfirmable(label, confirm, extra = {}) {
588
+ const intent = irreversibleIntent(label)
589
+ if (!intent) return
590
+ if (confirm === true) return
591
+ throw new RuntimeRefusal({
592
+ message: `${JSON.stringify(clip(label, 80))} looks irreversible (matched "${intent}"), so nothing ran.\n`
593
+ + 'hint: repeat the call with confirm: true if it is genuinely intended.',
594
+ rule: 'runtime/irreversible',
595
+ decision: 'confirm',
596
+ target: String(label),
597
+ meta: { matched: intent, ...extra },
598
+ })
599
+ }
600
+
601
+ function assertActivationAllowed(activate) {
602
+ if (activate !== true || allowActivation) return
603
+ throw new RuntimeRefusal({
604
+ message: 'activation is disabled: runtime.desktop.allowActivation is false.\n'
605
+ + 'hint: pass window so the action can be posted in the background, or ask the user to allow activation.',
606
+ rule: 'runtime/activation-disabled',
607
+ decision: 'deny',
608
+ })
609
+ }
610
+
611
+ const browserTools = browserConfig.enabled === false ? [] : [
612
+ {
613
+ name: 'browser_open',
614
+ description:
615
+ 'Open a page in a Chromium-family browser: either the browser this plugin launches with its own profile, '
616
+ + 'or the one the user started with --remote-debugging-port when runtime.browser.attachPort is set. '
617
+ + 'Only http/https on the configured hosts (loopback by default) are reachable; file:// is refused. '
618
+ + 'Returns the final URL, title, viewport, and a screenshot path. A sign-in, CAPTCHA, SMS, or QR check '
619
+ + 'comes back as [attention] with how to hand over, not as a failure.',
620
+ properties: {
621
+ url: { type: 'string', description: 'Absolute http(s) URL to open.' },
622
+ headless: { type: 'boolean', description: 'Run without a visible window (default from config).' },
623
+ width: { type: 'number', description: 'Viewport width in CSS pixels (default 1280).' },
624
+ height: { type: 'number', description: 'Viewport height in CSS pixels (default 900).' },
625
+ },
626
+ required: ['url'],
627
+ async execute(args = {}) {
628
+ const verdict = checkNavigation(args.url, { allowedHosts: browserConfig.allowedHosts })
629
+ if (!verdict.allowed) {
630
+ await record({
631
+ kind: 'runtime.browser',
632
+ action: 'open',
633
+ target: verdict.url,
634
+ decision: 'deny',
635
+ result: 'blocked',
636
+ rule: verdict.rule,
637
+ meta: { reason: verdict.reason },
638
+ })
639
+ return `[error] ${verdict.reason}\nrule: ${verdict.rule}`
640
+ }
641
+ return withPage('open', verdict.url, async (live, meta) => {
642
+ const page = live.page
643
+ // An attached tab is the user's window; re-applying a fixed viewport
644
+ // would resize it under them.
645
+ await page.init({
646
+ width: Number(args.width) || 1280,
647
+ height: Number(args.height) || 900,
648
+ emulateViewport: live.mode !== 'attach',
649
+ })
650
+ const loaded = await page.goto(verdict.url)
651
+ const shot = await shoot(page, 'open')
652
+ const info = await page.evaluate('({ width: innerWidth, height: innerHeight })')
653
+ meta.url = loaded.url
654
+ meta.title = loaded.title
655
+ meta.screenshot = shot.path
656
+ await raiseIfGated(live, { target: loaded.url, screenshot: shot.path })
657
+ return [
658
+ 'browser_open: ok',
659
+ `url: ${loaded.url}`,
660
+ `title: ${loaded.title}`,
661
+ `viewport: ${info.width}×${info.height}`,
662
+ `screenshot: ${shot.path}`,
663
+ ].join('\n')
664
+ })
665
+ },
666
+ },
667
+ {
668
+ name: 'browser_elements',
669
+ description:
670
+ 'List the actionable elements on the current page with a stable index, accessible name, role, and '
671
+ + 'bounding box. Filter by visible text, role, or CSS selector. Feed the index to browser_click or browser_type.',
672
+ properties: {
673
+ text: { type: 'string', description: 'Keep elements whose name contains this text, ignoring case.' },
674
+ role: { type: 'string', description: 'Keep elements with exactly this role (button, link, textbox, checkbox…).' },
675
+ limit: { type: 'number', description: 'Maximum rows to print (default 60).' },
676
+ },
677
+ async execute(args = {}) {
678
+ return withPage('elements', null, async live => {
679
+ const listing = await live.page.elements()
680
+ const needle = args.text ? String(args.text).toLowerCase() : null
681
+ const role = args.role ? String(args.role).toLowerCase() : null
682
+ const rows = listing.elements.filter(item => {
683
+ if (role && String(item.role ?? '').toLowerCase() !== role) return false
684
+ if (!needle) return true
685
+ return `${item.name ?? ''} ${item.value ?? ''}`.toLowerCase().includes(needle)
686
+ })
687
+ const limit = Math.max(1, Math.min(400, Number(args.limit) || 60))
688
+ if (rows.length === 0) {
689
+ return `browser_elements: 0 matches of ${listing.elements.length} element(s) on ${listing.url}`
690
+ }
691
+ const lines = [
692
+ `browser_elements: ${rows.length} of ${listing.elements.length} element(s) on ${listing.url}`,
693
+ `title: ${listing.title}`,
694
+ `scroll: ${listing.scroll.x},${listing.scroll.y} viewport: ${listing.viewport.width}×${listing.viewport.height}`,
695
+ ]
696
+ for (const item of rows.slice(0, limit)) {
697
+ lines.push(
698
+ ` [${item.index}] ${String(item.role ?? '-').padEnd(10)} `
699
+ + `${boxText(item.bbox).padEnd(20)} ${item.inViewport ? 'in-view' : 'offscreen'} `
700
+ + `${item.disabled ? 'disabled ' : ''}${clip(item.name, 70) || '(no name)'}`,
701
+ )
702
+ }
703
+ if (rows.length > limit) lines.push(` … ${rows.length - limit} more (raise limit to see them)`)
704
+ return lines.join('\n')
705
+ })
706
+ },
707
+ },
708
+ {
709
+ name: 'browser_click',
710
+ description:
711
+ 'Click one element by index, CSS selector, visible text, or role. Returns the element box and a fresh '
712
+ + 'screenshot taken after the click, so the result is evidence rather than a claim. Actions whose label '
713
+ + 'means submit/delete/pay need confirm: true.',
714
+ properties: {
715
+ index: { type: 'number', description: 'Element index from browser_elements.' },
716
+ css: { type: 'string', description: 'CSS selector, used when index is absent.' },
717
+ text: { type: 'string', description: 'Visible text or accessible name to match, ignoring case.' },
718
+ role: { type: 'string', description: 'Role to disambiguate a text match.' },
719
+ confirm: { type: 'boolean', description: 'Confirm an irreversible action (submit, delete, pay). Required for those labels.' },
720
+ screenshot: { type: 'boolean', description: 'Capture a screenshot after clicking (default true).' },
721
+ },
722
+ async execute(args = {}) {
723
+ return withPage('click', targetLabel(args), async (live, meta) => {
724
+ const page = live.page
725
+ const target = await pickElement(page, args)
726
+ if (target.type === 'file') {
727
+ throw new RuntimeRefusal({
728
+ message: `${JSON.stringify(clip(target.label, 60) || 'this file input')} is a file input, and uploads are refused.\n`
729
+ + 'hint: uploading would send a local file to a page; add the file through the workspace instead, '
730
+ + 'or ask the user to pick it manually.',
731
+ rule: 'runtime/file-upload',
732
+ decision: 'deny',
733
+ target: clip(target.label, 120) || 'file input',
734
+ })
735
+ }
736
+ assertConfirmable(target.label, args.confirm, { index: target.index })
737
+ let clicked
738
+ if (target.index !== null && target.index !== undefined) clicked = await page.clickIndex(target.index)
739
+ else clicked = await page.clickAt({ x: target.box.x + target.box.width / 2, y: target.box.y + target.box.height / 2, box: target.box })
740
+ await page.waitFor({ sleepMs: 250 })
741
+ const url = await page.evaluate('location.href')
742
+ meta.url = url
743
+ meta.index = target.index
744
+ if (args.screenshot !== false) {
745
+ const shot = await shoot(page, 'click')
746
+ meta.screenshot = shot.path
747
+ }
748
+ await raiseIfGated(live, { target: target.label, screenshot: meta.screenshot ?? null })
749
+ const lines = [
750
+ 'browser_click: ok',
751
+ `target: [${target.index ?? 'css'}] ${clip(target.label, 80) || '(no name)'}`,
752
+ `box: ${boxText(clicked.box ?? target.box)} clicked at ${clicked.x},${clicked.y}`,
753
+ `url: ${url}`,
754
+ ]
755
+ if (meta.screenshot) lines.push(`screenshot: ${meta.screenshot}`)
756
+ return lines.join('\n')
757
+ })
758
+ },
759
+ },
760
+ {
761
+ name: 'browser_type',
762
+ description:
763
+ 'Focus an element and insert text through the browser input pipeline, then optionally press Enter. '
764
+ + 'Returns the value the page reports and a screenshot.',
765
+ properties: {
766
+ index: { type: 'number', description: 'Element index from browser_elements.' },
767
+ css: { type: 'string', description: 'CSS selector, used when index is absent.' },
768
+ text: { type: 'string', description: 'Visible text or accessible name of the field.' },
769
+ value: { type: 'string', description: 'Text to insert.' },
770
+ submit: { type: 'boolean', description: 'Press Enter afterwards.' },
771
+ screenshot: { type: 'boolean', description: 'Capture a screenshot after typing (default true).' },
772
+ },
773
+ required: ['value'],
774
+ async execute(args = {}) {
775
+ return withPage('type', targetLabel(args), async (live, meta) => {
776
+ const page = live.page
777
+ const target = await pickElement(page, args)
778
+ const result = await page.typeInto({ index: target.index, text: String(args.value ?? ''), submit: args.submit === true })
779
+ await page.waitFor({ sleepMs: 200 })
780
+ const readBack = await page.evaluate(`(() => {
781
+ const el = document.activeElement
782
+ if (!el) return { tag: null, value: null }
783
+ return { tag: el.tagName.toLowerCase(), value: typeof el.value === 'string' ? el.value.slice(0, 200) : (el.innerText || '').slice(0, 200) }
784
+ })()`)
785
+ const url = await page.evaluate('location.href')
786
+ meta.url = url
787
+ meta.index = target.index
788
+ if (args.screenshot !== false) {
789
+ const shot = await shoot(page, 'type')
790
+ meta.screenshot = shot.path
791
+ }
792
+ if (args.submit === true) await raiseIfGated(live, { target: target.label, screenshot: meta.screenshot ?? null })
793
+ const shown = target.type === 'password' ? '•••••• (masked)' : JSON.stringify(readBack.value)
794
+ const lines = [
795
+ 'browser_type: ok',
796
+ `target: ${clip(target.label, 80)} box: ${boxText(target.box)}`,
797
+ `inserted: ${result.inserted} character(s)${result.submit ? ', Enter pressed' : ''}`,
798
+ `focused value: ${shown}`,
799
+ `url: ${url}`,
800
+ ]
801
+ if (meta.screenshot) lines.push(`screenshot: ${meta.screenshot}`)
802
+ return lines.join('\n')
803
+ })
804
+ },
805
+ },
806
+ {
807
+ name: 'browser_screenshot',
808
+ description: 'Capture the current page as a PNG and return its path, pixel size, and byte size.',
809
+ properties: {
810
+ path: { type: 'string', description: 'Optional destination file; defaults to the runtime screenshot directory.' },
811
+ full_page: { type: 'boolean', description: 'Capture beyond the viewport (default false).' },
812
+ },
813
+ async execute(args = {}) {
814
+ return withPage('screenshot', null, async live => {
815
+ const file = shotFile(args.path, 'page')
816
+ const shot = await live.page.screenshot({ path: file, fullPage: args.full_page === true })
817
+ return [
818
+ 'browser_screenshot: ok',
819
+ `path: ${shot.path}`,
820
+ `viewport: ${shot.width}×${shot.height} bytes: ${shot.bytes}`,
821
+ `url: ${await live.page.evaluate('location.href')}`,
822
+ ].join('\n')
823
+ })
824
+ },
825
+ },
826
+ {
827
+ name: 'browser_script',
828
+ description:
829
+ 'Evaluate one JavaScript expression in the page and return its JSON value. Use it for reads; clicks and '
830
+ + 'typing belong to browser_click and browser_type, where the audit trail can name the element.',
831
+ properties: {
832
+ expression: { type: 'string', description: 'Expression to evaluate, e.g. document.title.' },
833
+ await_promise: { type: 'boolean', description: 'Wait for a returned Promise (default true).' },
834
+ },
835
+ required: ['expression'],
836
+ async execute(args = {}) {
837
+ return withPage('script', clip(args.expression, 140), async live => {
838
+ const value = await live.page.evaluate(String(args.expression ?? ''), { awaitPromise: args.await_promise !== false })
839
+ const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
840
+ const clipped = text.length > 8000 ? `${text.slice(0, 8000)}\n[truncated ${text.length - 8000} character(s)]` : text
841
+ return `browser_script: ok\nresult: ${clipped}`
842
+ })
843
+ },
844
+ },
845
+ {
846
+ name: 'browser_wait',
847
+ description: 'Wait for visible text, a CSS selector, a URL fragment, or a fixed delay before the next action.',
848
+ properties: {
849
+ text: { type: 'string', description: 'Body text that must appear.' },
850
+ css: { type: 'string', description: 'Selector that must match.' },
851
+ url_contains: { type: 'string', description: 'Fragment the URL must contain.' },
852
+ milliseconds: { type: 'number', description: 'Fixed delay instead of a condition.' },
853
+ timeout_ms: { type: 'number', description: 'Give up after this long (default 10000).' },
854
+ },
855
+ async execute(args = {}) {
856
+ return withPage('wait', clip(args.text ?? args.css ?? args.url_contains ?? '', 120), async live => {
857
+ const timeoutMs = Math.max(100, Number(args.timeout_ms) || 10000)
858
+ const result = await live.page.waitFor({
859
+ text: args.text ?? null,
860
+ css: args.css ?? null,
861
+ urlContains: args.url_contains ?? null,
862
+ timeoutMs,
863
+ sleepMs: Number.isFinite(Number(args.milliseconds)) ? Number(args.milliseconds) : null,
864
+ })
865
+ return `browser_wait: ok after ${result.waited}ms\ncondition: ${result.condition}\nurl: ${await live.page.evaluate('location.href')}`
866
+ })
867
+ },
868
+ },
869
+ {
870
+ name: 'browser_await_human',
871
+ description:
872
+ 'Wait for a person to clear a sign-in, CAPTCHA, SMS code, two-factor, or QR-login check in the page, then '
873
+ + 'report that automation may continue. It never solves, types, or scans the check. A check still pending at '
874
+ + 'the timeout comes back as [attention]; that is a hand-off, not a failed run.',
875
+ properties: {
876
+ timeout_ms: { type: 'number', description: 'How long to wait for the check to clear (default 120000, max 1800000).' },
877
+ poll_ms: { type: 'number', description: 'How often to look at the page again (default 1000).' },
878
+ screenshot: { type: 'boolean', description: 'Capture a screenshot once the check is gone (default true).' },
879
+ },
880
+ async execute(args = {}) {
881
+ if (!session) return '[error] no browser is open; call browser_open first'
882
+ return withPage('await_human', 'human verification', async (live, meta) => {
883
+ const timeoutMs = clamp(args.timeout_ms, 1000, 1800000, 120000)
884
+ const pollMs = clamp(args.poll_ms, 100, 10000, 1000)
885
+ const started = now()
886
+ let gate = await gateOf(live.page)
887
+ while (gate) {
888
+ const elapsed = now() - started
889
+ if (elapsed >= timeoutMs) {
890
+ if (args.screenshot !== false) {
891
+ const shot = await shoot(live.page, 'attention')
892
+ meta.screenshot = shot.path
893
+ }
894
+ meta.waited = elapsed
895
+ throw new RuntimeAttention({
896
+ message: await attentionFor({
897
+ gate,
898
+ live,
899
+ target: gate.kind,
900
+ screenshot: meta.screenshot ?? null,
901
+ waitedMs: elapsed,
902
+ }),
903
+ gate,
904
+ target: gate.kind,
905
+ meta: { waited: elapsed },
906
+ })
907
+ }
908
+ await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, timeoutMs - elapsed)))
909
+ gate = await gateOf(live.page)
910
+ }
911
+ const waited = now() - started
912
+ const url = await live.page.evaluate('location.href')
913
+ meta.waited = waited
914
+ meta.gate = 'cleared'
915
+ meta.url = url
916
+ const lines = ['browser_await_human: ok', `cleared after ${waited}ms`, `url: ${url}`]
917
+ if (args.screenshot !== false) {
918
+ const shot = await shoot(live.page, 'human')
919
+ meta.screenshot = shot.path
920
+ lines.push(`screenshot: ${shot.path}`)
921
+ }
922
+ return lines.join('\n')
923
+ })
924
+ },
925
+ },
926
+ {
927
+ name: 'browser_close',
928
+ description:
929
+ 'Forget the page handle. A browser this plugin launched is closed; an attached browser is only detached, '
930
+ + 'because it belongs to the user and keeps running.',
931
+ properties: {},
932
+ async execute() {
933
+ return guarded({ kind: 'runtime.browser', action: 'close', target: null }, async meta => {
934
+ if (!session) return 'browser_close: no browser was open'
935
+ const closing = session
936
+ session = null
937
+ markSession(closing, meta)
938
+ await closing.close()
939
+ return closing.mode === 'attach'
940
+ ? `browser_close: detached from 127.0.0.1:${closing.port}; the browser you started was left running`
941
+ : 'browser_close: ok'
942
+ })
943
+ },
944
+ },
945
+ ]
946
+
947
+ const desktopTools = desktopConfig.enabled === false ? [] : [
948
+ {
949
+ name: 'desktop_screenshot',
950
+ description:
951
+ 'Capture the whole desktop or one window (matched by title, captured with PrintWindow so a covered '
952
+ + 'window still yields its own pixels) and return the PNG path.',
953
+ properties: {
954
+ window: { type: 'string', description: 'Part of a window title; omit to capture the whole desktop.' },
955
+ path: { type: 'string', description: 'Optional destination file.' },
956
+ },
957
+ async execute(args = {}) {
958
+ return guarded({ kind: 'runtime.desktop', action: 'desktop_screenshot', target: args.window ?? 'desktop' }, async meta => {
959
+ const file = shotFile(args.path, 'desktop')
960
+ const result = await captureScreenshot({ path: file, window: args.window ?? null })
961
+ const stat = await fsp.stat(result.path)
962
+ meta.path = result.path
963
+ meta.scope = result.scope
964
+ return [
965
+ 'desktop_screenshot: ok',
966
+ `scope: ${result.scope}`,
967
+ `path: ${result.path}`,
968
+ `bytes: ${stat.size}`,
969
+ result.rect ? `rect: ${result.rect.x},${result.rect.y} ${result.rect.width}×${result.rect.height}` : null,
970
+ ].filter(Boolean).join('\n')
971
+ })
972
+ },
973
+ },
974
+ {
975
+ name: 'desktop_windows',
976
+ description: 'List visible top-level windows with their handle, title, process id, and screen rectangle.',
977
+ properties: {
978
+ filter: { type: 'string', description: 'Keep titles containing this text, ignoring case.' },
979
+ limit: { type: 'number', description: 'Maximum rows to print (default 40).' },
980
+ },
981
+ async execute(args = {}) {
982
+ return guarded({ kind: 'runtime.desktop', action: 'desktop_windows', target: args.filter ?? null }, async () => {
983
+ const windows = await listWindows()
984
+ const needle = args.filter ? String(args.filter).toLowerCase() : null
985
+ const rows = windows.filter(item => !needle || String(item.title).toLowerCase().includes(needle))
986
+ if (rows.length === 0) return `desktop_windows: 0 of ${windows.length} visible window(s) match`
987
+ const limit = Math.max(1, Math.min(200, Number(args.limit) || 40))
988
+ const lines = [`desktop_windows: ${rows.length} of ${windows.length} visible window(s)`]
989
+ for (const item of rows.slice(0, limit)) {
990
+ lines.push(
991
+ ` ${String(item.hwnd).padEnd(10)} pid ${String(item.pid).padEnd(7)} `
992
+ + `${item.rect.x},${item.rect.y} ${item.rect.width}×${item.rect.height}`
993
+ + `${item.minimized ? ' minimized' : ''} ${clip(item.title, 70)}`,
994
+ )
995
+ }
996
+ return lines.join('\n')
997
+ })
998
+ },
999
+ },
1000
+ {
1001
+ name: 'desktop_click',
1002
+ description:
1003
+ 'Click screen coordinates. By default the click is posted to the target window without activating it '
1004
+ + '(window title required). activate: true brings the window forward first and is recorded separately.',
1005
+ properties: {
1006
+ x: { type: 'number', description: 'Screen x in physical pixels.' },
1007
+ y: { type: 'number', description: 'Screen y in physical pixels.' },
1008
+ window: { type: 'string', description: 'Part of the target window title; required for a background click.' },
1009
+ activate: { type: 'boolean', description: 'Allow a foreground click (brings the window forward).' },
1010
+ right: { type: 'boolean', description: 'Right button instead of left.' },
1011
+ confirm: { type: 'boolean', description: 'Confirm when the target window title reads as irreversible.' },
1012
+ },
1013
+ required: ['x', 'y'],
1014
+ async execute(args = {}) {
1015
+ const activation = args.activate === true
1016
+ const target = `${Math.round(Number(args.x) || 0)},${Math.round(Number(args.y) || 0)}`
1017
+ return guarded({ kind: 'runtime.desktop', action: 'desktop_click', target }, async meta => {
1018
+ assertActivationAllowed(activation)
1019
+ assertConfirmable(args.window, args.confirm, { point: target })
1020
+ const result = await clickAt({
1021
+ x: Math.round(Number(args.x)),
1022
+ y: Math.round(Number(args.y)),
1023
+ window: args.window ?? null,
1024
+ activate: activation,
1025
+ right: args.right === true,
1026
+ })
1027
+ // An activation is the one thing a reader of the audit trail must be
1028
+ // able to spot without opening the tool output.
1029
+ meta.mode = result.mode
1030
+ meta.activated = result.activated === true
1031
+ if (result.hwnd) meta.hwnd = result.hwnd
1032
+ meta.window = args.window ?? null
1033
+ meta.right = args.right === true
1034
+ return [
1035
+ `desktop_click: ok (${result.mode})`,
1036
+ `point: ${result.x},${result.y}${result.hwnd ? ` hwnd: ${result.hwnd}` : ''}`,
1037
+ activation ? 'activation: yes — the window was brought forward (recorded in the audit trail)' : 'activation: no',
1038
+ ].join('\n')
1039
+ })
1040
+ },
1041
+ },
1042
+ {
1043
+ name: 'desktop_type',
1044
+ description:
1045
+ 'Type text into a window. Default is background delivery (WM_CHAR to the window\'s focused control, no '
1046
+ + 'focus change); activate: true uses SendInput after bringing the window forward.',
1047
+ properties: {
1048
+ text: { type: 'string', description: 'Text to type.' },
1049
+ window: { type: 'string', description: 'Part of the target window title.' },
1050
+ activate: { type: 'boolean', description: 'Allow foreground typing.' },
1051
+ },
1052
+ required: ['text'],
1053
+ async execute(args = {}) {
1054
+ const activation = args.activate === true
1055
+ return guarded({ kind: 'runtime.desktop', action: 'desktop_type', target: args.window ?? null }, async meta => {
1056
+ assertActivationAllowed(activation)
1057
+ const result = await typeText({
1058
+ text: String(args.text ?? ''),
1059
+ window: args.window ?? null,
1060
+ activate: activation,
1061
+ })
1062
+ meta.mode = result.mode
1063
+ meta.activated = result.activated === true
1064
+ meta.chars = result.chars
1065
+ if (result.hwnd) meta.hwnd = result.hwnd
1066
+ return [
1067
+ `desktop_type: ok (${result.mode})`,
1068
+ `characters: ${result.chars}${result.hwnd ? ` hwnd: ${result.hwnd}` : ''}`,
1069
+ activation ? 'activation: yes — recorded in the audit trail' : 'activation: no',
1070
+ 'note: posted characters reach classic Win32 controls; Chromium and Electron content often ignores them.',
1071
+ ].join('\n')
1072
+ })
1073
+ },
1074
+ },
1075
+ {
1076
+ name: 'desktop_keys',
1077
+ description:
1078
+ 'Press named keys (enter, tab, escape, f5, a, 1 …) one after another. Background by default; activate: true '
1079
+ + 'uses SendInput after bringing the target window forward.',
1080
+ properties: {
1081
+ keys: { type: 'array', items: { type: 'string' }, description: 'Key names, pressed in order.' },
1082
+ window: { type: 'string', description: 'Part of the target window title.' },
1083
+ activate: { type: 'boolean', description: 'Allow foreground key delivery.' },
1084
+ },
1085
+ required: ['keys'],
1086
+ async execute(args = {}) {
1087
+ const activation = args.activate === true
1088
+ let virtualKeys
1089
+ try {
1090
+ virtualKeys = resolveVirtualKeys(Array.isArray(args.keys) ? args.keys : [args.keys])
1091
+ } catch (error) {
1092
+ return `[error] ${error.message}`
1093
+ }
1094
+ return guarded({ kind: 'runtime.desktop', action: 'desktop_keys', target: args.window ?? null }, async meta => {
1095
+ assertActivationAllowed(activation)
1096
+ const result = await pressKeys({ virtualKeys, window: args.window ?? null, activate: activation })
1097
+ meta.mode = result.mode
1098
+ meta.activated = result.activated === true
1099
+ meta.keys = virtualKeys
1100
+ if (result.hwnd) meta.hwnd = result.hwnd
1101
+ return [
1102
+ `desktop_keys: ok (${result.mode})`,
1103
+ `keys: ${virtualKeys.join(', ')}`,
1104
+ activation ? 'activation: yes — recorded in the audit trail' : 'activation: no',
1105
+ ].join('\n')
1106
+ })
1107
+ },
1108
+ },
1109
+ ]
1110
+
1111
+ const statusTool = [{
1112
+ name: 'runtime_status',
1113
+ description: 'Report whether runtime control is stopped, which halves are registered, and the browser state.',
1114
+ properties: {},
1115
+ async execute() {
1116
+ const state = stopState()
1117
+ const executable = findBrowserExecutable({ explicit: browserConfig.executablePath ?? null, env })
1118
+ return [
1119
+ 'runtime_status',
1120
+ `enabled: ${enabled ? 'yes' : 'no'}`,
1121
+ `browser tools: ${browserTools.length} (headless ${browserConfig.headless !== false}, `
1122
+ + `hosts ${(browserConfig.allowedHosts.length ? browserConfig.allowedHosts : LOOPBACK_HOSTS).join(', ')})`,
1123
+ `browser mode: ${browserConfig.attachPort !== null && browserConfig.attachPort !== undefined
1124
+ ? `attach to 127.0.0.1:${browserConfig.attachPort} (the user's own profile)`
1125
+ : `launch with a ${browserConfig.userDataDir ? `persistent profile at ${browserConfig.userDataDir}` : 'fresh temporary profile'}`}`,
1126
+ `desktop tools: ${desktopTools.length} (activation ${allowActivation ? 'allowed' : 'disabled'})`,
1127
+ `stop switch: ${state.stopped ? `SET by ${state.source}` : `clear (${stopFile})`}`,
1128
+ `screenshots: ${shotDir}`,
1129
+ `browser executable: ${executable ?? 'not found'}`,
1130
+ `browser session: ${describeSession(session)}`,
1131
+ ].join('\n')
1132
+ },
1133
+ }]
1134
+
1135
+ return {
1136
+ enabled,
1137
+ stopFile,
1138
+ shotDir,
1139
+ stopState,
1140
+ checkNavigation: url => checkNavigation(url, { allowedHosts: browserConfig.allowedHosts }),
1141
+ irreversibleIntent,
1142
+ tools: enabled ? [...browserTools, ...desktopTools, ...statusTool] : [],
1143
+ /** Close anything this layer opened; the host calls it on unload. */
1144
+ async dispose() {
1145
+ if (!session) return
1146
+ const closing = session
1147
+ session = null
1148
+ await closing.close().catch(error => warn(`runtime: cannot close the browser: ${error?.message ?? error}`))
1149
+ },
1150
+ }
1151
+ }