dsh-inner-browser-use 0.45.0 → 0.47.0

package/rest.js

@@ -0,0 +1,124 @@
+/* When to put the browser down.
+ *
+ * A fixed fifteen minutes is either too long (a chat that asks one question
+ * and walks away leaves a whole Chrome standing for a quarter of an hour) or
+ * too short (a long task that thinks for a minute between reads) — and the
+ * number that tells the two apart is already in the chat, in the gaps between
+ * one call and the next. So the browser learns its own rhythm: the 95th
+ * percentile of recent gaps says how long this chat pauses while it is still
+ * working, and the rest window is a multiple of that, floored and capped so a
+ * fast chat still gets a minute of grace and a slow one is not kept forever.
+ *
+ * Only the last few dozen gaps count. A stale rhythm from an hour ago is not
+ * evidence about now, and a sliding window forgets it without a decay constant
+ * to tune. The percentile is exact over that window: cheap at this size, and
+ * not an estimate that can drift.
+ */
+
+/** Shortest rest window: a chat that works in two-second steps still gets grace. */
+export const MIN_REST_MS = 90_000
+/** Longest rest window: nothing learned may keep a browser up for longer than this. */
+export const MAX_REST_MS = 15 * 60_000
+/** Shortest quiet window: how soon an idle chat stops paying for a picture nobody sees. */
+export const MIN_QUIET_MS = 20_000
+/** Longest quiet window. */
+export const MAX_QUIET_MS = 2 * 60_000
+/** How many recent gaps make up the learned rhythm. */
+const WINDOW = 64
+/** Rest at this multiple of the learned p95: long enough to sit through a pause. */
+const REST_FACTOR = 6
+/** Quiet at this multiple: two slow steps in a row is a pause, not a break. */
+const QUIET_FACTOR = 2
+
+/**
+ * @param {number} value - what to keep in range.
+ * @param {number} low - smallest allowed.
+ * @param {number} high - largest allowed.
+ * @returns {number} `value` inside `[low, high]`.
+ */
+function clamp(value, low, high) {
+  if (!Number.isFinite(value)) return low
+  return Math.min(high, Math.max(low, value))
+}
+
+/**
+ * The recent gaps between one use of this browser and the next, and what they
+ * say about how long a pause is still "working" rather than "gone".
+ */
+export class GapClock {
+  /** @param {{window?: number}} [options] - how many gaps to keep. */
+  constructor(options = {}) {
+    /** @type {number} when the browser was last used, in ms. */
+    this.last = 0
+    /** @type {number[]} the recent gaps, oldest first. */
+    this.gaps = []
+    this.window = Math.max(4, Number(options.window ?? WINDOW) || WINDOW)
+    /** @type {number} how many gaps were seen at all, for reporting. */
+    this.seen = 0
+  }
+
+  /**
+   * Notes a use now and returns the gap it closed.
+   * @param {number} [now] - the moment of this use.
+   * @returns {number} the gap in ms, or 0 when there is no rhythm yet.
+   */
+  record(now = Date.now()) {
+    const at = Number(now)
+    const was = Number(this.last)
+    this.last = at
+    if (!Number.isFinite(was) || was <= 0 || !Number.isFinite(at) || at <= was) return 0
+    const gap = at - was
+    /* A gap longer than the longest rest window is a new sitting, not a step:
+       folding it in would teach the browser that hours are normal. */
+    if (gap > MAX_REST_MS) return 0
+    this.gaps.push(gap)
+    if (this.gaps.length > this.window) this.gaps.shift()
+    this.seen += 1
+    return gap
+  }
+
+  /**
+   * @param {number} q - a fraction in (0, 1].
+   * @returns {number} that percentile of the kept gaps, or 0 with no rhythm.
+   */
+  quantile(q = 0.95) {
+    const size = this.gaps.length
+    if (size === 0) return 0
+    const sorted = [...this.gaps].sort((a, b) => a - b)
+    const at = clamp(Math.ceil(q * size) - 1, 0, size - 1)
+    return sorted[at]
+  }
+
+  /** @returns {number} ms of silence after which the browser may be put down. */
+  restAfter() {
+    if (this.gaps.length === 0) return MIN_REST_MS
+    return clamp(this.quantile(0.95) * REST_FACTOR, MIN_REST_MS, MAX_REST_MS)
+  }
+
+  /** @returns {number} ms of silence after which an unwatched page may stop painting. */
+  quietAfter() {
+    if (this.gaps.length === 0) return MIN_QUIET_MS
+    return clamp(this.quantile(0.95) * QUIET_FACTOR, MIN_QUIET_MS, MAX_QUIET_MS)
+  }
+
+  /** @returns {number} the middle gap, for a report that has to be readable. */
+  typical() {
+    return this.quantile(0.5)
+  }
+}
+
+/**
+ * What the browser should do about time passing right now.
+ * @param {{now: number, lastUse: number, restAt: number, watched: number, quietAfter: number}} state - clocks and viewers.
+ * @returns {'awake'|'quiet'|'rest'} `rest` means nobody is watching and the window ran out.
+ */
+export function decide(state) {
+  const now = Number(state.now ?? 0)
+  const watched = Number(state.watched ?? 0)
+  const lastUse = Number(state.lastUse ?? 0)
+  const restAt = Number(state.restAt ?? 0)
+  if (watched > 0) return lastUse > 0 && now - lastUse >= Number(state.quietAfter ?? MIN_QUIET_MS) ? 'quiet' : 'awake'
+  if (restAt > 0 && now >= restAt) return 'rest'
+  if (lastUse > 0 && now - lastUse >= Number(state.quietAfter ?? MIN_QUIET_MS)) return 'quiet'
+  return 'awake'
+}

package/scripts/bench-resource.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * What this browser costs, in the same terms the neighbours are measured in.
+ *
+ *   node scripts/bench-resource.mjs [--json out.json]
+ *
+ * Cold start, action round trip, idle memory and CPU with a page open, the
+ * reversible freeze, the rest, and the wake. One process tree, one page, the
+ * same protocol `docs/RESOURCES.md` uses for Playwright MCP and Chrome DevTools
+ * MCP — so the numbers can sit in one table.
+ */
+import { createServer } from 'node:http'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+process.env.DSH_INNER_BROWSER_STATE_DIR = mkdtempSync(join(tmpdir(), 'dsh-bench-'))
+const sink = (() => {
+  const at = process.argv.indexOf('--json')
+  return at === -1 ? null : process.argv[at + 1]
+})()
+
+const server = createServer((request, response) => {
+  response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+  response.end('<!doctype html><meta charset="utf-8"><title>bench</title><h1>bench</h1>' +
+    `<p>${'the page has to cost what a page costs. '.repeat(40)}</p>` +
+    '<ul>' + Array.from({ length: 60 }, (_, i) => `<li><a href="/row-${i}">row ${i}</a></li>`).join('') + '</ul>')
+})
+await new Promise((done) => server.listen(0, '127.0.0.1', done))
+const url = `http://127.0.0.1:${server.address().port}/page`
+
+const { Sidecar } = await import('../sidecar.js')
+const { sidecarTools, sessionScope, workScope } = await import('../tools.js')
+
+const wait = (ms) => new Promise((settle) => setTimeout(settle, ms))
+const sidecar = new Sidecar({ profile: 'bench-resource', headless: true, restFloor: 1200, restCeiling: 1600, budgetMb: 4000 })
+const tools = sidecarTools(sidecar, { byChat: new Map() }, {})
+const tool = (name) => tools.find((one) => one.name === name)
+const cwd = mkdtempSync(join(tmpdir(), 'dsh-bench-cwd-'))
+const chat = 'session-bench-resource'
+const run = (name, args) => sessionScope.run(chat, () => workScope.run(cwd, () => tool(name).execute(args, { agent: { id: chat } })))
+const text = (said) => String(said?.text ?? '')
+
+/* ps once per sample: pid, parent, cpu, rss. macOS sums shared pages per
+   process, so the total overstates real memory; the neighbours are measured the
+   same way, which is the only way the numbers compare. */
+function tree(root) {
+  const rows = execFileSync('ps', ['-Ao', 'pid=,ppid=,%cpu=,rss='], { encoding: 'utf8' })
+    .trim().split('\n').map((line) => line.trim().split(/\s+/)).map(([pid, ppid, cpu, rss]) => ({ pid: Number(pid), ppid: Number(ppid), cpu: Number(cpu), rss: Number(rss) }))
+  const byParent = new Map()
+  for (const row of rows) {
+    if (!byParent.has(row.ppid)) byParent.set(row.ppid, [])
+    byParent.get(row.ppid).push(row)
+  }
+  const out = []
+  const walk = (pid) => {
+    for (const child of byParent.get(pid) ?? []) {
+      out.push(child)
+      walk(child.pid)
+    }
+  }
+  walk(root)
+  return out
+}
+function weigh() {
+  const root = sidecar.child?.pid
+  if (!root) return { mb: 0, cpu: 0, procs: 0 }
+  const rows = tree(root)
+  return {
+    mb: Math.round(rows.reduce((sum, row) => sum + row.rss, 0) / 1024),
+    cpu: Number(rows.reduce((sum, row) => sum + row.cpu, 0).toFixed(1)),
+    procs: rows.length + 1,
+  }
+}
+async function cpuOver(ms, every = 5000) {
+  const samples = []
+  const until = Date.now() + ms
+  while (Date.now() < until) {
+    samples.push(weigh().cpu)
+    await wait(Math.min(every, Math.max(0, until - Date.now())))
+  }
+  return {
+    samples_pct: samples,
+    avg_pct: Number((samples.reduce((a, b) => a + b, 0) / Math.max(1, samples.length)).toFixed(2)),
+  }
+}
+
+const report = { generated_at: new Date().toISOString(), host: { arch: process.arch, platform: process.platform }, version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version }
+let failed = 0
+const check = (ok, what) => {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${what}`)
+  if (!ok) failed += 1
+}
+
+try {
+  /* Keep the rest out of the way while the page is measured. */
+  const coldAt = Date.now()
+  await run('browser_open', { url })
+  const first = text(await run('browser_view', {}))
+  report.cold_start_ms = Date.now() - coldAt
+  check(first.includes('bench'), `cold start ${String(report.cold_start_ms)} ms`)
+  check(report.cold_start_ms < 6000, 'cold start under six seconds')
+
+  const readAt = Date.now()
+  const read = text(await run('browser_read', {}))
+  report.read_ms = Date.now() - readAt
+  report.read_chars = read.length
+  check(report.read_ms < 4000 && read.length > 200, `a read is ${String(report.read_ms)} ms and ${String(report.read_chars)} chars`)
+
+  const evalAt = Date.now()
+  for (let i = 0; i < 5; i += 1) await run('browser_eval', { code: 'document.title' })
+  report.action_rtt_ms = Math.round((Date.now() - evalAt) / 5)
+  check(report.action_rtt_ms < 500, `an action round trip is ${String(report.action_rtt_ms)} ms`)
+
+  const up = weigh()
+  report.open_rss_mb = up.mb
+  report.open_procs = up.procs
+  check(up.mb > 0, `a page open costs ${String(up.mb)} MB in ${String(up.procs)} processes`)
+
+  /* The first seconds after a load are the page finishing; the number that
+     matters is what it costs once it has finished. */
+  sidecar.touch(600_000)
+  await wait(5000)
+  report.idle_cpu = await cpuOver(30_000)
+  sidecar.touch(600_000)
+  await wait(2000)
+  const idle = weigh()
+  report.idle_rss_mb = idle.mb
+  check(true, `idle 30 s: ${String(idle.mb)} MB, ${String(report.idle_cpu.avg_pct)} % cpu`)
+
+  /* The reversible park: the page keeps its DOM, the process keeps its share. */
+  const frozenAt = Date.now()
+  await sidecar.pageFor(chat)?.freeze()
+  await wait(3000)
+  const frozen = weigh()
+  report.freeze_ms = Date.now() - frozenAt
+  report.frozen_rss_mb = frozen.mb
+  const frozenCpu = await cpuOver(6000)
+  report.frozen_cpu_pct = frozenCpu.avg_pct
+  check(report.frozen_rss_mb <= idle.mb + 8, `frozen costs ${String(report.frozen_rss_mb)} MB, was ${String(idle.mb)} MB`)
+
+  const thawAt = Date.now()
+  await sidecar.pageFor(chat)?.thaw()
+  const quick = text(await run('browser_view', {}))
+  report.thaw_ms = Date.now() - thawAt
+  check(quick.includes('bench') || quick.includes('nothing changed'), `thaw took ${String(report.thaw_ms)} ms`)
+
+  /* The full release and the wake that costs a cold launch. */
+  sidecar.touch(600)
+  for (let i = 0; i < 60; i += 1) {
+    await wait(200)
+    if ((await sidecar.state()).alive !== true) break
+  }
+  const asleep = await sidecar.state()
+  report.rested = asleep.alive !== true
+  report.asleep_mb = asleep.memory
+  check(report.rested && asleep.memory === 0, `rest releases everything (${String(asleep.memory)} bytes)`)
+
+  const wakeAt = Date.now()
+  const back = text(await run('browser_view', {}))
+  report.wake_ms = Date.now() - wakeAt
+  check(sidecar.pageFor(chat)?.url === url, `wake came back to ${String(sidecar.pageFor(chat)?.url)} in ${String(report.wake_ms)} ms`)
+  check(back.length > 0, 'the page still reads after the wake')
+} finally {
+  server.close()
+  await sidecar.shutdown().catch(() => {})
+}
+
+console.log('\n' + JSON.stringify(report, null, 2))
+if (sink !== null) writeFileSync(sink, JSON.stringify(report, null, 2) + '\n')
+console.log(failed === 0 ? '\nresource numbers hold.' : `\n${String(failed)} bench checks failed.`)
+process.exitCode = failed === 0 ? 0 : 1

package/scripts/check-rest.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * What putting the browser to rest costs, and what waking it back up buys.
+ *
+ *   node scripts/check-rest.mjs
+ *
+ * Opens a page, lets the rest window run out with nobody watching, and checks
+ * that the browser really went away — no process, no memory, a reason on the
+ * record — and that the next tool call brings it back with the same page, in
+ * well under the time a cold launch takes. Exits non-zero when rest gets
+ * expensive, or when waking loses the page.
+ */
+import { createServer } from 'node:http'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+process.env.DSH_INNER_BROWSER_STATE_DIR = mkdtempSync(join(tmpdir(), 'dsh-rest-'))
+
+const server = createServer((request, response) => {
+  response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+  response.end('<!doctype html><meta charset="utf-8"><title>rest check</title><h1>rest check</h1><p>this page has to survive a rest.</p>')
+})
+await new Promise((done) => server.listen(0, '127.0.0.1', done))
+const url = `http://127.0.0.1:${server.address().port}/page`
+
+const { Sidecar } = await import('../sidecar.js')
+const { sidecarTools, sessionScope, workScope } = await import('../tools.js')
+
+const wait = (ms) => new Promise((settle) => setTimeout(settle, ms))
+/* A short window on purpose: the point is the chain, not the length. */
+const sidecar = new Sidecar({ profile: 'rest-check', headless: true, restFloor: 1200, restCeiling: 1600, budgetMb: 4000 })
+const tools = sidecarTools(sidecar, { byChat: new Map() }, {})
+const tool = (name) => tools.find((one) => one.name === name)
+const cwd = mkdtempSync(join(tmpdir(), 'dsh-rest-cwd-'))
+/* Chats are `session-…` ids: the tab memory on disk only keeps those, and a
+   throwaway id would lose the page across a rest instead of testing that it
+   is kept. */
+const chat = 'session-rest-check'
+const run = (name, args) => sessionScope.run(chat, () => workScope.run(cwd, () => tool(name).execute(args, { agent: { id: chat } })))
+let failed = 0
+const check = (ok, what) => {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${what}`)
+  if (!ok) failed += 1
+}
+const text = (said) => String(said?.text ?? '')
+let sidecarDone = false
+try {
+  await run('browser_open', { url })
+  const before = text(await run('browser_view', {}))
+  check(before.includes('this page has to survive a rest'), 'the page opened')
+  const upText = text(await run('browser_state', {}))
+  check(upText.includes('rests in') || upText.includes('no rest scheduled'), `the state names the rest (${upText.split('\n').filter((row) => row.includes('rest')).join(' / ')})`)
+  const up = await sidecar.state()
+  check(up.alive === true && up.memory > 0, `the browser is up and costs ${String(up.memory)} bytes`)
+
+  /* Nobody is watching: this is exactly the state the pane closes into. */
+  sidecar.touch(1200)
+  const restAt = Date.now() + 1200
+  for (let i = 0; i < 60; i += 1) {
+    await wait(250)
+    const said = await sidecar.state()
+    if (said.alive !== true) break
+    if (Date.now() > restAt + 15_000) break
+  }
+  const asleepText = text(await run('browser_state', {}))
+  check(asleepText.includes('stopped'), 'the state says the browser is stopped')
+  const asleep = await sidecar.state()
+  check(asleep.alive !== true, 'the browser went away when its rest ran out')
+  check(asleep.memory === 0, 'no memory is held while it rests')
+  check(asleep.rests >= 1, `the rest was counted (${String(asleep.rests)})`)
+  check(String(asleep.error).includes('put away') || String(asleep.restNote).length > 0, `it said why (${String(asleep.error || asleep.restNote)})`)
+
+  const asked = Date.now()
+  const after = text(await run('browser_view', {}))
+  const woke = Date.now() - asked
+  const back = await sidecar.state()
+  check(back.alive === true, 'the next call brought it back')
+  /* The address is the proof: a blank mirror would say `about:blank`, and the
+     read is deduplicated against the picture from before the rest. */
+  check(sidecar.pageFor(chat)?.url === url, `it came back to the same address (${String(sidecar.pageFor(chat)?.url)})`)
+  check(after.includes('this page has to survive a rest') || after.includes('nothing changed since the last read'), 'the page still says what it said before the rest')
+  check(woke < 4000, `the wake took ${String(woke)} ms`)
+  check(back.wakeMs > 0 && back.wakeMs <= woke + 50, `the sidecar timed its own wake (${String(back.wakeMs)} ms)`)
+  check(back.rests >= 1, 'the count survives the wake')
+} finally {
+  server.close()
+  if (!sidecarDone) await sidecar.shutdown().catch(() => {})
+}
+console.log(failed === 0 ? '\nrest and wake hold.' : `\n${String(failed)} rest checks failed.`)
+process.exitCode = failed === 0 ? 0 : 1

package/scripts/soak.mjs

@@ -41,12 +41,15 @@ const docUrl = `http://127.0.0.1:${port}/doc`
 const { Sidecar } = await import('../sidecar.js')
 const { sidecarTools, sessionScope, workScope } = await import('../tools.js')
 
-const sidecar = new Sidecar({ profile: 'soak', headless: true })
+/* A short rest window on purpose: the run has to cross the sleep/wake chain
+   often enough to see it leak, not just remember that it works once. */
+const sidecar = new Sidecar({ profile: 'soak', headless: true, restFloor: 1200, restCeiling: 1600 })
 const tools = sidecarTools(sidecar, { byChat: new Map() }, {})
 const tool = (name) => tools.find((one) => one.name === name)
 const cwd = mkdtempSync(join(tmpdir(), 'dsh-soak-cwd-'))
 /* Same binding the plugin does: the chat and the project a call belongs to. */
-const run = (name, args) => sessionScope.run('soak', () => workScope.run(cwd, () => tool(name).execute(args, { agent: { id: 'soak' } })))
+const chat = 'session-soak'
+const run = (name, args) => sessionScope.run(chat, () => workScope.run(cwd, () => tool(name).execute(args, { agent: { id: chat } })))
 const text = (said) => String(said?.text ?? '')
 
 /* macOS reports every renderer's RSS in full, shared pages included, so a
@@ -63,11 +66,13 @@ const check = (ok, what) => {
 const startedAt = Date.now()
 try {
   await sidecar.launch('about:blank')
-  await sidecar.watch(() => {})
-  await sidecar.ensure({ session: 'soak' })
+  /* No mirror sink here: a watcher is what keeps a browser awake, and this run
+     has to reach the rest the way a chat with its pane closed does. */
+  await sidecar.ensure({ session: chat })
 
   let reads = 0
   let snapshots = 0
+  let rests = 0
   for (let i = 0; i < cycles; i += 1) {
     const url = i % 2 === 0 ? appUrl : docUrl
     await run('browser_open', { url })
@@ -86,6 +91,19 @@ try {
       samples.push({ cycle: i + 1, mb, pages: Number(state?.pages ?? 0) })
       console.log(`     cycle ${String(i + 1).padStart(3)} · ${String(mb)} MB · pages ${String(state?.pages)}`)
     }
+    /* Every eighth cycle the browser is left alone until its rest runs out:
+       the whole tree has to go, memory included, and the next cycle has to
+       bring it back without a second page or a lost address. */
+    if (i % 8 === 7) {
+      sidecar.touch(1200)
+      for (let step = 0; step < 40 && sidecar.alive; step += 1) {
+        await new Promise((settle) => setTimeout(settle, 250))
+      }
+      const down = await sidecar.state()
+      if (down.alive === true) throw new Error('the browser did not rest inside 10 s')
+      if (Number(down.memory ?? 0) !== 0) throw new Error('memory was still held while resting')
+      rests += 1
+    }
     /* A quiet moment, so a leak in the close/reopen path is not hidden by the
        next navigation arriving before the old page is gone. */
     if (i % 6 === 5) await new Promise((settle) => setTimeout(settle, 250))
@@ -99,7 +117,9 @@ try {
   check(samples.every((one) => one.pages <= 1), `one page per chat is kept (max ${String(Math.max(...samples.map((one) => one.pages)))})`)
   check(last.mb < ceilingMb, `RSS stays inside this machine's ceiling (${String(last.mb)} < ${String(ceilingMb)} MB)`)
   check(growth < 250, `RSS growth over ${String(cycles)} cycles is bounded (${growth >= 0 ? '+' : ''}${String(growth)} MB)`)
-  console.log(`soak: ${failed === 0 ? 'ok' : `${String(failed)} failed`} · ${String(cycles)} cycles, ${String(seconds)} s, rss ${String(first.mb)} → ${String(last.mb)} MB, pages ${String(last.pages)}, ${String(snapshots)} shots, ${String(reads)} reads`)
+  check(rests > 0, `the browser rested ${String(rests)} times and each rest released its memory`)
+  check(Number(last.pages ?? 0) <= 1, 'the rest and wake chain never left a second page behind')
+  console.log(`soak: ${failed === 0 ? 'ok' : `${String(failed)} failed`} · ${String(cycles)} cycles, ${String(seconds)} s, rss ${String(first.mb)} → ${String(last.mb)} MB, pages ${String(last.pages)}, ${String(snapshots)} shots, ${String(reads)} reads, ${String(rests)} rests`)
 } catch (error) {
   failed += 1
   console.log('FAIL ' + String(error?.stack ?? error))