dsh-inner-browser-use 0.44.0 → 0.46.0

package/pixels.js

@@ -0,0 +1,217 @@
+/**
+ * The screen without the picture: a page that draws itself — a game, a canvas
+ * app, a Flash movie — has nothing a text tree can read, and a screenshot costs
+ * image tokens on every step. This turns the screen into a small grid of
+ * characters instead: one letter per block of pixels, the same letters for the
+ * same colours, so a caller can see what changed by reading text.
+ *
+ * Everything here is pure: decode, average, quantise, diff. No browser, no
+ * files, so it can be tested without one.
+ */
+
+import { inflateSync } from 'node:zlib'
+
+/** Colours a screen block can be called, most common things first. */
+export const PALETTE = [
+  { char: '.', name: 'black', rgb: [16, 16, 16] },
+  { char: ':', name: 'dark', rgb: [64, 64, 64] },
+  { char: '-', name: 'gray', rgb: [112, 112, 112] },
+  { char: '+', name: 'light', rgb: [168, 168, 168] },
+  { char: '*', name: 'bright', rgb: [216, 216, 216] },
+  { char: '#', name: 'white', rgb: [248, 248, 248] },
+  { char: 'r', name: 'red', rgb: [208, 48, 48] },
+  { char: 'g', name: 'green', rgb: [64, 176, 72] },
+  { char: 'b', name: 'blue', rgb: [56, 104, 216] },
+  { char: 'y', name: 'yellow', rgb: [232, 208, 72] },
+  { char: 'c', name: 'cyan', rgb: [64, 200, 208] },
+  { char: 'm', name: 'magenta', rgb: [200, 72, 200] },
+  { char: 'o', name: 'orange', rgb: [224, 136, 48] },
+  { char: 'p', name: 'purple', rgb: [112, 56, 168] },
+  { char: 'n', name: 'brown', rgb: [136, 88, 48] },
+]
+
+/**
+ * The letter closest to a colour. Grays and bright colours are judged by eye
+ * first so a dark sky does not read as blue and a red button does not read as
+ * brown.
+ * @param {number} r - red 0..255.
+ * @param {number} g - green 0..255.
+ * @param {number} b - blue 0..255.
+ * @returns {string} one character.
+ */
+export function quantize(r, g, b) {
+  /* Red, green and blue are counted more heavily than a plain euclidean
+     distance would: two colours a person calls different should not collapse
+     into the same letter. */
+  const red = r * 1.30
+  const green = g * 1.15
+  const blue = b * 0.90
+  let best = PALETTE[0].char
+  let near = Infinity
+  for (const entry of PALETTE) {
+    const dr = red - entry.rgb[0] * 1.30
+    const dg = green - entry.rgb[1] * 1.15
+    const db = blue - entry.rgb[2] * 0.90
+    const d = dr * dr + dg * dg + db * db
+    if (d < near) {
+      near = d
+      best = entry.char
+    }
+  }
+  return best
+}
+
+/**
+ * Read a PNG made by Chrome into plain pixels. Chrome writes 8-bit
+ * non-interlaced images, RGB or RGBA; anything else is refused with a reason
+ * rather than a guess.
+ * @param {Buffer} file - the PNG bytes.
+ * @returns {{width: number, height: number, data: Uint8Array, channels: number}} pixels, row-major.
+ */
+export function decodePng(file) {
+  const bytes = new Uint8Array(file.buffer !== undefined && file.byteOffset === 0 && file.byteLength === file.buffer.byteLength ? file.buffer : file)
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10]
+  for (let i = 0; i < signature.length; i += 1) {
+    if (bytes[i] !== signature[i]) throw new Error('pixels: not a PNG')
+  }
+  let width = 0
+  let height = 0
+  let depth = 0
+  let type = 0
+  let interlace = 0
+  const chunks = []
+  let at = 8
+  while (at + 8 <= bytes.length) {
+    const length = view.getUint32(at)
+    const name = String.fromCharCode(bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7])
+    const body = bytes.subarray(at + 8, at + 8 + length)
+    if (name === 'IHDR') {
+      width = view.getUint32(at + 8)
+      height = view.getUint32(at + 12)
+      depth = body[8]
+      type = body[9]
+      interlace = body[12]
+    } else if (name === 'IDAT') chunks.push(body)
+    else if (name === 'IEND') break
+    at += 12 + length
+  }
+  if (depth !== 8) throw new Error(`pixels: PNG depth ${depth} is not 8`)
+  const channels = type === 6 ? 4 : type === 2 ? 3 : type === 0 ? 1 : 0
+  if (channels === 0) throw new Error(`pixels: PNG colour type ${type} is not RGB`)
+  if (interlace !== 0) throw new Error('pixels: interlaced PNG is not supported')
+  const packed = inflateSync(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))))
+  const stride = width * channels
+  const out = new Uint8Array(width * height * channels)
+  let raw = 0
+  for (let y = 0; y < height; y += 1) {
+    const filter = packed[raw]
+    raw += 1
+    const row = out.subarray(y * stride, (y + 1) * stride)
+    const up = y === 0 ? null : out.subarray((y - 1) * stride, y * stride)
+    for (let x = 0; x < stride; x += 1) {
+      const value = packed[raw + x]
+      const left = x >= channels ? row[x - channels] : 0
+      const above = up === null ? 0 : up[x]
+      const corner = up !== null && x >= channels ? up[x - channels] : 0
+      let said = value
+      if (filter === 1) said = value + left
+      else if (filter === 2) said = value + above
+      else if (filter === 3) said = value + ((left + above) >> 1)
+      else if (filter === 4) {
+        const guess = left + above - corner
+        const dl = Math.abs(guess - left)
+        const du = Math.abs(guess - above)
+        const dc = Math.abs(guess - corner)
+        said = value + (dl <= du && dl <= dc ? left : du <= dc ? above : corner)
+      } else if (filter !== 0) throw new Error(`pixels: PNG filter ${filter} is not known`)
+      row[x] = said & 0xff
+    }
+    raw += stride
+  }
+  return { width, height, data: out, channels }
+}
+
+/**
+ * Average each block of the picture into one character.
+ * @param {{width: number, height: number, data: Uint8Array, channels: number}} png - decoded picture.
+ * @param {number} cols - cells across.
+ * @returns {{rows: string[], cols: number, rowCount: number, blockW: number, blockH: number}} the grid.
+ */
+export function gridOf(png, cols) {
+  const across = Math.min(64, Math.max(4, Math.round(cols)))
+  const rows = Math.min(64, Math.max(2, Math.round((across * png.height) / Math.max(1, png.width))))
+  const blockW = png.width / across
+  const blockH = png.height / rows
+  const lines = []
+  let seen = ''
+  for (let ry = 0; ry < rows; ry += 1) {
+    let line = ''
+    for (let rx = 0; rx < across; rx += 1) {
+      const x0 = Math.floor(rx * blockW)
+      const x1 = Math.max(x0 + 1, Math.min(png.width, Math.floor((rx + 1) * blockW)))
+      const y0 = Math.floor(ry * blockH)
+      const y1 = Math.max(y0 + 1, Math.min(png.height, Math.floor((ry + 1) * blockH)))
+      let r = 0
+      let g = 0
+      let b = 0
+      let n = 0
+      for (let y = y0; y < y1; y += 1) {
+        for (let x = x0; x < x1; x += 1) {
+          const at = (y * png.width + x) * png.channels
+          r += png.data[at]
+          g += png.data[at + 1] ?? png.data[at]
+          b += png.data[at + 2] ?? png.data[at]
+          n += 1
+        }
+      }
+      line += quantize(r / n, g / n, b / n)
+    }
+    lines.push(line)
+    seen += line
+  }
+  return { rows: lines, cols: across, rowCount: rows, blockW, blockH }
+}
+
+/**
+ * What changed between two grids of the same screen.
+ * @param {string[]} before - earlier rows.
+ * @param {string[]} after - later rows.
+ * @returns {{cells: number, box: {x: number, y: number, w: number, h: number} | null}} the change.
+ */
+export function diffGrid(before, after) {
+  if (before.length !== after.length || before.some((row, i) => row.length !== after[i].length)) {
+    return { cells: Number.POSITIVE_INFINITY, box: null }
+  }
+  let cells = 0
+  let x0 = Infinity
+  let y0 = Infinity
+  let x1 = -1
+  let y1 = -1
+  for (let y = 0; y < after.length; y += 1) {
+    for (let x = 0; x < after[y].length; x += 1) {
+      if (before[y][x] === after[y][x]) continue
+      cells += 1
+      if (x < x0) x0 = x
+      if (y < y0) y0 = y
+      if (x > x1) x1 = x
+      if (y > y1) y1 = y
+    }
+  }
+  if (cells === 0) return { cells: 0, box: null }
+  return { cells, box: { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 } }
+}
+
+/**
+ * Cut one box out of a grid, with a cell of margin around it.
+ * @param {string[]} rows - the whole grid.
+ * @param {{x: number, y: number, w: number, h: number}} box - changed cells.
+ * @returns {{rows: string[], x: number, y: number}} the cut grid and where it starts.
+ */
+export function around(rows, box) {
+  const x = Math.max(0, box.x - 1)
+  const y = Math.max(0, box.y - 1)
+  const to = Math.min(rows[0].length, box.x + box.w + 1)
+  const down = Math.min(rows.length, box.y + box.h + 1)
+  return { rows: rows.slice(y, down).map((row) => row.slice(x, to)), x, y }
+}

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/check-flash-tools.mjs

@@ -28,6 +28,10 @@ try {
   await sidecar.watch(() => {})
   await sidecar.page.navigate(url).catch(() => {})
   await wait(9000)
+  /* A port that answers is not a plugin that loaded: ask the page, because a
+     missing plugin shows up as a black movie and reads like a slow one. */
+  const plugin = sidecar.flashCheck ?? (await sidecar.checkFlash())
+  const pluginOk = plugin?.ok === true
   const said = []
   const timed = async (name, args) => {
     const started = Date.now()
@@ -64,8 +68,8 @@ try {
      up whole. Otherwise a bad minute at the site reads as a regression here. */
   const degraded = said[0].chars < 300 || said[0].text.includes('page trouble')
   const fast = () => degraded || (median(clicks) < 120 && median(types) < 120)
-  ok = clicks.length === 5 && fast() && clicks.every(within) && types.every(within) && Number(last?.chars ?? 0) > 0 && viewAgain.chars < said[0].chars && viewThird.chars < said[0].chars
-  console.log(JSON.stringify({ view: said[0], clickMedianMs: median(clicks), clickMaxMs: Math.max(...clicks.map((one) => one.ms)), typeMedianMs: median(types), typeMaxMs: Math.max(...types.map((one) => one.ms)), clickChars: clicks[0].chars, typeChars: types[0].chars, viewAgainChars: viewAgain.chars, viewThirdChars: viewThird.chars, viewAgainText: viewAgain.text, degraded, ok }))
+  ok = pluginOk && clicks.length === 5 && fast() && clicks.every(within) && types.every(within) && Number(last?.chars ?? 0) > 0 && viewAgain.chars < said[0].chars && viewThird.chars < said[0].chars
+  console.log(JSON.stringify({ plugin, view: said[0], clickMedianMs: median(clicks), clickMaxMs: Math.max(...clicks.map((one) => one.ms)), typeMedianMs: median(types), typeMaxMs: Math.max(...types.map((one) => one.ms)), clickChars: clicks[0].chars, typeChars: types[0].chars, viewAgainChars: viewAgain.chars, viewThirdChars: viewThird.chars, viewAgainText: viewAgain.text, degraded, ok }))
 } catch (error) {
   console.log(JSON.stringify({ ok: false, error: String(error?.message ?? error).slice(0, 160) }))
 } finally {

package/scripts/check-look.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * browser_look against a real Chrome and a page that draws itself.
+ *
+ *   node scripts/check-look.mjs
+ *
+ * Paints a canvas, reads the screen as letters, paints one square, reads again
+ * and reports whether the second read named only that square. Exits non-zero
+ * when the tool stops being able to see a self-drawn page.
+ */
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+process.env.DSH_INNER_BROWSER_STATE_DIR = mkdtempSync(join(tmpdir(), 'dsh-look-'))
+const folder = mkdtempSync(join(tmpdir(), 'dsh-look-page-'))
+writeFileSync(join(folder, 'index.html'), `<!doctype html><meta charset="utf-8">
+<style>html,body{margin:0;height:100%;background:#101010}canvas{display:block}</style>
+<canvas id="c"></canvas>
+<script>
+const c = document.getElementById('c')
+c.width = innerWidth
+c.height = innerHeight
+const g = c.getContext('2d')
+g.fillStyle = '#202020'
+g.fillRect(0, 0, c.width, c.height)
+g.fillStyle = '#e0e0e0'
+g.fillRect(0, 0, c.width, c.height / 2)
+</script>`)
+
+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: 'look-check', headless: true })
+const tools = sidecarTools(sidecar, { byChat: new Map() }, {})
+const tool = (name) => tools.find((one) => one.name === name)
+/* Every tool path reads the chat from the scope it is called in, so the check
+   binds the same chat the plugin would bind for a real conversation. */
+const run = (name, args) => sessionScope.run('look-check', () => workScope.run(folder, () => tool(name).execute(args, { agent: { id: 'look-check' } })))
+let failed = 0
+const check = (ok, what) => {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${what}`)
+  if (!ok) failed += 1
+}
+try {
+  await sidecar.launch('about:blank')
+  await sidecar.watch(() => {})
+  const page = await sidecar.ensure({ session: 'look-check' })
+  await page.navigate(pathToFileURL(join(folder, 'index.html')).href).catch(() => {})
+  await wait(900)
+
+  const first = await run('browser_look', { cols: 12 })
+  const firstText = String(first?.text ?? '')
+  console.log('--- first look ---\n' + firstText)
+  check(/^look 12x\d+ of the screen/m.test(firstText), 'the whole screen is read as a 12-wide grid')
+  check(/1 canvas/.test(firstText), 'the call says the page draws itself')
+  check((firstText.match(/^[.:+\-*#rgbcmyopn]+$/gm) ?? []).length >= 6, 'the grid arrives as rows of palette letters')
+  check(/first look at this screen/.test(firstText), 'the first look says there is nothing to compare yet')
+
+  const painted = await run('browser_eval', { code: "(() => { const c = document.querySelector('canvas'); const g = c.getContext('2d'); g.fillStyle = '#ff2020'; g.fillRect(c.width * 0.2, c.height * 0.15, c.width * 0.4, c.height * 0.2); return 'painted' })()" })
+  check(/painted/.test(String(painted?.text ?? '')), 'the page can be asked to paint a square')
+  await wait(300)
+
+  const second = await run('browser_look', { cols: 12 })
+  const secondText = String(second?.text ?? '')
+  console.log('--- second look ---\n' + secondText)
+  check(/changed: \d+ cells? in box \d+,\d+ \d+x\d+/.test(secondText), 'the second look names only the part that moved')
+  /* Red has to be in the changed box, not anywhere in a page that may already
+     use it: the diff block is only palette rows, so one of those rows must
+     carry r. */
+  const diffBlock = secondText.slice(secondText.search(/changed:/))
+  check(/^[.:+*#rgbcmyopn-]*r[.:+*#rgbcmyopn-]*$/m.test(diffBlock), 'the picture of the change shows red where the square is')
+
+  const same = await run('browser_look', { cols: 12 })
+  check(/nothing changed since the last look/.test(String(same?.text ?? '')), 'a look that sees nothing new says so')
+  const chars = firstText.length + secondText.length + String(same?.text ?? '').length
+  console.log(`three looks cost ${chars} characters and no picture`)
+} catch (error) {
+  console.error('look check failed:', error)
+  failed += 1
+} finally {
+  await sidecar.close?.().catch(() => {})
+}
+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/check-sites.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * What the second read of the same site costs.
+ *
+ *   node scripts/check-sites.mjs
+ *
+ * Serves two pages on two origins: an app shell with three hundred buttons and
+ * a document of twelve thousand characters. Reads each one three times and
+ * checks that the first read teaches the next — the app opens as a map, the
+ * document is asked for less — and that the lesson is on disk for the next run.
+ * Exits non-zero when a site stops being learned.
+ */
+import { createServer } from 'node:http'
+import { existsSync, mkdtempSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+process.env.DSH_INNER_BROWSER_STATE_DIR = mkdtempSync(join(tmpdir(), 'dsh-sites-'))
+
+const buttons = Array.from({ length: 300 }, (_, i) => `<button>action ${i + 1}</button>`).join('')
+const app = `<!doctype html><meta charset="utf-8"><title>app shell</title>
+<h1>app shell</h1><p>a shell with three hundred things to click.</p><div>${buttons}</div>`
+const words = Array.from({ length: 240 }, (_, i) => `Paragraph ${i + 1}: ` + 'the quick brown fox jumps over the lazy dog and keeps running through the field '.repeat(3)).join('</p><p>')
+const doc = `<!doctype html><meta charset="utf-8"><title>long document</title>
+<article><h1>long document</h1><p>${words}</p></article>`
+
+const server = createServer((request, response) => {
+  const body = String(request.url ?? '').startsWith('/doc') ? doc : app
+  response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+  response.end(body)
+})
+await new Promise((done) => server.listen(0, '127.0.0.1', done))
+const port = server.address().port
+const appUrl = `http://127.0.0.1:${port}/app`
+const docUrl = `http://localhost:${port}/doc`
+
+const { Sidecar } = await import('../sidecar.js')
+const { saveTactics, sidecarTools, sessionScope, workScope } = await import('../tools.js')
+
+const wait = (ms) => new Promise((settle) => setTimeout(settle, ms))
+const sidecar = new Sidecar({ profile: 'sites-check', headless: true })
+const tools = sidecarTools(sidecar, { byChat: new Map() }, {})
+const tool = (name) => tools.find((one) => one.name === name)
+const cwd = mkdtempSync(join(tmpdir(), 'dsh-sites-cwd-'))
+/* Same binding the plugin does: the chat and the project a call belongs to. */
+const run = (name, args) => sessionScope.run('sites-check', () => workScope.run(cwd, () => tool(name).execute(args, { agent: { id: 'sites-check' } })))
+let failed = 0
+const check = (ok, what) => {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${what}`)
+  if (!ok) failed += 1
+}
+const text = (said) => String(said?.text ?? '')
+try {
+  await sidecar.launch('about:blank')
+  await sidecar.watch(() => {})
+  await sidecar.ensure({ session: 'sites-check' })
+
+  await run('browser_open', { url: appUrl })
+  const appFirst = text(await run('browser_view', {}))
+  const appSecond = text(await run('browser_view', {}))
+  const appThird = text(await run('browser_view', {}))
+  console.log('--- app, third read ---\n' + appThird.slice(0, 1200))
+  check(!/^map: /m.test(appFirst), 'the first read of a big site is the page itself')
+  check(!/^map: /m.test(appSecond), 'one read is not yet a lesson')
+  check(/^map: \d+ controls/m.test(appThird), 'the third read opens as a map of what is there')
+  check(/this site reads big \(2 read\(s\)/.test(appThird), 'the map says which site it learned and why')
+  check(appThird.length < appFirst.length, `the map costs less than the page (${String(appThird.length)} < ${String(appFirst.length)} chars)`)
+
+  await run('browser_open', { url: docUrl })
+  const docFirst = text(await run('browser_read', {}))
+  const docSecond = text(await run('browser_read', { force: true }))
+  const docThird = text(await run('browser_read', {}))
+  console.log('--- doc, third read (head) ---\n' + docThird.slice(0, 400))
+  console.log('--- doc, third read (tail) ---\n' + docThird.slice(-300))
+  check(docFirst.length > 4000, `a long document really is long (${String(docFirst.length)} chars)`)
+  check(docSecond.length > 4000, 'the forced second read is the whole thing again')
+  check(/this site reads long \(2 read\(s\), ~\d{4,} chars of text\): cut at 3500 characters/.test(docThird), 'the third read says it was cut short and how to go past it')
+  check(docThird.length < docFirst.length, `the learned read costs less (${String(docThird.length)} < ${String(docFirst.length)} chars)`)
+
+  await saveTactics()
+  const file = join(process.env.DSH_INNER_BROWSER_STATE_DIR, 'sites.json')
+  check(existsSync(file), 'the lesson is written where the next run will find it')
+  const kept = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {}
+  check(kept[`http://127.0.0.1:${port}`]?.controls >= 60, 'the app origin remembers how many controls it has')
+  check(kept[`http://localhost:${port}`]?.text >= 5000, 'the document origin remembers how long its text is')
+} catch (error) {
+  failed += 1
+  console.log('FAIL ' + String(error?.stack ?? error))
+} finally {
+  await sidecar.close?.().catch(() => {})
+  server.close()
+}
+console.log(failed === 0 ? 'sites: ok' : `sites: ${String(failed)} failed`)
+process.exitCode = failed === 0 ? 0 : 1