dsh-inner-browser-use 0.18.0 → 0.34.28

package/tools.js

@@ -9,14 +9,113 @@
  * has settled.
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createHash } from 'node:crypto'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { VIEW } from './sidecar.js?v=1'
-import { readPage, renderPage, locate, covering, contextFor, identityOf, sameThing, labelSpot, REF_GONE } from './read.js?v=1'
+import { readPage, renderPage, locate, covering, contextFor, identityOf, sameThing, differs, labelSpot, selectSpot, bounds, pictures, REF_GONE } from './read.js?v=1'
+import { brief as askBrief, recordRound, lastRoundNote, lastRound, markRound, MARK_STATUS } from './review.js?v=1'
 
-/** Where a screenshot from `sidecar_shot` lands, under the user's home. */
-export const SHOT_DIR = join('.dsh-inner-browser-use', 'screenshots')
+/** Which chat the running call belongs to, so each gets its own tab. */
+export const sessionScope = new AsyncLocalStorage()
+
+/** @returns {string} the chat id of the running call. */
+function currentSession() {
+  return String(sessionScope.getStore() ?? '')
+}
+
+/** Which project the running call belongs to, so its files stay together. */
+export const workScope = new AsyncLocalStorage()
+
+/** Where files a call produces land, under the user's home. */
+export const ARTIFACT_ROOT = String(process.env.DSH_INNER_BROWSER_ARTIFACTS ?? '') !== ''
+  ? String(process.env.DSH_INNER_BROWSER_ARTIFACTS)
+  : join(homedir(), '.dsh-inner-browser-use', 'artifacts')
+
+/** How many files one kind keeps per chat; older ones go. */
+export const ARTIFACT_KEEP = 40
+
+/** Project folder name: the folder's own name, plus a short hash of its path. */
+function projectKey() {
+  const cwd = String(workScope.getStore() ?? '')
+  if (cwd === '') return 'no-project'
+  const named = basename(cwd).toLowerCase().replace(/[^a-z0-9._-]/g, '-').replace(/^-+|-+$/g, '')
+  return `${named === '' ? 'project' : named}-${createHash('sha1').update(cwd).digest('hex').slice(0, 6)}`
+}
+
+/** Chat folder name: the short id a person can match to the chat. */
+function sessionKey() {
+  const id = currentSession().replace(/^session-/, '').replace(/[^a-z0-9-]/gi, '')
+  return id === '' ? 'no-chat' : id.slice(0, 8)
+}
+
+/**
+ * Where one kind of file for this project and this chat goes.
+ * `~/.dsh-inner-browser-use/artifacts/<project>/<chat>/<kind>/`
+ * @param {string} kind - shots, pictures, pdf.
+ * @returns {string} absolute directory; not created yet.
+ */
+export function artifactDir(kind) {
+  return join(ARTIFACT_ROOT, projectKey(), sessionKey(), kind)
+}
+
+/**
+ * Write one file where the project and the chat expect it, and keep the folder
+ * from growing without a limit.
+ * @param {string} kind - shots, pictures, pdf.
+ * @param {string} body - base64 body.
+ * @param {{name?: string, ext?: string, prefix?: string}} [options] - file name.
+ * @returns {Promise<string>} absolute path.
+ */
+export async function saveArtifact(kind, body, options = {}) {
+  const dir = artifactDir(kind)
+  await mkdir(dir, { recursive: true })
+  const ext = String(options.ext ?? '.png')
+  /* A name is a name: no separators, no runs of dots that could read as a path
+     climb, and no leading dot to hide the file. */
+  const wanted = String(options.name ?? '').replace(/[^\w.-]/g, '').replace(/\.(png|jpe?g|webp|pdf)$/i, '').replace(/\.{2,}/g, '.').replace(/^\.+/, '')
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15)
+  const prefix = String(options.prefix ?? kind)
+  const file = join(dir, `${wanted === '' ? `${prefix}-${stamp}` : wanted}${ext}`)
+  await writeFile(file, Buffer.from(body, 'base64'))
+  await pruneArtifacts(dir, ARTIFACT_KEEP)
+  return file
+}
+
+/**
+ * Keep the newest `keep` files in one folder: a browser session that runs all
+ * day does not leave a folder nobody can look through.
+ * @param {string} dir - folder to trim.
+ * @param {number} keep - how many files survive.
+ * @returns {Promise<void>} done.
+ */
+export async function pruneArtifacts(dir, keep) {
+  let names
+  try {
+    names = await readdir(dir)
+  } catch {
+    return
+  }
+  const listed = []
+  for (const name of names) {
+    try {
+      listed.push({ name, at: (await stat(join(dir, name))).mtimeMs })
+    } catch {
+      /* a file that vanished between listing and reading is already gone */
+    }
+  }
+  if (listed.length <= keep) return
+  listed.sort((left, right) => right.at - left.at)
+  for (const spare of listed.slice(keep)) {
+    try {
+      await unlink(join(dir, spare.name))
+    } catch {
+      /* best effort: a file in use stays */
+    }
+  }
+}
 
 /** How many times a call found a control again after the page redrew it. */
 const follows = { count: 0 }
@@ -25,6 +124,41 @@ const follows = { count: 0 }
 export const SIDECAR_OFF = 'The sidecar browser is not running. Call sidecar_open with the address first.'
 
 /** Output schema every tool returns. */
+/** The picture half of a screenshot result: shown only when the route can see it. */
+const SHOT_IMAGE = {
+  type: 'object', // ui-copy-ignore
+  properties: {
+    attachmentId: { type: 'string' },
+    mediaType: { type: 'string' },
+    bytes: { type: 'integer' }, // ui-copy-ignore
+    width: { type: 'integer' }, // ui-copy-ignore
+    height: { type: 'integer' }, // ui-copy-ignore
+    name: { type: 'string' }, // ui-copy-ignore
+  },
+  required: ['attachmentId', 'mediaType', 'bytes', 'width', 'height'],
+  additionalProperties: false,
+}
+
+/** A screenshot's path, plus the picture when this model can look at it. */
+export const SHOT_OUTPUT = {
+  schema: { // ui-copy-ignore
+    type: 'object', // ui-copy-ignore
+    properties: { text: { type: 'string' }, image: SHOT_IMAGE },
+    required: ['text'],
+    additionalProperties: false,
+  },
+  /**
+   * @param {unknown} _args - call arguments, unused.
+   * @param {any} value - tool value.
+   * @returns {any[]} the text, and the picture when there is one.
+   */
+  render(_args, value) {
+    const blocks = [{ type: 'text', text: String(value?.text ?? '') }]
+    if (value?.image !== undefined) blocks.push({ type: 'image', attachment: value.image })
+    return blocks
+  },
+}
+
 const TEXT_OUTPUT = {
   schema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: false },
   /**
@@ -45,18 +179,21 @@ const TEXT_OUTPUT = {
  * @param {any} page - sidecar page.
  * @returns {Promise<string>} address, title, focus and any open dialog.
  */
+export const BRIEF_JS = `(() => {
+    const a = document.activeElement
+    const secret = a !== null && typeof a === 'object' && (String(a.type ?? '') === 'password' || String(a.getAttribute === undefined ? '' : a.getAttribute('type') ?? '') === 'password')
+    const focus = a !== null && a !== document.body && a !== document.documentElement
+      ? { name: String(a.getAttribute('aria-label') || a.getAttribute('placeholder') || (a.labels && a.labels[0] && a.labels[0].innerText) || a.innerText || a.name || a.tagName).trim().slice(0, 60), value: secret ? '' : String(a.value === undefined ? '' : a.value).slice(0, 60) }
+      : null
+    return { url: location.href, title: document.title.slice(0, 80), focus }
+  })()`
+
 async function brief(page) {
   const dialog = page.dialog
   if (dialog !== null && dialog !== undefined) {
     return `${String(page.url ?? '')} · dialog ${String(dialog.type ?? '')}: ${String(dialog.message ?? '')}`
   }
-  const info = await evaluate(page, `(() => {
-    const a = document.activeElement
-    const focus = a !== null && a !== document.body && a !== document.documentElement
-      ? { name: String(a.getAttribute('aria-label') || a.getAttribute('placeholder') || (a.labels && a.labels[0] && a.labels[0].innerText) || a.innerText || a.name || a.tagName).trim().slice(0, 60), value: String(a.value === undefined ? '' : a.value).slice(0, 60) }
-      : null
-    return { url: location.href, title: document.title.slice(0, 80), focus }
-  })()`)
+  const info = await evaluate(page, BRIEF_JS)
   const bits = [String(info?.url ?? '')]
   if (String(info?.title ?? '') !== '') bits.push(String(info.title))
   if (info?.focus) bits.push(`focus ${info.focus.name}${info.focus.value === '' ? '' : ` = ${info.focus.value}`}`)
@@ -188,6 +325,18 @@ export const KEYS = {
   Space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
 }
 
+/* A game moves while a key is held, and the keys a game listens for are letters
+   and digits, not the ones a form needs. Each entry carries what a browser
+   reports: the `key` value, the physical `code`, and the legacy number old
+   engines still look at. */
+for (const letter of 'abcdefghijklmnopqrstuvwxyz') {
+  KEYS[letter] = { key: letter, code: `Key${letter.toUpperCase()}`, keyCode: letter.toUpperCase().charCodeAt(0), text: letter }
+  KEYS[letter.toUpperCase()] = KEYS[letter]
+}
+for (const digit of '0123456789') {
+  KEYS[digit] = { key: digit, code: `Digit${digit}`, keyCode: digit.charCodeAt(0), text: digit }
+}
+
 /**
  * Press a key: keyDown, then keyUp, with the character when the key types one.
  * @param {any} page - sidecar page.
@@ -195,14 +344,37 @@ export const KEYS = {
  * @param {number} [modifiers] - CDP modifier bits: Alt 1, Ctrl 2, Meta 4, Shift 8.
  * @returns {Promise<void>} done.
  */
-export async function pressKey(page, name, modifiers = 0) {
+export async function pressKey(page, name, modifiers = 0, holdMs = 0) {
   const key = KEYS[name] ?? KEYS[name.charAt(0).toUpperCase() + name.slice(1)]
   if (key === undefined) throw new Error(`sidecar: no such key ${name}`) // ui-copy-ignore
   const base = { key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode, nativeVirtualKeyCode: key.keyCode, modifiers }
   await page.key('keyDown', key.text === undefined ? base : { ...base, text: key.text })
+  /* A key held down is how a game moves: down, wait, up — not a tap. */
+  if (holdMs > 0) await new Promise((settle) => setTimeout(settle, holdMs))
   await page.key('keyUp', base)
 }
 
+/**
+ * Press several keys at once and hold them: the diagonal a game expects, and a
+ * chord such as Shift+ArrowLeft. Releasing in reverse order is what a pair of
+ * hands does, and some engines only notice the last key that went up.
+ * @param {any} page - sidecar page.
+ * @param {string[]} names - key names, for example ['ArrowLeft', 'ArrowUp'].
+ * @param {number} [modifiers] - CDP modifier bits.
+ * @param {number} [holdMs] - how long every key stays down.
+ * @returns {Promise<void>} done.
+ */
+export async function pressChord(page, names, modifiers = 0, holdMs = 0) {
+  const keys = names.map((name) => {
+    const key = KEYS[name] ?? KEYS[name.charAt(0).toUpperCase() + name.slice(1)]
+    if (key === undefined) throw new Error(`sidecar: no such key ${name}`) // ui-copy-ignore
+    return { key, base: { key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode, nativeVirtualKeyCode: key.keyCode, modifiers } }
+  })
+  for (const one of keys) await page.key('keyDown', one.key.text === undefined ? one.base : { ...one.base, text: one.key.text })
+  if (holdMs > 0) await new Promise((settle) => setTimeout(settle, holdMs))
+  for (const one of [...keys].reverse()) await page.key('keyUp', one.base)
+}
+
 /**
  * Empty the field that has focus, whatever this machine calls select-all:
  * Command on macOS, Control elsewhere. A page can swallow the shortcut, so any
@@ -419,9 +591,15 @@ async function until(page, expression, timeout) {
 async function findWords(page, words) {
   const read = await readPage(page, { mode: 'text', maxChars: 1200, max: 200 })
   const shown = read.controls.filter((control) => control.view !== false)
-  const wanted = words.toLowerCase()
-  const hit = shown.find((control) => control.name.toLowerCase() === wanted) ?? shown.find((control) => control.name.toLowerCase().includes(wanted))
-  if (hit === undefined) return null
+  /* The words may sit in separate inline nodes: <span>Sign</span><span>in</span>
+     reads as "Signin" to the page, so compare with the spaces taken out too. */
+  const squeeze = (text) => String(text).toLowerCase().replace(/\s+/g, '')
+  const wanted = squeeze(words)
+  const found = shown.find((control) => squeeze(control.name) === wanted) ?? shown.find((control) => squeeze(control.name).includes(wanted))
+  if (found === undefined) return null
+  /* When only the squeezed form matched, say the words the caller used: the
+     page spread them over nodes and "Signin" is not what anyone wrote. */
+  const hit = squeeze(found.name) === wanted && found.name.toLowerCase() !== words.toLowerCase() ? { ...found, name: words } : found
   const spot = await locate(page, hit.ref)
   if (spot.gone === true) return null
   return { ...hit, x: Number(spot.x), y: Number(spot.y) }
@@ -438,12 +616,60 @@ const EDITABLE_KINDS = ['input', 'textarea', 'select', 'combobox', 'textbox', 's
  */
 async function fieldSpot(page, words) {
   const said = await evaluate(page, labelSpot(words))
-  if (said.error !== undefined || said.result === undefined) return null
-  const spot = said.result
-  if (spot === undefined || spot === null || spot.name === undefined) return null
+  if (said === undefined || said === null || said.error !== undefined) return null
+  const spot = typeof said === 'string' ? JSON.parse(said) : said
+  if (spot === null || spot.name === undefined || spot.name === '') return null
   return { x: Number(spot.x), y: Number(spot.y), name: String(spot.name) }
 }
 
+/**
+ * Where the field called these words is, clearing a banner over it first.
+ * @param {any} page - sidecar page.
+ * @param {string} words - what the field is called on screen.
+ * @returns {Promise<{x: number, y: number, name: string, lead: string}|null>} the click.
+ */
+async function fieldByName(page, words) {
+  const hit = await findWords(page, words)
+  const lead = hit === null ? '' : await coverLead(page, hit.ref)
+  if (hit !== null && EDITABLE_KINDS.includes(String(hit.kind))) {
+    const spot = await locate(page, hit.ref)
+    if (spot.gone !== true) return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead }
+  }
+  const field = await fieldSpot(page, words)
+  if (field !== null) return { ...field, lead }
+  if (hit === null) return null
+  const spot = await locate(page, hit.ref)
+  if (spot.gone === true) return null
+  return { x: Number(spot.x), y: Number(spot.y), name: String(hit.name), lead }
+}
+
+/**
+ * Click a spot, type into it, and optionally clear it first.
+ * @param {any} page - sidecar page.
+ * @param {{x: number, y: number}} point - where to click.
+ * @param {string} text - what to type.
+ * @param {{clear?: boolean, submit?: boolean}} options - how.
+ */
+async function writeAt(page, point, text, options = {}) {
+  /* Approach the control the way a hand does: a couple of small moves that
+     land in different places, not a teleport followed by a click. */
+  const drift = (by) => ({ x: point.x + by, y: point.y + Math.round(by / 2) })
+  await page.mouse('mouseMoved', drift(-14 - Math.round(Math.random() * 10)))
+  await wait(40 + Math.round(Math.random() * 45))
+  await page.mouse('mouseMoved', drift(-4 - Math.round(Math.random() * 4)))
+  await wait(25 + Math.round(Math.random() * 35))
+  await page.mouse('mouseMoved', point)
+  await wait(35 + Math.round(Math.random() * 60))
+  await page.mouse('mousePressed', { ...point, clickCount: 1 })
+  await wait(20 + Math.round(Math.random() * 40))
+  await page.mouse('mouseReleased', { ...point, clickCount: 1 })
+  await wait(90 + Math.round(Math.random() * 120))
+  if (options.clear === true) await clearFocus(page)
+  if (options.human === false) await page.insertText(text)
+  else await page.humanType(text)
+  if (options.submit === true) await pressKey(page, 'Enter')
+}
+
 /**
  * Where the control behind a ref is now, following it across a re-render.
  * The module-level sibling of findAgain, for runStep, which has no closure.
@@ -454,8 +680,11 @@ async function fieldSpot(page, words) {
  */
 async function followRef(page, ref, known) {
   const spot = await locate(page, ref)
-  if (spot.gone !== true) return spot
   const was = Array.isArray(known) ? known.find((control) => Number(control.ref) === Number(ref)) : undefined
+  if (spot.gone !== true) {
+    const drift = differs(was, spot)
+    return drift === '' ? spot : { gone: true, why: drift }
+  }
   if (was === undefined) return spot
   const want = identityOf(was)
   if (want.name === '') return spot
@@ -468,12 +697,40 @@ async function followRef(page, ref, known) {
   return { ...next, followed: true, was: want.name }
 }
 
+/**
+ * One read state per chat, created the first time that chat reads.
+ * @param {Map<string, any>} store - per-chat states.
+ * @param {string} id - chat id.
+ * @param {any} fallback - state for calls that name no chat.
+ * @returns {any} the state of that chat.
+ */
+export function readStateFor(store, id, fallback) {
+  const key = String(id ?? '')
+  const known = store.get(key)
+  if (known !== undefined) return known
+  /* The one object the plugin was started with belongs to calls that name no
+     chat, so a chat that does name itself gets an empty one of its own. */
+  const fresh = key === '' ? fallback : { refs: [], at: 0 }
+  store.set(key, fresh)
+  return fresh
+}
+
+/**
+ * A step that could not be carried out. The batch stops here: the next step was
+ * written against a page that never arrived.
+ * @param {string} text - what happened.
+ * @returns {{text: string, blocked: boolean}} the step result.
+ */
+function stuck(text) {
+  return { text, blocked: true }
+}
+
 async function runStep(page, step, known) {
   if (step.ref !== undefined) {
     if (step.tap !== undefined || step.text !== undefined) {
       const lead = await coverLead(page, Number(step.ref))
       const spot = await followRef(page, Number(step.ref), known)
-      if (spot.gone === true) return `ref ${String(step.ref)}: ${REF_GONE}`
+      if (spot.gone === true) return stuck(`ref ${String(step.ref)}: ${REF_GONE}`)
       const after = spot.followed === true ? ` (it was redrawn under a new number, used where it is now)` : ''
       const point = { x: Number(spot.x), y: Number(spot.y) }
       await page.mouse('mouseMoved', point)
@@ -482,17 +739,17 @@ async function runStep(page, step, known) {
       if (step.tap !== undefined) return `${lead}clicked ${String(step.ref)} ${String(spot.name ?? '')}`.trim() + after
       await wait(80)
       if (step.clear === true) await clearFocus(page)
-      await page.insertText(String(step.text))
+      await page.humanType(String(step.text))
       if (step.submit === true) await pressKey(page, 'Enter')
       return `${lead}typed into ${String(step.ref)} ${String(spot.name ?? '')}`.trim() + after
     }
   }
   if (step.tap !== undefined && !/^\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*$/.test(String(step.tap))) {
     const hit = await findWords(page, String(step.tap))
-    if (hit === null) return `no control says ${JSON.stringify(String(step.tap))}`
+    if (hit === null) return stuck(`no control says ${JSON.stringify(String(step.tap))}`)
     const lead = await coverLead(page, hit.ref)
     const spot = await locate(page, hit.ref)
-    if (spot.gone === true) return `ref ${String(hit.ref)}: ${REF_GONE}`
+    if (spot.gone === true) return stuck(`ref ${String(hit.ref)}: ${REF_GONE}`)
     const point = { x: Number(spot.x), y: Number(spot.y) }
     await page.mouse('mouseMoved', point)
     await page.mouse('mousePressed', { ...point, clickCount: 1 })
@@ -502,40 +759,10 @@ async function runStep(page, step, known) {
   if (step.field !== undefined) {
     /* The words may sit on the field or in a div above a bare input. Only a
        click that lands on the field itself can be trusted with the typing. */
-    const hit = await findWords(page, String(step.field))
-    let lead = ''
-    let point = null
-    let called = ''
-    if (hit !== null && EDITABLE_KINDS.includes(String(hit.kind))) {
-      lead = await coverLead(page, hit.ref)
-      const spot = await locate(page, hit.ref)
-      if (spot.gone !== true) {
-        point = { x: Number(spot.x), y: Number(spot.y) }
-        called = String(hit.name)
-      }
-    }
-    if (point === null) {
-      const field = await fieldSpot(page, String(step.field))
-      if (field !== null) {
-        point = { x: field.x, y: field.y }
-        called = field.name
-      }
-    }
-    if (point === null) {
-      if (hit === null) return `no control says ${JSON.stringify(String(step.field))}`
-      const spot = await locate(page, hit.ref)
-      if (spot.gone === true) return `ref ${String(hit.ref)}: ${REF_GONE}`
-      point = { x: Number(spot.x), y: Number(spot.y) }
-      called = String(hit.name)
-    }
-    await page.mouse('mouseMoved', point)
-    await page.mouse('mousePressed', { ...point, clickCount: 1 })
-    await page.mouse('mouseReleased', { ...point, clickCount: 1 })
-    await wait(80)
-    if (step.clear === true) await clearFocus(page)
-    await page.insertText(String(step.text ?? ''))
-    if (step.submit === true) await pressKey(page, 'Enter')
-    return `${lead}typed into "${called.slice(0, 60)}"`
+    const target = await fieldByName(page, String(step.field))
+    if (target === null) return stuck(`${String(step.field)}: ${REF_GONE}`)
+    await writeAt(page, { x: target.x, y: target.y }, String(step.text ?? ''), { clear: step.clear, submit: step.submit })
+    return `${target.lead}typed into "${target.name.slice(0, 60)}"`
   }
   if (step.tap !== undefined) {
     const [x, y] = String(step.tap).split(',').map(Number)
@@ -547,7 +774,7 @@ async function runStep(page, step, known) {
   }
   if (step.text !== undefined) {
     if (step.clear === true) await clearFocus(page)
-    await page.insertText(String(step.text))
+    await page.humanType(String(step.text))
     if (step.submit === true) await pressKey(page, 'Enter')
     return `typed ${String(step.text).slice(0, 60)}`
   }
@@ -563,17 +790,17 @@ async function runStep(page, step, known) {
   if (step.wait_text !== undefined) {
     const needle = JSON.stringify(String(step.wait_text))
     const ok = await until(page, `document.body ? document.body.innerText.includes(${needle}) : false`, Number(step.timeout ?? 8000))
-    return ok ? `saw ${String(step.wait_text)}` : `did not see ${String(step.wait_text)}`
+    return ok ? `saw ${String(step.wait_text)}` : stuck(`did not see ${String(step.wait_text)}`)
   }
   if (step.wait_gone !== undefined) {
     const needle = JSON.stringify(String(step.wait_gone))
     const ok = await until(page, `document.body ? !document.body.innerText.includes(${needle}) : true`, Number(step.timeout ?? 8000))
-    return ok ? `${String(step.wait_gone)} went away` : `${String(step.wait_gone)} stayed`
+    return ok ? `${String(step.wait_gone)} went away` : stuck(`${String(step.wait_gone)} stayed`)
   }
   if (step.wait_url !== undefined) {
     const needle = JSON.stringify(String(step.wait_url))
     const ok = await until(page, `location.href.includes(${needle})`, Number(step.timeout ?? 8000))
-    return ok ? `at ${String(step.wait_url)}` : `still at a different address`
+    return ok ? `at ${String(step.wait_url)}` : stuck(`still at a different address`)
   }
   if (step.open !== undefined) {
     const landed = await page.navigate(String(step.open))
@@ -610,6 +837,22 @@ async function remember(page, refs, options) {
   return read
 }
 
+/**
+ * Two reads of the same page in the same shape say the same thing. Saying it
+ * again costs tokens and teaches nothing, so the second read can be one line.
+ * @param {any} before - the earlier read.
+ * @param {any} after - the read now.
+ * @returns {boolean} true when nothing a read would show has changed.
+ */
+export function sameRead(before, after) {
+  if (before === undefined || before === null || after === undefined || after === null) return false
+  if (before.url !== after.url || before.title !== after.title) return false
+  if (before.text !== after.text) return false
+  if (JSON.stringify(before.controls) !== JSON.stringify(after.controls)) return false
+  if ((before.focused?.ref ?? null) !== (after.focused?.ref ?? null)) return false
+  return true
+}
+
 /**
  * Say only what changed since the previous read.
  * @param {any} previous - the read before.
@@ -705,7 +948,140 @@ export async function extractRows(page, args) {
   return `${rows.length} of ${Number(value.total)} rows matching ${select}:\n${said.join('\n')}${more}`
 }
 
+/**
+ * Say one thing to a box in the page and take the answer back. The wait ends
+ * when the answer has stopped changing, so a streaming reply is not cut off and
+ * a page that never answers does not hold the call open forever.
+ * @param {any} page - sidecar page.
+ * @param {{text?: string, ref?: number, submit?: boolean, timeout_ms?: number}} args - what to say.
+ * @returns {Promise<string>} the answer, or why there is none.
+ */
+/**
+ * Whether a box on the page still holds the words that were typed.
+ * A box that keeps them never sent them, which is what a signed-out page does.
+ * @param {any} page - sidecar page.
+ * @param {string} words - what was typed.
+ * @returns {Promise<boolean>} true when the words are still in a box.
+ */
+async function boxHolds(page, words) {
+  const wanted = String(words).slice(0, 24)
+  if (wanted === '') return false
+  const held = await evaluate(page, `(() => {
+  const wanted = ${JSON.stringify(wanted)}
+  for (const el of document.querySelectorAll('textarea, [contenteditable=""], [contenteditable="true"], input[type="text"], input[type="search"], input:not([type])')) {
+    if (String(el.value ?? el.innerText ?? '').trim().includes(wanted)) return true
+  }
+  return false
+})()`)
+  return held === true
+}
+
+/**
+ * Sends a line to whatever chat the page holds and waits for the answer to stop
+ * growing. The ref is followed the same way a click follows it, so a reply box
+ * that was redrawn since the read still gets the text.
+ * @param {any} page - sidecar page.
+ * @param {any} args - text, optional ref, optional timeout.
+ * @returns {Promise<string>} the answer.
+ */
+export async function askInPage(page, args) {
+const said = String(args?.text ?? '').trim()
+if (said === '') return 'Give me something to say.'
+const budget = Math.max(3000, Math.min(180_000, Math.trunc(Number(args?.timeout_ms ?? 60_000)) || 60_000))
+const before = await readPage(page, { mode: 'text', maxChars: 4000 })
+let point = null
+if (args?.ref !== undefined) {
+  const spot = await followRef(page, Number(args.ref))
+  if (spot.gone === true) return spot.why ?? REF_GONE
+  point = { x: Number(spot.x), y: Number(spot.y) }
+} else {
+  const at = await evaluate(page, `(() => {
+    let best = null
+    for (const el of document.querySelectorAll('textarea, [contenteditable=""], [contenteditable="true"], input[type="text"], input[type="search"], input:not([type])')) {
+      const b = el.getBoundingClientRect()
+      const s = getComputedStyle(el)
+      if (s.visibility === 'hidden' || s.display === 'none' || b.width < 80 || b.height < 18) continue
+      if (b.bottom < 0 || b.top > innerHeight) continue
+      if (best === null || b.width * b.height > best.area) best = { area: b.width * b.height, x: b.x + Math.min(24, b.width / 2), y: b.y + b.height / 2, name: String(el.getAttribute('placeholder') ?? el.getAttribute('aria-label') ?? '').slice(0, 40) }
+    }
+    return best === null ? null : { x: Math.round(best.x), y: Math.round(best.y), name: best.name }
+  })()`)
+  if (at === null || at === undefined) return 'No box to type in on this page. Call sidecar_view to see what is there.'
+  point = { x: Number(at.x), y: Number(at.y) }
+}
+await page.mouse('mouseMoved', point)
+await page.mouse('mousePressed', { ...point, clickCount: 1 })
+await page.mouse('mouseReleased', { ...point, clickCount: 1 })
+await wait(60)
+await page.humanType(said)
+if (args?.submit !== false) await pressKey(page, 'Enter')
+await wait(500)
+if (args?.submit !== false && (await boxHolds(page, said))) {
+  return `the words are still in the box 0.5s after pressing Enter: the page did not take the message. If it is waiting for a sign-in, sign in in the column, then ask again.`
+}
+const started = Date.now()
+const deadline = started + budget
+let last = before.text
+let fresh = ''
+let steady = 0
+let quiet = 0
+while (Date.now() < deadline) {
+  await wait(500)
+  const now = await readPage(page, { mode: 'text', maxChars: 4000 })
+  if (now.text !== last) {
+    last = now.text
+    fresh = now.text
+    steady = 0
+    quiet = 0
+    continue
+  }
+  if (fresh !== '') {
+    steady += 1
+    if (steady >= 3) break
+  } else {
+    quiet += 1
+    if (quiet >= 4 && Date.now() - started > 4000) break
+  }
+}
+const took = Date.now() - started
+/* A page that shows neither the words in a box nor the message itself never
+   took it: the chips moved, the menu redrew, and none of that is an answer. */
+const echo = String(said.slice(0, 24))
+if (fresh !== '' && echo.length >= 8 && !fresh.includes(echo)) {
+  const asking = /(sign in|log in|登录|注册)/i.test(fresh)
+  return `the page changed but does not show the message: it did not take what was sent.${asking ? ' It is asking for a sign-in — sign in in the column, then ask again.' : ' Try sidecar_view to see what is in the way.'}`
+}
+/* A box that still holds the words is the page saying it did not take them:
+   a signed-out page leaves them there, and the old wording sent the reader
+   looking for an answer that was never asked for. */
+const stuck = fresh === '' && (await boxHolds(page, said))
+if (fresh === '') {
+  if (stuck) return `sent it — no answer after ${Math.round(took / 100) / 10}s, and the words are still in the box: the page did not take the message. If it is waiting for a sign-in, sign in in the column, then ask again.`
+  return `sent it — no answer after ${Math.round(took / 100) / 10}s; the page still says: ${before.text.slice(0, 400)}`
+}
+/* The answer may replace the words that were there, so cut at the last
+   character the two reads share, not at the old length. */
+let shared = 0
+while (shared < fresh.length && shared < before.text.length && fresh[shared] === before.text[shared]) shared += 1
+const added = fresh.slice(shared)
+/* Lines are kept: a reviewer's list is one point per line, and flattening it
+   would leave the next round with a paragraph instead of items. */
+const words = added.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim().slice(0, 2500)
+return `the answer came back in ${Math.round(took / 100) / 10}s:\n${words}`
+}
+
 export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
+  /* A ref belongs to the page it was read from, and two chats read two pages.
+     One shared read state meant chat B's read replaced chat A's baseline, so A's
+     next "what changed" was a diff against a page it never saw and a number from
+     A could be matched against B's control. Each chat now keeps its own. */
+  const byChat = new Map()
+  /**
+   * The read state of the chat this call speaks for.
+   * @param {string} [id] - chat id; the current one by default.
+   * @returns {{refs: any[], at: number, last?: any, lastShape?: string}} its state.
+   */
+  const refsFor = (id = currentSession()) => readStateFor(byChat, id, refs)
   /* Reading, clicking and typing on Chrome's own error page is not driving the
      site: the text there is Chrome talking, the buttons reload. Those calls are
      refused with the error code instead. The tools that report the browser
@@ -713,14 +1089,23 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
      run, because they are how a stuck person finds out what happened. */
   const withRawPage = async (work) => {
     if (!sidecar.alive) return { text: SIDECAR_OFF }
-    const page = await sidecar.ensure()
+    const page = await sidecar.ensure({ session: currentSession() })
     const text = await work(page)
     return { text: text + personNote(sidecar) }
   }
   /** Looking is still useful while the person has the page. */
   const withRead = async (work) => {
-    if (!sidecar.alive) return { text: SIDECAR_OFF }
-    const page = await sidecar.ensure()
+    /* A plugin reload makes a new driver while the browser it started keeps
+       running. Refusing every read until someone opens a page again would throw
+       away a browser that is still there: attach to it instead. */
+    if (!sidecar.alive) {
+      try {
+        await sidecar.ensure({ session: currentSession() })
+      } catch {
+        return { text: SIDECAR_OFF }
+      }
+    }
+    const page = await sidecar.ensure({ session: currentSession() })
     const dead = await unreachable(page)
     if (dead !== '') return { text: dead + personNote(sidecar) }
     const text = await work(page)
@@ -733,7 +1118,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     return withRead(work)
   }
   const look = async (page, options) => {
-    const read = await remember(page, refs, options)
+    const read = await remember(page, refsFor(), options)
     const said = renderPage(read, options)
     return isCheckPage(read) ? `${said}\n${CHECK_NOTE}` : said
   }
@@ -754,8 +1139,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
    */
   const findAgain = async (page, ref) => {
     const spot = await locate(page, ref)
-    if (spot.gone !== true) return spot
-    const known = (refs?.refs ?? []).find((control) => Number(control.ref) === Number(ref))
+    const known = (refsFor().refs ?? []).find((control) => Number(control.ref) === Number(ref))
+    if (spot.gone !== true) {
+      const drift = differs(known, spot)
+      return drift === '' ? spot : { gone: true, why: drift }
+    }
     if (known === undefined) return spot
     const want = identityOf(known)
     if (want.name === '') return spot
@@ -787,7 +1175,8 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       isConcurrencySafe: () => false,
       /** @param {any} args - arguments. @param {any} exec - tool run. @returns {Promise<{text: string}>} what the page is. */
       execute: async (args, exec) => {
-        const page = await sidecar.ensure({ url: args?.url, headless: args?.headless })
+        const who = String(exec?.agent?.id ?? '')
+        const page = await sidecar.ensure({ url: args?.url, headless: args?.headless, session: who })
         if (args?.url === undefined) await page.readTitle()
         /* A window on the person's screen is their business, not a surprise: say
            it, so nobody wonders what popped up. A site that refuses a windowless
@@ -795,7 +1184,6 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         const windowed = sidecar.headless === false ? 'The browser is showing a window this time — a site only opens for a windowed one. Same profile, same logins.\n' : ''
         /* The tab appears in the calling chat and nowhere else: the person may
            be reading a different chat, and a browser there would be a surprise. */
-        const who = String(exec?.agent?.id ?? '')
         if (who !== '') host.want?.(who) // ui-copy-ignore
         await settle(page, 8000)
         const dead = await unreachable(page)
@@ -824,10 +1212,29 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the read. */
       execute: async (args) => withRead(async (page) => {
         const options = { mode: String(args?.mode ?? 'text'), maxChars: Number(args?.max_chars ?? 4600) }
-        const read = await remember(page, refs, options)
+        /* Each chat keeps its own read state: a shared one let another chat's
+           read replace this chat's baseline, so its numbers and its "what
+           changed" answered about a page it never saw. */
+        const state = refsFor()
+        const read = await remember(page, state, options)
         const note = isCheckPage(read) ? `\n${CHECK_NOTE}` : ''
-        if (args?.changed_only === true && refs.last !== undefined) return diffRead(refs.last, read, options) + note
-        refs.last = read
+        if (args?.changed_only === true && state.last !== undefined) {
+          /* The diff becomes the new baseline: a page that moved zero -> one
+             should not report that move again on the next read. */
+          const text = diffRead(state.last, read, options) + note
+          state.last = read
+          state.lastShape = JSON.stringify(options)
+          return text
+        }
+        const before = state.last
+        state.last = read
+        /* Same page, same shape, same words: the numbers above still work, and
+           repeating the page would only spend tokens. */
+        if (sameRead(before, read) && state.lastShape === JSON.stringify(options)) {
+          const moved = Number(before.scroll?.y ?? 0) !== Number(read.scroll?.y ?? 0) ? `, scrolled to ${Math.round(Number(read.scroll?.y ?? 0))}` : ''
+          return `still at ${read.url}${moved} — nothing changed since the last read; the numbers above still work${note}`
+        }
+        state.lastShape = JSON.stringify(options)
         return renderPage(read, options) + note
       }),
     },
@@ -843,6 +1250,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           y: { type: 'integer', description: 'Viewport y, when clicking a point.' },
           double: { type: 'boolean', description: 'Double-click.' },
           right: { type: 'boolean', description: 'Right-click, opening a context menu.' },
+          hold_ms: { type: 'integer', description: 'Keep the button down this long before releasing: a press-and-hold a game or a drag handle needs.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         additionalProperties: false,
@@ -857,7 +1265,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         let followed = ''
         if (args?.ref !== undefined) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           if (spot.followed === true) followed = `the page redrew, so "${String(spot.was).slice(0, 50)}" has a new number — used where it is now`
           point = { x: Number(spot.x), y: Number(spot.y) }
         } else if (String(args?.text ?? '') !== '') {
@@ -872,6 +1280,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (args?.ref !== undefined && button === 'left') {
           const gate = await clearCover(page, Number(args.ref))
           cover = gate.note
+          /* An overlay that would not go away leaves the control underneath:
+             the click would land on the overlay, so it is not sent. */
+          if (gate.cleared !== true) {
+            return `${cover.trim()}\nNot clicked: the control is still covered. Call sidecar_view and handle the overlay first.`
+          }
           if (gate.cleared && cover !== '') {
             const again = await locate(page, Number(args.ref))
             if (again.gone !== true) point = { x: Number(again.x), y: Number(again.y) }
@@ -879,6 +1292,8 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         }
         await page.mouse('mouseMoved', point)
         await page.mouse('mousePressed', { ...point, clickCount: args?.double === true ? 2 : 1, button })
+        const hold = Math.max(0, Math.min(60_000, Number(args?.hold_ms ?? 0)))
+        if (hold > 0) await new Promise((settle) => setTimeout(settle, hold))
         await page.mouse('mouseReleased', { ...point, clickCount: args?.double === true ? 2 : 1, button })
         await settle(page)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 3000 }), `click ${label}`)
@@ -893,6 +1308,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         properties: {
           text: { type: 'string', description: 'Text to type.' },
           ref: { type: 'integer', description: 'Control to click before typing.' },
+          field: { type: 'string', description: 'The field is called this on screen, when you have no number for it.' },
           submit: { type: 'boolean', description: 'Press Enter after typing.' },
           clear: { type: 'boolean', description: 'Select all and delete before typing.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
@@ -907,11 +1323,23 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async (args) => withPage(async (page) => {
         let cover = ''
         let followed = ''
+        if (args?.field !== undefined && args?.ref === undefined) {
+          const target = await fieldByName(page, String(args.field))
+          if (target === null) return `${String(args.field)}: ${REF_GONE}`
+          cover = target.lead
+          await writeAt(page, { x: target.x, y: target.y }, String(args?.text ?? ''), { clear: args?.clear, submit: args?.submit === true })
+          await settle(page)
+          const called = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), 'type')
+          return called + cover + ` (typed into "${target.name.slice(0, 50)}")` // ui-copy-ignore
+        }
         if (args?.ref !== undefined) {
           const gate = await clearCover(page, Number(args.ref))
           cover = gate.note
+          if (gate.cleared !== true) {
+            return `${cover.trim()}\nNot typed into: the field is still covered. Call sidecar_view and handle the overlay first.`
+          }
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE + cover
+          if (spot.gone === true) return spot.why ?? REF_GONE + cover
           if (spot.followed === true) followed = `the page redrew, so "${String(spot.was).slice(0, 50)}" has a new number — typed where it is now`
           const point = { x: Number(spot.x), y: Number(spot.y) }
           await page.mouse('mouseMoved', point)
@@ -920,21 +1348,131 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           await wait(80)
         }
         if (args?.clear === true) await clearFocus(page)
-        await page.insertText(String(args?.text ?? ''))
+        await page.humanType(String(args?.text ?? ''))
         if (args?.submit === true) await pressKey(page, 'Enter')
         await settle(page)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), 'type')
         return said + cover + (followed === '' ? '' : ` (${followed})`) // ui-copy-ignore
       }),
     },
+    {
+      name: 'sidecar_ask', // ui-copy-ignore
+      description: 'Say something to a chat that is open in the page — a model, a support window, a search box — and read its answer back in the same call. Types into the box, presses Enter, then waits until the answer stops growing. Use it to get a review or a picture prompt answered without a read between every step.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          text: { type: 'string', description: 'What to say.' },
+          ref: { type: 'integer', description: 'The box to type in, from sidecar_view. Omit to use the page\u2019s own chat box.' },
+          submit: { type: 'boolean', description: 'Press Enter to send. Default true.' },
+          timeout_ms: { type: 'integer', description: 'How long to wait for the answer. Default 60000.' },
+        },
+        required: ['text'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 180_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the answer. */
+      execute: async (args) => withPage((page) => askInPage(page, args)),
+    },
+    {
+      name: 'sidecar_review', // ui-copy-ignore
+      description: 'Ask the chat in the page to review a repository and take its review back as a list: builds the message, sends it, waits for the answer, and writes the round down so the next round knows what was already said. Use it for a review round, not for a one-off question (that is sidecar_ask).',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          repo: { type: 'string', description: 'Address of the repository to review.' },
+          commit: { type: 'string', description: 'The commit the review is about. Omit for the newest one.' },
+          focus: { type: 'string', description: 'One thing to look at especially.' },
+          diff: { type: 'string', description: 'The change to review, as a diff. Include it when the reviewer cannot open the repository itself.' },
+          ref: { type: 'integer', description: 'The box to type in, from sidecar_view. Omit to use the page\u2019s own chat box.' },
+          timeout_ms: { type: 'integer', description: 'How long to wait for the review. Default 120000.' },
+        },
+        required: ['repo'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 240_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the review. */
+      execute: async (args) => withPage(async (page) => {
+        const repo = String(args?.repo ?? '').trim()
+        if (repo === '') return 'Which repository should the reviewer look at?'
+        const commit = String(args?.commit ?? '').trim()
+        /* What was settled last time travels with the question. */
+        const before = lastRound()
+        const already = Array.isArray(before?.marks) ? before.marks : []
+        const asked = askBrief({ repo, commit, focus: String(args?.focus ?? ''), diff: String(args?.diff ?? ''), already })
+        const started = Date.now()
+        const told = await askInPage(page, { text: asked, ref: args?.ref, timeout_ms: args?.timeout_ms ?? 120_000 })
+        const tookMs = Date.now() - started
+        if (!String(told).startsWith('the answer came back in')) return told
+        const answer = String(told).split('\n').slice(1).join('\n').trim()
+        const { round } = recordRound({ commit, question: asked, answer, tookMs })
+        /* A wall answers too, and its words are not advice: name it rather than
+           call the login screen prose. */
+        const wall = /(sign in|log in|登录|注册|verif|checking your browser)/i.test(answer)
+        /* The question sitting there unanswered is not prose: say that instead. */
+        const busy = asked.slice(0, 24)
+        const waiting = round.points.length === 0 && busy.length >= 8 && answer.includes(busy)
+        const list = round.points.length > 0
+          ? round.points.map((point, at) => `${at + 1}. ${point}`).join('\n')
+          : waiting
+            ? `the page has the message but has not answered yet; it shows: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+            : wall
+            ? `the page is asking to sign in first, so there is no review yet: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+            : `It answered in prose; no list to work from. It said: ${answer.replace(/\s+/g, ' ').slice(0, 200)}`
+        const settled = already.filter((mark) => mark.status !== 'open').length
+        const carried = settled === 0 ? '' : `\n(${settled} earlier point${settled === 1 ? '' : 's'} left out as already handled)`
+        return `review round: ${commit === '' ? 'newest commit' : commit.slice(0, 12)} in ${Math.round(tookMs / 100) / 10}s\n${list}${carried}`
+      }),
+    },
+    {
+      name: 'sidecar_review_verdict', // ui-copy-ignore
+      description: 'Record what happened to each point of the last review round, so the next round leaves settled points out: point numbers are the ones sidecar_review printed, and each mark is fixed, verified (checked in the code and the point does not apply), invalid, or open.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          mark: { // ui-copy-ignore
+            type: 'array',
+            description: 'One entry per point: which point, its status, and the evidence that backs it.',
+            items: { // ui-copy-ignore
+              type: 'object', // ui-copy-ignore
+              properties: { // ui-copy-ignore
+                point: { type: 'integer', description: 'The point number sidecar_review printed, starting at 1.' },
+                status: { type: 'string', enum: MARK_STATUS, description: 'fixed, verified, invalid, or open.' },
+                evidence: { type: 'string', description: 'Where the code shows it: file, test, or commit.' },
+              },
+              required: ['point', 'status'], // ui-copy-ignore
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['mark'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 10_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<{text: string}>} what was recorded. */
+      execute: async (args) => {
+        const written = markRound({ marks: Array.isArray(args?.mark) ? args.mark : [] })
+        if (written === null) return 'No review round to mark: play one with sidecar_review first.'
+        const counts = new Map()
+        for (const mark of written.marks) counts.set(mark.status, (counts.get(mark.status) ?? 0) + 1)
+        const said = [...counts].map(([status, n]) => `${n} ${status}`).join(', ')
+        return `review round ${String(written.round.commit || 'newest').slice(0, 12)}: recorded ${written.marks.length} of ${written.round.points.length} points (${said}).`
+      },
+    },
     {
       name: 'sidecar_key', // ui-copy-ignore
-      description: 'Press one key in the sidecar browser: Enter, Tab, Escape, Backspace, Delete, ArrowUp/ArrowDown/ArrowLeft/ArrowRight, Home, End, PageUp, PageDown, Space.',
+      description: 'Press one key in the sidecar browser: Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space, letters and digits. Join keys with + to hold them together, and hold_ms to keep them down.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
-          key: { type: 'string', description: 'Key name.' },
+          key: { type: 'string', description: 'Key name, or several joined by + to hold them together (ArrowLeft+ArrowUp, Shift+ArrowLeft). Letters and digits work too.' },
           modifiers: { type: 'string', description: 'Held while pressing: Ctrl, Alt, Shift or Meta, joined by +.' },
+          hold_ms: { type: 'integer', description: 'Keep the key down this long before releasing. Games move while a key is held.' },
           read: { type: 'boolean', description: 'Read the page after the action, instead of a one-line confirmation.' },
         },
         required: ['key'], // ui-copy-ignore
@@ -948,8 +1486,13 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         const name = String(args?.key ?? 'Enter')
         const held = String(args?.modifiers ?? '')
         const mods = (held.includes('Alt') ? 1 : 0) + (held.includes('Ctrl') ? 2 : 0) + (held.includes('Meta') ? 4 : 0) + (held.includes('Shift') ? 8 : 0)
-        await pressKey(page, name, mods)
-        await settle(page, 3000)
+        const hold = Math.max(0, Math.min(60_000, Number(args?.hold_ms ?? 0)))
+        const names = name.split('+').map((one) => one.trim()).filter((one) => one !== '')
+        if (names.length > 1) await pressChord(page, names, mods, hold)
+        else await pressKey(page, name, mods, hold)
+        /* A held key is game input: waiting for the page to fall quiet after one
+           costs more than the frame it was meant to drive. */
+        if (hold === 0) await settle(page, 3000)
         return acted(page, args, () => look(page, { mode: 'text', maxChars: 2000 }), `key ${name}`)
       }),
     },
@@ -995,7 +1538,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
         const spot = await findAgain(page, Number(args?.ref))
-        if (spot.gone === true) return REF_GONE
+        if (spot.gone === true) return spot.why ?? REF_GONE
         const cursor = await page.hover({ x: Number(spot.x), y: Number(spot.y) })
         await wait(400)
         const said = await acted(page, args, () => look(page, { mode: 'text', maxChars: 2500 }), `hover ${String(args?.ref)} · ${cursor}`)
@@ -1079,9 +1622,14 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (steps.length === 0) return 'Give at least one step.'
         const report = []
         for (const [index, step] of steps.entries()) {
-          const said = await runStep(page, step ?? {}, refs?.refs)
-          report.push(`${index + 1}. ${said}`)
-          if (/^ref \d+: That control is gone/.test(said)) return `${report.join('\n')}\nStopped: the page changed. Call sidecar_view and use the new numbers.`
+          const said = await runStep(page, step ?? {}, refsFor().refs)
+          const text = typeof said === 'string' ? said : said.text
+          report.push(`${index + 1}. ${text}`)
+          /* A step that never landed makes every later step a guess, so the
+             batch ends here instead of typing into a page that is not there. */
+          if (typeof said !== 'string' && said.blocked === true) {
+            return `${report.join('\n')}\nStopped after step ${index + 1}. Call sidecar_view and plan again from what the page shows now.`
+          }
           /* A step can navigate straight onto Chrome's error page — a mistyped
              address, or a site that does not answer. The rest of the batch
              would then type into "This site can't be reached", so it stops
@@ -1094,13 +1642,14 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         const mode = String(args?.read ?? 'text')
         if (mode === 'none') return report.join('\n')
         const options = { mode: mode === 'changed' ? 'text' : mode, maxChars: Number(args?.max_chars ?? 3000) }
-        const read = await remember(page, refs, options)
-        if (mode === 'changed' && refs.last !== undefined) {
-          const diff = diffRead(refs.last, read, options)
-          refs.last = read
+        const state = refsFor()
+        const read = await remember(page, state, options)
+        if (mode === 'changed' && state.last !== undefined) {
+          const diff = diffRead(state.last, read, options)
+          state.last = read
           return `${report.join('\n')}\n${diff}`
         }
-        refs.last = read
+        state.last = read
         return `${report.join('\n')}\n\n${renderPage(read, options)}`
       }),
     },
@@ -1163,9 +1712,10 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         type: 'object', // ui-copy-ignore
         properties: {
           ref: { type: 'integer', description: 'Number of the select control from sidecar_view.' },
+          field: { type: 'string', description: 'The dropdown is called this on screen, when you have no number for it.' },
           value: { type: 'string', description: 'Option label or value to choose.' },
         },
-        required: ['ref', 'value'], // ui-copy-ignore
+        required: ['value'], // ui-copy-ignore
         additionalProperties: false,
       },
       output: TEXT_OUTPUT, // ui-copy-ignore
@@ -1173,8 +1723,17 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       isConcurrencySafe: () => false,
       /** @param {any} args - arguments. @returns {Promise<{text: string}>} the page after. */
       execute: async (args) => withPage(async (page) => {
+        if (args?.ref === undefined) {
+          if (args?.field === undefined) return 'name the dropdown: pass its number from sidecar_view, or the words on screen that name it.' // ui-copy-ignore
+          const chosen = await evaluate(page, selectSpot(String(args.field), String(args?.value ?? '')))
+          const said = typeof chosen === 'string' ? chosen : chosen?.error === undefined ? '' : String(chosen.error)
+          if (said === '' || said.startsWith('no dropdown')) return said === '' ? 'the page did not answer; read it and try again.' : said // ui-copy-ignore
+          await settle(page, 3000)
+          if (args?.read === true) return `${said}\n${await look(page, { mode: 'text', maxChars: 2000 })}`
+          return `${said} · ${await brief(page)}`
+        }
         const spot = await findAgain(page, Number(args?.ref))
-        if (spot.gone === true) return REF_GONE
+        if (spot.gone === true) return spot.why ?? REF_GONE
         const wanted = JSON.stringify(String(args?.value ?? ''))
         const route = await contextFor(page, Number(args?.ref))
         const local = route?.local ?? Number(args?.ref)
@@ -1221,7 +1780,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (route?.contextId !== undefined) uploadParams.contextId = route.contextId
         const handle = await page.cdp.send('Runtime.evaluate', uploadParams, route?.sessionId)
         const objectId = handle.result?.objectId
-        if (objectId === undefined) return REF_GONE
+        if (objectId === undefined) return spot.why ?? REF_GONE
         const node = await page.cdp.send('DOM.describeNode', { objectId }, route?.sessionId)
         const backendNodeId = node?.node?.backendNodeId
         if (backendNodeId === undefined) return 'That control cannot take a file.'
@@ -1232,7 +1791,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
     },
     {
       name: 'sidecar_shot', // ui-copy-ignore
-      description: 'Save a PNG of the sidecar browser into the session folder and return its absolute path. Default is the visible screen; full takes the whole page, ref takes one control.',
+      description: 'Save a PNG of the sidecar browser into the session folder and return its absolute path; when the current model accepts images the picture comes back in the same call, so a captcha, a chart or a broken layout can be looked at instead of guessed. Default is the visible screen; full takes the whole page, ref takes one control.',
       parameters: {
         type: 'object', // ui-copy-ignore
         properties: {
@@ -1243,25 +1802,109 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         },
         additionalProperties: false,
       },
-      output: TEXT_OUTPUT, // ui-copy-ignore
+      output: SHOT_OUTPUT, // ui-copy-ignore
       timeoutMs: 40_000,
       isConcurrencySafe: () => false,
-      /** @param {any} args - arguments. @returns {Promise<{text: string}>} the saved path. */
-      execute: async (args) => withRead(async (page) => {
+      /**
+       * A picture nobody can look at is only a file path: when the route declares
+       * image input, the same call carries the PNG as an attachment so the next
+       * step can be planned from what is actually on screen instead of guessing.
+       * @param {any} args - arguments.
+       * @param {any} [exec] - call context, for the route and its attachments.
+       * @returns {Promise<any>} the saved path, and the picture when available.
+       */
+      execute: async (args, exec) => {
+        /** @type {{data: string, file: string}|undefined} */
+        let taken
+        const said = await withRead(async (page) => {
         const scale = Math.max(1, Math.min(3, Number(args?.scale ?? 1)))
         let clip = undefined
         if (args?.ref !== undefined) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
-          clip = { x: Math.max(0, Number(spot.x) - 20), y: Math.max(0, Number(spot.y) - 20), width: 220, height: 140 }
+          if (spot.gone === true) return spot.why ?? REF_GONE
+          /* The picture is of the control, not of a guess around its middle:
+             a canvas can be most of the page, a checkbox a few pixels. */
+          const box = await evaluate(page, bounds(Number(args.ref)))
+          const rect = typeof box === 'string' ? JSON.parse(box) : box
+          if (rect?.gone === true) return spot.why ?? REF_GONE
+          const pad = 8
+          clip = {
+            x: Math.max(0, Math.round(Number(rect.x) - pad)),
+            y: Math.max(0, Math.round(Number(rect.y) - pad)),
+            width: Math.max(8, Math.round(Number(rect.width) + pad * 2)),
+            height: Math.max(8, Math.round(Number(rect.height) + pad * 2)),
+          }
         }
         const data = await page.shot({ full: args?.full === true, rect: clip, scale })
-        const dir = join(homedir(), SHOT_DIR)
-        await mkdir(dir, { recursive: true })
-        const name = String(args?.name ?? '').replace(/[^\w.-]/g, '') || `sidecar-${Date.now()}`
-        const file = join(dir, name.endsWith('.png') ? name : `${name}.png`)
-        await writeFile(file, Buffer.from(data, 'base64'))
+        const file = await saveArtifact('shots', data, { name: args?.name, prefix: 'shot' })
+        taken = { data, file }
         return file
+        })
+        if (taken === undefined) return said
+        let image
+        try {
+          image = await host.showShot?.(taken.data, taken.file.split('/').pop() ?? 'shot.png', exec) // ui-copy-ignore
+        } catch {
+          image = undefined
+        }
+        /* The route may not carry pictures at all: then the file path is all
+           this call can give, and saying so is better than a silent path the
+           next step assumes was looked at. */
+        if (image === undefined) return { text: `${said.text}\nno picture reached this result — sidecar_view reads the words here, sidecar_grab returns a picture as a file` }
+        return { text: said.text, image }
+      },
+    },
+    {
+      name: 'sidecar_grab', // ui-copy-ignore
+      description: 'Save the picture on the page as a file: an image, a chart, a drawing surface. Picks the largest one, or the one inside a given control.',
+      parameters: {
+        type: 'object', // ui-copy-ignore
+        properties: {
+          ref: { type: 'integer', description: 'Only the picture at or inside this control.' },
+          name: { type: 'string', description: 'File name without extension.' },
+          count: { type: 'integer', description: 'How many, largest first. Default 1, at most 4.' },
+        },
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 40_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - arguments. @returns {Promise<string>} the saved paths, one per line. */
+      execute: async (args) => withRead(async (page) => {
+        const said = await evaluate(page, pictures(args?.ref, args?.count))
+        let found
+        try {
+          found = JSON.parse(typeof said === 'string' ? said : JSON.stringify(said))
+        } catch {
+          found = { pictures: [] }
+        }
+        const rows = []
+        const base = String(args?.name ?? '').replace(/[^\w.-]/g, '')
+        const list = Array.isArray(found?.pictures) ? found.pictures : []
+        for (let index = 0; index < list.length; index += 1) {
+          const item = list[index]
+          const body = String(item?.data ?? '')
+          const mark = body.indexOf(',')
+          if (mark < 0) continue
+          const type = String(item?.type ?? 'image/png')
+          const ext = type.includes('jpeg') ? 'jpg' : type.includes('webp') ? 'webp' : type.includes('svg') ? 'svg' : 'png'
+          const file = await saveArtifact('pictures', body.slice(mark + 1), {
+            name: base === '' ? '' : `${base}${list.length > 1 ? `-${index + 1}` : ''}`,
+            ext: `.${ext}`,
+            prefix: 'picture',
+          })
+          const size = `${Math.round(Number(item.width) || 0)}x${Math.round(Number(item.height) || 0)}`
+          /* Say what the picture looks like in words: a model that cannot open
+             a file still needs to know a chart came back blank. */
+          const flat = Number(item.flat) || 0
+          const colors = Number(item.colors) || 0
+          const look = flat >= 0.9 ? 'mostly one colour' : colors <= 3 ? 'a few colours' : 'a picture with detail'
+          rows.push(`${file} ${size} ${look}`)
+        }
+        if (rows.length === 0) {
+          return list.length === 0 ? 'There is no picture on the page.' : 'That picture could not be saved.'
+        }
+        return rows.join('\n')
       }),
     },
     {
@@ -1275,13 +1918,23 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async () => {
         const state = await sidecar.state()
         const owner = String(host.owner?.() ?? '') // ui-copy-ignore
+        const session = currentSession()
+        const seats = String(host.seats?.() ?? '?') // ui-copy-ignore
+        const mine = sidecar.pageFor(session)
         const rows = [
           state.alive ? 'running' : 'stopped',
+          `chat ${session === '' ? '(no chat id)' : session}`,
+          `this chat's tab ${mine === null ? 'none' : String(mine.url)}`, // ui-copy-ignore
+          `tabs in the browser ${String(sidecar.pages.size)}`,
+          `tab list ${[...sidecar.pages.entries()].map(([key, each]) => `${key.slice(-8)}=${String(each.url)}=${each.cdp?.closed === true ? 'closed' : 'open'}`).join(' | ')}`, // ui-copy-ignore
+          `default tab ${String(sidecar.page?.url)}`, // ui-copy-ignore
           state.headless === false ? 'showing a window' : 'no window',
           `profile ${String(state.profile)}`,
           `url ${String(state.url)}`,
           `title ${String(state.title)}`,
           `viewers ${String(state.viewers)}`,
+          `listening chats ${seats}`, // ui-copy-ignore
+          `mirror owner ${owner === '' ? 'none' : owner}`, // ui-copy-ignore
           owner === '' ? 'no owner' : `owner ${owner}`,
           `refs followed ${String(follows.count)}`,
           holdText(sidecar) === '' ? 'person free' : `person using it (${String(Math.ceil(Number(sidecar.holding()) / 1000))} s left)`,
@@ -1343,7 +1996,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         let start = { x: Number(args?.x ?? NaN), y: Number(args?.y ?? NaN) }
         if (args?.from !== undefined) {
           const spot = await findAgain(page, Number(args.from))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           start = { x: Number(spot.x), y: Number(spot.y) }
         }
         const end = { x: Number(args?.to_x ?? NaN), y: Number(args?.to_y ?? NaN) }
@@ -1388,11 +2041,11 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
         if (checkRoute?.contextId !== undefined) checkParams.contextId = checkRoute.contextId
         const probe = await page.cdp.send('Runtime.evaluate', checkParams, checkRoute?.sessionId)
         const now = probe.result?.value
-        if (now === null || now === undefined) return REF_GONE
+        if (now === null || now === undefined) return spot.why ?? REF_GONE
         const want = args?.checked === undefined ? !Boolean(now.checked) : args.checked === true
         if (Boolean(now.checked) !== want) {
           const spot = await findAgain(page, Number(args.ref))
-          if (spot.gone === true) return REF_GONE
+          if (spot.gone === true) return spot.why ?? REF_GONE
           await page.mouse('mouseMoved', { x: Number(spot.x), y: Number(spot.y) })
           await page.mouse('mousePressed', { x: Number(spot.x), y: Number(spot.y) })
           await page.mouse('mouseReleased', { x: Number(spot.x), y: Number(spot.y) })
@@ -1614,18 +2267,18 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       execute: async (args) => withRawPage(async (page) => {
         const action = String(args?.action ?? 'list')
         if (action === 'list') {
-          const rows = await sidecar.tabs()
+          const rows = await sidecar.tabs(currentSession())
           if (rows.length === 0) return 'no tabs'
           return rows.map((row, i) => `${i}${row.current ? ' *' : ''} ${row.title || row.url} · ${row.url}`).join('\n')
         }
         const index = Number(args?.index ?? 0)
         if (action === 'switch') {
-          const next = await sidecar.useTab(index)
+          const next = await sidecar.useTab(index, currentSession())
           return `tab ${index} · ${String(next?.url ?? '')}`
         }
         if (action === 'close') {
-          await sidecar.closeTab(index)
-          return `closed tab ${index} · ${String(sidecar.page?.url ?? '')}`
+          await sidecar.closeTab(index, currentSession())
+          return `closed tab ${index} · ${String((sidecar.pageFor(currentSession()) ?? sidecar.page)?.url ?? '')}`
         }
         throw new Error(`sidecar: unknown action ${action}`)
       }),
@@ -1641,11 +2294,7 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       /** @returns {Promise<{text: string}>} where the PDF is. */
       execute: async () => withRawPage(async (page) => {
         const data = await page.pdf()
-        const dir = join(homedir(), SHOT_DIR)
-        await mkdir(dir, { recursive: true })
-        const file = join(dir, `sidecar-${Date.now()}.pdf`)
-        await writeFile(file, Buffer.from(data, 'base64'))
-        return file
+        return saveArtifact('pdf', data, { ext: '.pdf', prefix: 'page' })
       }),
     },
   ]