dsh-plugin-computer-use 2.4.1

package/index.js

@@ -0,0 +1,1595 @@
+/**
+ * computer-use — let the model see the desktop and drive apps, on any OS.
+ *
+ * v2 rewires the whole backend onto the Cua Driver SDK (@trycua/cua-driver):
+ * a Rust in-process computer-use runtime loaded directly into the dsh host.
+ * No daemon, no MCP server, no PowerShell scripts — `pnpm` pulls one native
+ * package per OS/arch and the tools just work (Windows tested; the same code
+ * path drives the macOS / Linux natives).
+ *
+ * v2.2 fixes the two things that made v2 unusable on a real Windows desktop:
+ *
+ * - **DPI bootstrap.** The driver's whole Windows backend measures screens,
+ *   captures pixels and maps coordinates through GetSystemMetrics/
+ *   GetWindowRect — APIs that return DPI-VIRTUALIZED values unless the host
+ *   process declared Per-Monitor-V2 awareness (upstream assumes the daemon
+ *   exe; an in-process SDK inherits the HOST, and node.exe is unaware). On a
+ *   200%-scaled primary the driver then captured only the top-left quarter of
+ *   the display and every desktop coordinate was off by the scale factor.
+ *   The plugin now flips the process to Per-Monitor-V2 via a tiny FFI call
+ *   (koffi, prebuilt binaries, no compiler) BEFORE the driver runtime is
+ *   created — after that the driver's own numbers are correct
+ *   (`get_desktop_state` returns the true 3200x2000 @2x, not a crop).
+ * - **Session lifecycle.** The driver's implicit session dies after 5 min of
+ *   idle and ended names are never revived by ordinary actions — every call
+ *   then failed with "session has ended" until the process restarted. The
+ *   plugin now runs one named session (`dsh-computer-use`) that it starts at
+ *   boot, passes explicitly on every call that accepts it, and revives with
+ *   `start_session` + one retry whenever the driver reports `session_ended`.
+ *
+ * v2.4 fixes what the session log of a real "greet a WeChat contact" run
+ * exposed — 50 idle minutes after host boot every window/app query silently
+ * answered "no windows matched" and the model fell back to pwsh + blind
+ * desktop coordinates:
+ *
+ * - **Queries carry the session label too.** `list_windows` / `list_apps` /
+ *   `launch_app` used to go untagged, hanging off the transport's implicit
+ *   session, which dies after 5 idle minutes — while the tagged action tools
+ *   kept self-healing. Now EVERY driver call except session lifecycle itself
+ *   is tagged, a stuck session escalates through end→start→retry, and one
+ *   that still won't come back triggers a full runtime rebuild (the racy
+ *   watchdog of 0.28.1 could wedge a transport for its whole lifetime; fixed
+ *   upstream in 0.28.2).
+ * - **Query errors surface.** An isError `list_windows` used to parse into an
+ *   empty table ("no windows matched"); it now throws the driver's own text.
+ * - **CJK/emoji typing goes through the clipboard.** Foreground SendInput
+ *   typing through an active IME corrupts non-ASCII text (measured: 这→！！,
+ *   👋→🙏); `computer_type` desktop= now pastes such text via the driver
+ *   clipboard and restores the user's clipboard afterwards.
+ * - **Elastic desktop coordinates.** x/y given in PHYSICAL desktop px (the
+ *   native size of a HiDPI capture) are mapped into the model frame instead
+ *   of bouncing with "outside the 1568x980 screenshot".
+ * - **`computer_screenshot save=path.png`** writes the capture to disk
+ *   (desktop captures at native resolution) and stages it on the clipboard,
+ *   so "send a screenshot into a chat" needs no pwsh detour.
+ *
+ * The driver's native paradigm is window-centric and background-first, so the
+ * tool surface speaks it now:
+ *
+ * - **Element-first.** `computer_screenshot(app=…)` returns the window's
+ *   screenshot AND its accessibility tree (indexed elements with tokens);
+ *   `computer_click(element=token)` invokes through UIA/AX — works on
+ *   backgrounded, minimized and even off-desktop windows.
+ * - **No focus stealing.** Every action defaults to `delivery_mode:
+ *   "background"`: PostMessage/UIA routes that never raise the window or move
+ *   the human's cursor. When a target genuinely drops posted input (some
+ *   Chromium/Electron surfaces), the plugin retries the same action with
+ *   `delivery_mode: "foreground"` once — the driver restores the previous
+ *   foreground afterwards.
+ * - **Keyboard-first still.** Descriptions keep pushing `computer_open` /
+ *   `computer_key` / `computer_sequence` over pixel hunts.
+ *
+ * Coordinates are pixels of the latest screenshot of the SAME target: window
+ * actions use window-local px of the last window capture; desktop-scope
+ * actions use px of the last `computer_screenshot` (primary display).
+ *
+ * Screenshots ride to the model as attachment images —
+ * `dsh-plugin-read-image-preview` renders them with its generic image card;
+ * nothing here ships a client half.
+ *
+ * @module dsh-plugin-computer-use
+ */
+
+import zlib from 'node:zlib'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'computer-use'
+export const inject = ['tools', 'attachments']
+
+export const Config = z.object({
+  /** Model-visible frame long-edge cap, in px. */
+  maxDim: z.natural().min(320).max(3840),
+  /** Settle time between the gesture and the result screenshot. */
+  settleMs: z.natural().max(5000),
+  /** 'once-per-agent': the first mutating call asks, later ones run; 'never': no own gate. */
+  askPolicy: z.union([z.const('once-per-agent'), z.const('always'), z.const('never')]),
+  /** Content-free product telemetry of the bundled Cua Driver runtime. */
+  telemetry: z.boolean(),
+  /** Windows: switch the host process to Per-Monitor-V2 DPI awareness before the
+   * driver starts (strongly recommended; set false only if some other component
+   * already owns process DPI awareness and you must not touch it). */
+  dpiAware: z.boolean(),
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Minimal PNG codec (decode → RGBA, box resize, crop, encode). Screenshots
+// arrive as 8-bit RGB/RGBA PNGs; the driver never downscales desktop captures,
+// so the model-frame cap is enforced here. No native or third-party deps.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c
+  }
+  return t
+})()
+
+function crc32(buf) {
+  let c = 0xffffffff
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+/** Decode an 8-bit non-interlaced RGB/RGBA PNG into `{ width, height, data }` (RGBA). Exported for the self-test. */
+export function pngDecode(buf) {
+  if (buf.length < 24 || buf.readUInt32BE(0) !== 0x89504e47) throw new Error('not a PNG')
+  let off = 8
+  let ihdr = null
+  const idat = []
+  while (off + 8 <= buf.length) {
+    const len = buf.readUInt32BE(off)
+    const type = buf.toString('ascii', off + 4, off + 8)
+    const data = buf.subarray(off + 8, off + 8 + len)
+    if (type === 'IHDR') {
+      ihdr = { w: data.readUInt32BE(0), h: data.readUInt32BE(4), depth: data[8], color: data[9], interlace: data[12] }
+    } else if (type === 'IDAT') idat.push(data)
+    else if (type === 'IEND') break
+    off += 12 + len
+  }
+  if (!ihdr) throw new Error('PNG without IHDR')
+  if (ihdr.depth !== 8 || ihdr.interlace !== 0 || (ihdr.color !== 2 && ihdr.color !== 6)) {
+    throw new Error('unsupported PNG (color=' + ihdr.color + ' depth=' + ihdr.depth + ' interlace=' + ihdr.interlace + ')')
+  }
+  const ch = ihdr.color === 6 ? 4 : 3
+  const stride = ihdr.w * ch
+  const raw = zlib.inflateSync(Buffer.concat(idat))
+  const out = Buffer.alloc(ihdr.w * ihdr.h * 4)
+  let pos = 0
+  let prev = Buffer.alloc(stride)
+  for (let y = 0; y < ihdr.h; y++) {
+    const filter = raw[pos++]
+    const line = Buffer.from(raw.subarray(pos, pos + stride))
+    pos += stride
+    if (filter === 1) { for (let i = ch; i < stride; i++) line[i] = (line[i] + line[i - ch]) & 0xff }
+    else if (filter === 2) { for (let i = 0; i < stride; i++) line[i] = (line[i] + prev[i]) & 0xff }
+    else if (filter === 3) { for (let i = 0; i < stride; i++) line[i] = (line[i] + (((i < ch ? 0 : line[i - ch]) + prev[i]) >> 1)) & 0xff }
+    else if (filter === 4) {
+      for (let i = 0; i < stride; i++) {
+        const a = i < ch ? 0 : line[i - ch]
+        const b = prev[i]
+        const c = i < ch ? 0 : prev[i - ch]
+        const p = a + b - c
+        const pa = Math.abs(p - a); const pb = Math.abs(p - b); const pc = Math.abs(p - c)
+        line[i] = (line[i] + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c)) & 0xff
+      }
+    } else if (filter !== 0) throw new Error('bad PNG filter ' + filter)
+    for (let x = 0; x < ihdr.w; x++) {
+      const si = x * ch
+      const di = (y * ihdr.w + x) * 4
+      out[di] = line[si]; out[di + 1] = line[si + 1]; out[di + 2] = line[si + 2]
+      out[di + 3] = ch === 4 ? line[si + 3] : 255
+    }
+    prev = line
+  }
+  return { width: ihdr.w, height: ihdr.h, data: out }
+}
+
+/** Encode RGBA as a filter-0 PNG. Exported for the self-test. */
+export function pngEncode(img) {
+  const { width, height, data } = img
+  const chunk = (type, body) => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(body.length)
+    const td = Buffer.from(type, 'ascii')
+    const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(Buffer.concat([td, body])))
+    return Buffer.concat([len, td, body, crc])
+  }
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4)
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0
+  const raw = Buffer.alloc(height * (1 + width * 4))
+  for (let y = 0; y < height; y++) {
+    raw[y * (1 + width * 4)] = 0
+    data.copy(raw, y * (1 + width * 4) + 1, y * width * 4, (y + 1) * width * 4)
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+/** Box-average resize of an RGBA image. Exported for the self-test. */
+export function resizeRgba(img, tw, th) {
+  const { width, height, data } = img
+  const out = Buffer.alloc(tw * th * 4)
+  for (let ty = 0; ty < th; ty++) {
+    const y0 = Math.floor((ty * height) / th)
+    const y1 = Math.max(y0 + 1, Math.floor(((ty + 1) * height) / th))
+    for (let tx = 0; tx < tw; tx++) {
+      const x0 = Math.floor((tx * width) / tw)
+      const x1 = Math.max(x0 + 1, Math.floor(((tx + 1) * width) / tw))
+      let r = 0; let g = 0; let b = 0; let a = 0; let n = 0
+      for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+          const i = (y * width + x) * 4
+          r += data[i]; g += data[i + 1]; b += data[i + 2]; a += data[i + 3]; n++
+        }
+      }
+      const o = (ty * tw + tx) * 4
+      out[o] = r / n; out[o + 1] = g / n; out[o + 2] = b / n; out[o + 3] = a / n
+    }
+  }
+  return { width: tw, height: th, data: out }
+}
+
+/** Crop an RGBA image (bounds clamped). Exported for the self-test. */
+export function cropRgba(img, x, y, w, h) {
+  const cx = Math.max(0, Math.min(x, img.width - 1))
+  const cy = Math.max(0, Math.min(y, img.height - 1))
+  const cw = Math.max(1, Math.min(w, img.width - cx))
+  const chh = Math.max(1, Math.min(h, img.height - cy))
+  const out = Buffer.alloc(cw * chh * 4)
+  for (let row = 0; row < chh; row++) {
+    img.data.copy(out, row * cw * 4, ((cy + row) * img.width + cx) * 4, ((cy + row) * img.width + cx + cw) * 4)
+  }
+  return { width: cw, height: chh, data: out }
+}
+
+/**
+ * Map desktop coordinates to driver desktop-space px. Pure — exported for the
+ * self-test. `frame` is { sw, sh, fw, fh }: physical screen size and the
+ * model-frame size it was downscaled to.
+ *
+ * Coordinates are expected in FRAME px (the screenshot the model sees), but
+ * ones given in PHYSICAL desktop px (the capture's native size — the model
+ * reads native-resolution features off HiDPI captures regularly) are mapped
+ * into the frame per-axis instead of bouncing the call: the roundtrip is
+ * exact, and "outside the 1568x980 screenshot" retries cost a full model
+ * round-trip for nothing. Genuinely out-of-bounds input still throws.
+ */
+export function deskMapXY(frame, x, y, label = 'coordinate') {
+  if (frame === null || typeof frame !== 'object') throw new Error('no desktop screenshot yet: call computer_screenshot first')
+  if (typeof x !== 'number' || !isFinite(x) || typeof y !== 'number' || !isFinite(y)) throw new Error(label + ' must be numbers')
+  if (x < 0 || y < 0) throw new Error(label + ' outside the ' + frame.fw + 'x' + frame.fh + ' screenshot')
+  let scaled = false
+  if (x > frame.fw) {
+    if (x > frame.sw) throw new Error(label + ' outside the ' + frame.fw + 'x' + frame.fh + ' screenshot (physical desktop is ' + frame.sw + 'x' + frame.sh + ')')
+    x = (x * frame.fw) / frame.sw
+    scaled = true
+  }
+  if (y > frame.fh) {
+    if (y > frame.sh) throw new Error(label + ' outside the ' + frame.fw + 'x' + frame.fh + ' screenshot (physical desktop is ' + frame.sw + 'x' + frame.sh + ')')
+    y = (y * frame.fh) / frame.sh
+    scaled = true
+  }
+  return { x: Math.round((x * frame.sw) / frame.fw), y: Math.round((y * frame.sh) / frame.fh), scaled }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin body
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx - plugin context.
+ * @param {{ maxDim?: number, settleMs?: number, askPolicy?: string, telemetry?: boolean }} [config]
+ */
+export function apply(ctx, config) {
+  const maxDim = config && config.maxDim !== undefined ? config.maxDim : 1568
+  const settleMs = config && config.settleMs !== undefined ? config.settleMs : 600
+  const askPolicy = config && config.askPolicy === 'always' ? 'always' : config && config.askPolicy === 'never' ? 'never' : 'once-per-agent'
+  const telemetry = !!(config && config.telemetry === true)
+  const dpiAwareCfg = !(config && config.dpiAware === false)
+  // May computer_open / window captures bring an ALREADY-RUNNING app's
+  // minimized window back to the foreground? Off = never touch the foreground.
+  const restoreCfg = !(config && config.restore === false)
+  // May computer_open walk an ALREADY-RUNNING app through its own launcher when
+  // that app exposes no window (tray state)? Off by default — see computer_open.
+  const activateRunningCfg = !!(config && config.activateRunning === true)
+  if (!telemetry) process.env.CUA_DRIVER_RS_TELEMETRY_ENABLED = '0'
+
+  // ── DPI bootstrap (Windows) ────────────────────────────────────────────────
+  // The driver assumes a Per-Monitor-V2-aware host (its daemon exe ships that
+  // manifest; upstream capture/input code comments say so outright). The
+  // in-process SDK instead inherits THIS process — and node.exe is DPI-unaware.
+  // Every screen metric the driver reads is then DPI-virtualized while BitBlt
+  // and SendInput still work in physical pixels: on a 200%-scaled primary the
+  // desktop capture silently covers only the top-left quarter of the display
+  // and all desktop coordinates drift by the scale factor. Flip the process
+  // BEFORE the driver runtime creates its worker threads (threads inherit the
+  // process context at creation); afterwards every driver number is physical.
+  /** { text, aware } — filled during the first getDriver() chain. */
+  const dpiState = { text: 'pending', aware: false }
+  const ensureProcessDpiAware = async () => {
+    if (process.platform !== 'win32') { dpiState.text = 'n/a (not Windows)'; dpiState.aware = true; return }
+    if (!dpiAwareCfg) { dpiState.text = 'skipped (dpiAware: false)'; dpiState.aware = false; return }
+    try {
+      const m = await import('koffi')
+      const koffi = m.default && m.default.load ? m.default : m
+      const user32 = koffi.load('user32.dll')
+      let shcore = null
+      try { shcore = koffi.load('shcore.dll') } catch {}
+      // PROCESS_DPI_AWARENESS: 0 unaware, 1 system, 2 per-monitor; NULL handle = this process.
+      const query = () => {
+        if (!shcore) return -1
+        try {
+          const getProc = shcore.func('int32_t GetProcessDpiAwareness(void*, int32_t*)')
+          const out = koffi.alloc('int32_t', 1)
+          if (getProc(null, out) !== 0) return -1
+          return koffi.decode(out, 'int32_t')
+        } catch { return -1 }
+      }
+      let now = query()
+      if (now !== 2) {
+        try { user32.func('bool SetProcessDpiAwarenessContext(intptr_t)')(-4) } catch {} // PER_MONITOR_AWARE_V2
+        now = query()
+        if (now === 0 || now === -1) {
+          try { user32.func('bool SetProcessDPIAware()')() } catch {}
+          now = query()
+        }
+      }
+      dpiState.aware = now >= 1
+      dpiState.text = now === 2
+        ? 'per-monitor-v2'
+        : now === 1
+          ? 'system-DPI-aware (fallback: metrics are physical, mixed-scale window captures may stretch)'
+          : now === 0
+            ? 'UNAWARE (runtime switch refused — HiDPI captures/coordinates are unreliable)'
+            : 'unknown (shcore query unsupported)'
+    } catch (e) {
+      dpiState.aware = false
+      dpiState.text = 'unknown (koffi unavailable: ' + (e && e.message ? e.message : e) + ')'
+    }
+  }
+
+  // ── named driver session ───────────────────────────────────────────────────
+  // The implicit session the runtime creates for a transport is private and,
+  // once it ends (5-minute idle TTL / explicit end), ordinary calls against it
+  // fail forever: “this session has ended; call start_session explicitly”.
+  // A public label survives that: start_session revives it and is idempotent.
+  // (`session` is not sticky server-side — repeat it.)
+  const SESSION_LABEL = 'dsh-computer-use'
+  // Every driver call is tagged with the label EXCEPT session lifecycle /
+  // transport introspection itself. The old whitelist left the queries
+  // (list_windows / list_apps / launch_app …) untagged: they hung off the
+  // transport's implicit session and were the exact calls that died after the
+  // idle TTL while the tagged action tools kept self-healing. Every plugin
+  // tool call has been verified to accept `session` on 0.28.1.
+  const NO_SESSION_TOOLS = new Set(['start_session', 'end_session', 'escalate_session', 'shutdown', 'list_tools_json', 'list_sessions', 'list_host_sessions_json', 'get_session', 'get_session_state', 'metadata', 'is_available', 'execution_mode'])
+  const isSessionEnded = (r) => r.errorCode === 'session_ended' || /session has ended|call start_session/i.test(String((r && r.text) ?? ''))
+
+  /** Lazily-created in-process Cua Driver runtime (one per profile process). */
+  let driver = null
+  let driverPromise = null
+  let driverDead = false
+  /** In-flight runtime rebuild (stuck-session escape hatch); see rebuildDriver. */
+  let rebuilding = null
+  const getDriver = () => {
+    if (driver) return Promise.resolve(driver)
+    if (driverDead) throw new Error('Cua Driver runtime was shut down; restart dsh to reactivate computer-use')
+    if (!driverPromise) {
+      driverPromise = ensureProcessDpiAware().then(() => {
+        ctx.logger.info('computer-use: host process DPI awareness = ' + dpiState.text)
+        return import('@trycua/cua-driver')
+      }).then((m) => {
+        const created = m.CuaDriver.create()
+        driver = created
+        ctx.effect(() => () => {
+          driverDead = true
+          driver = null
+          driverPromise = null
+          Promise.resolve(created.callTool('end_session', JSON.stringify({ session: SESSION_LABEL }))).catch(() => {})
+          Promise.resolve(created.shutdown()).catch(() => {})
+        })
+        return Promise.resolve(created.callTool('start_session', JSON.stringify({ session: SESSION_LABEL })))
+          .then((r) => { if (r && r.isError) ctx.logger.warn('computer-use: start_session failed: ' + String(r.text).slice(0, 160)) }, () => {})
+          .then(() => created)
+      }, (e) => { driverPromise = null; throw new Error('cannot load @trycua/cua-driver native runtime: ' + (e && e.message ? e.message : e)) })
+    }
+    return driverPromise
+  }
+
+  /** Destroy and recreate the runtime (a transport can wedge permanently —
+   *  measured on 0.28.1: after the idle TTL killed the session, no amount of
+   *  start_session revived the calls; the watchdog data race fixed upstream
+   *  in 0.28.2 is the likely culprit). Shared so concurrent callers rebuild once. */
+  const rebuildDriver = () => {
+    if (!rebuilding) {
+      rebuilding = (async () => {
+        const old = driver
+        driver = null
+        driverPromise = null
+        if (old) {
+          await Promise.resolve(old.callTool('end_session', JSON.stringify({ session: SESSION_LABEL }))).catch(() => {})
+          await Promise.resolve(old.shutdown()).catch(() => {})
+        }
+        const fresh = await getDriver()
+        ctx.logger.warn('computer-use: rebuilt the Cua Driver runtime after a stuck session')
+        return fresh
+      })().finally(() => { rebuilding = null })
+    }
+    return rebuilding
+  }
+
+  /** Call one driver tool by name; returns the parsed ToolResult. */
+  const raw = async (tool, args) => {
+    let a = args ?? {}
+    if (!NO_SESSION_TOOLS.has(tool) && a.session === undefined) a = { ...a, session: SESSION_LABEL }
+    const json = JSON.stringify(a)
+    const d = await getDriver()
+    let r = await d.callTool(tool, json)
+    if (!(r && r.isError && isSessionEnded(r))) return r
+    // Idle TTL tripped (or the transport wedged around it). A bare revive is
+    // not always enough — measured on 0.28.1, start_session can report success
+    // while the session stays dead — so end the corpse first, revive, retry…
+    await Promise.resolve(d.callTool('end_session', JSON.stringify({ session: SESSION_LABEL }))).catch(() => {})
+    const revived = await Promise.resolve(d.callTool('start_session', JSON.stringify({ session: SESSION_LABEL }))).catch(() => null)
+    if (revived === null || revived.isError) ctx.logger.warn('computer-use: session revive failed: ' + String(revived === null ? 'call threw' : revived.text).slice(0, 140))
+    r = await d.callTool(tool, json)
+    if (!(r && r.isError && isSessionEnded(r))) return r
+    // …and if it is STILL dead the runtime itself is wedged: rebuild it once.
+    const d2 = await rebuildDriver()
+    return await d2.callTool(tool, json)
+  }
+  /** Same, but throws on isError with the driver's own message. */
+  const call = async (tool, args) => {
+    const r = await raw(tool, args)
+    if (r.isError) throw new Error(tool + ': ' + String(r.text ?? 'failed').slice(0, 400))
+    return r
+  }
+  const structured = (r) => {
+    try { return JSON.parse(r.structuredJson) } catch {}
+    try { return JSON.parse(r.rawJson ?? '{}').structuredContent ?? {} } catch { return {} }
+  }
+
+  /**
+   * list_windows with the driver's errors surfaced. An isError result used to
+   * parse into an empty table — "no windows matched" — sending the model
+   * name-hunting (微信? WeChat? Weixin?) while the session was actually dead;
+   * the field log of exactly that wasted five steps before the pwsh detour.
+   */
+  const listWindows = async (args) => {
+    const r = await raw('list_windows', args)
+    if (r.isError) throw new Error('list_windows: ' + String(r.text ?? 'failed').slice(0, 300))
+    return structured(r)
+  }
+
+  const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      if (signal && signal.aborted) reject(new Error('cancelled'))
+      else resolve()
+    }, ms)
+    if (signal && typeof signal.addEventListener === 'function') {
+      signal.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('cancelled')) }, { once: true })
+    }
+  })
+
+  // ── target bookkeeping ─────────────────────────────────────────────────────
+  /** Last window the model captured or acted on; lets follow-ups omit targets. */
+  let last = null
+  /** Desktop frame mapping (get_desktop_state may be downscaled for the model). */
+  let deskFrame = null
+
+  const windowTarget = (t) => ({ kind: 'window', pid: t.pid, window_id: t.windowId })
+
+  /** Resolve {app|pid|window_id} args to {pid, windowId, title}. */
+  const resolveWindow = async (a) => {
+    if (a.app !== undefined || a.pid !== undefined) {
+      let pid
+      if (a.pid !== undefined) pid = Math.round(Number(a.pid))
+      const w = await listWindows({ on_screen_only: false })
+      const wins = w.windows ?? []
+      if (pid === undefined) {
+        const needle = String(a.app).toLowerCase()
+        const cands = wins.filter((x) => String(x.app_name ?? '').toLowerCase().includes(needle) || String(x.title ?? '').toLowerCase().includes(needle))
+        if (cands.length === 0) throw new Error('no window matches app "' + a.app + '" — check computer_windows')
+        pid = cands[0].pid
+      }
+      let mine = wins.filter((x) => x.pid === pid)
+      if (mine.length === 0) throw new Error('pid ' + pid + ' has no windows — check computer_windows')
+      if (a.window_id !== undefined) {
+        const hit = mine.find((x) => (x.window_id ?? x.windowId) === Math.round(Number(a.window_id)))
+        if (!hit) throw new Error('window_id ' + a.window_id + ' not found under pid ' + pid)
+        last = { pid, windowId: hit.window_id ?? hit.windowId, title: hit.title ?? '', app: String(a.app ?? '') }
+        return last
+      }
+      mine = mine.filter((x) => x.is_on_screen !== false)
+      mine.sort((x, y) => (y.z_index ?? 0) - (x.z_index ?? 0))
+      last = { pid, windowId: mine[0].window_id ?? mine[0].windowId, title: mine[0].title ?? '', app: String(a.app ?? '') }
+      return last
+    }
+    if (last) return last
+    throw new Error('no target: pass app (e.g. app="notepad") or pid/window_id, or capture first — see computer_windows')
+  }
+
+  // ── "is it already running?" ───────────────────────────────────────────────
+  // `launch_app` on Windows ALWAYS creates a new process (ShellExecuteEx; the
+  // `creates_new_application_instance` flag is a documented no-op there), so it
+  // can never "focus-resolve" anything. Re-running a chat app that way spawns a
+  // second, logged-out instance that begs for a fresh login — the app is
+  // already running, its (minimized / tray) window just isn't the one the model
+  // ended up looking at. Every "open this app" path therefore asks the driver's
+  // own app inventory first and reuses the live instance when there is one.
+  const normApp = (s) => String(s ?? '').trim().toLowerCase().replace(/\.exe$/, '')
+  const scoreApp = (want, cand) => {
+    const w = normApp(want)
+    const name = normApp(cand && cand.name)
+    const exe = normApp(String((cand && cand.bundle_id) ?? '').split(/[\\/]/).pop())
+    if (name === '' && exe === '') return 0
+    if (name === w || exe === w) return 100
+    if (w.length < 3) return 0
+    if (name.includes(w) || exe.includes(w)) return 60
+    if (w.includes(name) && name !== '') return 40
+    return 0
+  }
+  /**
+   * The installed-app inventory entry for `want`, or null.
+   * Only consulted on the launch path (it is the slow call); its running flags
+   * are NOT used for the "already running?" decision — the official guidance is
+   * to reason about windows from `list_windows`, and that view is also the one
+   * a reuse decision actually needs.
+   */
+  const findInstalledApp = async (want) => {
+    let apps = []
+    try {
+      const r = await raw('list_apps', {})
+      if (r.isError) throw new Error(String(r.text ?? 'list_apps failed').slice(0, 200))
+      apps = structured(r).apps ?? []
+    } catch (e) {
+      // Tolerated (the name-launch fallback still works) — but say so: a silent
+      // null here is what sent computer_open into launch_app on a dead session.
+      ctx.logger.warn('computer-use: list_apps failed (' + String(e && e.message ? e.message : e).slice(0, 160) + ') — falling back to a name-only launch')
+      return null
+    }
+    let best = null
+    let bestScore = 0
+    for (const entry of apps) {
+      const s = scoreApp(want, entry)
+      if (s > bestScore) { bestScore = s; best = entry }
+    }
+    return best === null || bestScore <= 0 ? null : best
+  }
+
+  /**
+   * How to launch an app that is not running yet.
+   * - UWP/Store: `aumid` — the docs' own advice for capturing the packaged pid;
+   *   its `launch_path` is the same `shell:appsFolder\…` string but activates
+   *   through the broker and reports pid 0.
+   * - desktop: the shortcut's full commandline (`launch_path`), so arguments
+   *   survive; falls back to the bare name.
+   */
+  const launchSelectorFor = async (want) => {
+    const entry = await findInstalledApp(want)
+    const lp = entry !== null && typeof entry.launch_path === 'string' ? entry.launch_path : ''
+    if (entry !== null && entry.kind === 'uwp') {
+      const aumid = lp.startsWith('shell:appsFolder\\') ? lp.slice('shell:appsFolder\\'.length) : ''
+      if (aumid !== '') return { aumid }
+      if (typeof entry.bundle_id === 'string' && entry.bundle_id.includes('!')) return { aumid: entry.bundle_id }
+    }
+    if (lp !== '' && !lp.startsWith('shell:appsFolder')) return { launch_path: lp }
+    return { name: want }
+  }
+
+  const windowsOf = async (pid) => {
+    const w = await listWindows({ pid })
+    const mine = (w.windows ?? []).filter((x) => x.pid === pid)
+    const onScreen = mine.filter((x) => x.is_on_screen !== false)
+    const pick = (onScreen.length > 0 ? onScreen : mine).slice()
+    pick.sort((x, y) => (y.z_index ?? 0) - (x.z_index ?? 0))
+    return pick
+  }
+
+  /**
+   * Find an EXISTING window for an app by name / exe / title, across every pid.
+   * Never bind to the pid `list_apps` reports: for freshly started packaged apps
+   * that pid can be a launcher that owns no window (Win11 Notepad: the app entry
+   * points at one process while the window belongs to another that appears a
+   * moment later), so a pid-scoped lookup silently finds nothing and the caller
+   * would launch a second instance.
+   */
+  const findAppWindow = async (want, preferPid) => {
+    const w = structured(await raw('list_windows', { on_screen_only: false }))
+    const w0 = normApp(want)
+    const scored = []
+    for (const x of w.windows ?? []) {
+      const app = normApp(x.app_name)
+      const title = String(x.title ?? '').toLowerCase()
+      let score = 0
+      if (app !== '' && app === w0) score = 100
+      else if (app !== '' && w0.length >= 3 && app.includes(w0)) score = 70
+      else if (title !== '' && w0.length >= 3 && title.includes(w0)) score = 45
+      if (score === 0) continue
+      if (x.is_on_screen !== false) score += 10
+      if (preferPid !== undefined && x.pid === preferPid) score += 25
+      scored.push({ score, z: x.z_index ?? 0, x })
+    }
+    if (scored.length === 0) return null
+    scored.sort((a, b) => (b.score - a.score) || (b.z - a.z))
+    const win = scored[0].x
+    return { pid: win.pid, windowId: win.window_id ?? win.windowId, title: win.title ?? '', app: want, minimized: win.minimized === true }
+  }
+
+  /** windowsOf(pid), falling back to a name match (see findAppWindow). */
+  const windowFor = async (want, pid) => {
+    if (pid !== undefined && pid !== null && Number(pid) > 0) {
+      const mine = await windowsOf(Math.round(Number(pid)))
+      if (mine.length > 0) {
+        const w = mine[0]
+        return { pid: Math.round(Number(pid)), windowId: w.window_id ?? w.windowId, title: w.title ?? '', app: want, minimized: w.minimized === true }
+      }
+    }
+    return await findAppWindow(want, pid)
+  }
+
+  /**
+   * launch_app + wait for a window to show up.
+   * `selector` is an app name string or a full argument object ({name}|{path}|{aumid}|{launch_path}).
+   * Returns { pid, target } where `target` is a resolvable window (or null).
+   */
+  const launchAndSettle = async (selector, settle, signal) => {
+    const args = typeof selector === 'string' ? { name: selector } : selector
+    const want = typeof args.name === 'string' ? args.name : String(args.path ?? args.aumid ?? args.launch_path ?? '')
+    const r = await call('launch_app', args)
+    const sc = structured(r)
+    const pid = sc.pid
+    const first = (sc.windows ?? [])[0]
+    if (first !== undefined) {
+      return { pid, target: { pid: first.pid ?? pid, windowId: first.window_id ?? first.windowId, title: first.title ?? '', app: want, minimized: first.minimized === true } }
+    }
+    // A packaged-app launch (launch_path/aumid) reports pid 0 and no windows —
+    // measured behaviour — so a name lookup must come first instead of burning
+    // the whole settle budget on a pid that cannot ever match. Such launches are
+    // also slow to settle (measured ~9 s for Win11 Notepad), so pid 0 gets a
+    // longer window than the pid-scoped path.
+    const budget = (pid === 0 ? settle + 10000 : settle + 4000)
+    for (let waited = 0; waited < budget; waited += 400) {
+      // Not pid-scoped on purpose: the launcher pid may own no window at all.
+      const t = await windowFor(want, pid)
+      if (t !== null) return { pid: t.pid, target: t }
+      await sleep(400, signal)
+    }
+    // The launch reported success but nothing appeared. Distinguish "still
+    // starting" from "started and died" so the model is not told a dead launch
+    // succeeded (a name-only launch on this driver can exit within seconds).
+    let died = false
+    if (Number(pid) > 0) {
+      try {
+        const r = await raw('list_apps', {})
+        // An errored inventory must not read as "the process died": unknown
+        // stays unknown (died=false) rather than telling the model the app
+        // exited when the real problem is the driver call.
+        if (!r.isError) {
+          const seen = structured(r).apps ?? []
+          died = !seen.some((x) => Math.round(Number(x.pid)) === Math.round(Number(pid)))
+        }
+      } catch {}
+    }
+    return { pid, target: null, died }
+  }
+
+  // ── capture ────────────────────────────────────────────────────────────────
+  const IMAGE_VALUE = {
+    type: 'object', additionalProperties: false, required: true,
+    properties: {
+      attachmentId: { type: 'string', required: true },
+      mediaType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'], required: true },
+      bytes: { type: 'integer', required: true },
+      width: { type: 'integer', required: true },
+      height: { type: 'integer', required: true },
+    },
+  }
+  const SHOT_VALUE = {
+    type: 'object', additionalProperties: false,
+    properties: {
+      summary: { type: 'string', required: true },
+      frameText: { type: 'string', required: true },
+      elements: { type: 'string' },
+      image: IMAGE_VALUE,
+    },
+  }
+  const SHOT_RENDER = { schema: SHOT_VALUE, render: (_a, v) => [
+    { type: 'text', text: v.summary + '\n' + v.frameText + (v.elements ? '\n\n' + v.elements : '') },
+    { type: 'image', attachment: v.image },
+  ] }
+
+  const attach = async (png, name) => {
+    const ref = await ctx.attachments.saveImage({ data: png, mediaType: 'image/png', name })
+    return { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height }
+  }
+
+  const renderElements = (els, total) => {
+    if (!els || els.length === 0) return ''
+    const CAP = 80
+    const lines = els.slice(0, CAP).map((e) => {
+      const label = String(e.label ?? '').replace(/\s+/g, ' ').slice(0, 60)
+      const acts = (e.actions ?? []).join('/')
+      return e.element_index + ' ' + (e.role ?? '?') + (label ? ' "' + label + '"' : '') + (acts ? ' [' + acts + ']' : '') + ' ' + e.element_token
+    })
+    let out = 'ELEMENTS (element= + token; from THIS snapshot only):\n' + lines.join('\n')
+    if (els.length > CAP) out += '\n… ' + (els.length - CAP) + ' more; pass query= to filter'
+    else if (total > els.length) out += '\n(' + total + ' elements total; pass query= to project)'
+    return out
+  }
+
+  /** Best-effort: bring an existing window back from minimized / off-screen. */
+  const restoreWindow = async (pid, windowId) => {
+    if (!restoreCfg) return { ok: false, detail: 'disabled (config restore: false)' }
+    try {
+      const r = await call('bring_to_front', { pid, window_id: windowId })
+      const sc = structured(r)
+      return { ok: true, detail: 'previous_fg=' + String(sc.previous_fg_hwnd ?? '?') + ' now_fg=' + String(sc.now_fg_hwnd ?? '?') }
+    } catch (e) {
+      return { ok: false, detail: String(e && e.message ? e.message : e).slice(0, 200) }
+    }
+  }
+
+  /**
+   * Write a capture to disk and stage it on the clipboard. `computer_screenshot
+   * save=` exists so "attach a proof screenshot in a chat" stops being a pwsh
+   * detour (which first had to rediscover DPI awareness, measured) — the file
+   * lands on disk AND on the clipboard, ready for a computer_key ctrl+v.
+   */
+  const saveCapture = async (path, png) => {
+    if (typeof path !== 'string' || !/\.png$/i.test(String(path).trim())) throw new Error('save must be a file path ending in .png')
+    const fs = await import('node:fs')
+    const { dirname } = await import('node:path')
+    const target = String(path).trim()
+    await fs.promises.mkdir(dirname(target), { recursive: true })
+    await fs.promises.writeFile(target, png)
+    let clip = ''
+    try {
+      await call('clipboard_write', { image_path: target })
+      clip = ' and copied onto the clipboard (computer_key desktop ctrl+v pastes it)'
+    } catch (e) {
+      clip = ' (clipboard copy failed: ' + String(e && e.message ? e.message : e).slice(0, 120) + ')'
+    }
+    return 'Saved to ' + target + clip
+  }
+
+  /** Window capture → screenshot (+ optional element tree) SHOT value. */
+  const captureWindow = async (t, opts) => {
+    const includeTree = !(opts && opts.tree === false)
+    const build = () => {
+      const args = { pid: t.pid, window_id: t.windowId, include_accessibility_tree: includeTree }
+      if (opts && opts.query) args.query = opts.query
+      return args
+    }
+    let restored = ''
+    let r
+    const grab = () => call('get_window_state', build())
+    try {
+      r = await grab()
+    } catch (e) {
+      // A minimized window has no rendered content: the driver bails instead of
+      // handing back an all-black PNG. When the caller allows it, restore the
+      // window once and retry — otherwise teach the model the exact remedy.
+      const msg = String(e && e.message ? e.message : e)
+      if (!(opts && opts.restoreMinimized === true) || !/minimized window/i.test(msg)) throw e
+      const res = await restoreWindow(t.pid, t.windowId)
+      if (!res.ok) {
+        throw new Error('window ' + t.windowId + ' is minimized and could not be restored (' + res.detail + ') — the app is running, but its window is not visible; ask the user to restore it, then retry ' + msg.slice(0, 160))
+      }
+      restored = ' [was minimized — restored via bring_to_front (' + res.detail + '); the no-foreground contract is broken for this call]'
+      await sleep(settleMs, opts && opts.signal)
+      r = await grab()
+    }
+    let sc = structured(r)
+    let png = Buffer.from((r.images[0] && r.images[0].dataBase64) ?? '', 'base64')
+    let didRestore = restored !== ''
+    // A minimized window can fail in two different ways: the driver either
+    // throws ("cannot capture minimized window") or hands back an EMPTY image
+    // (measured on a window launched minimized). Handle the empty case here —
+    // without it, "open a not-yet-running app" dies on a bare
+    // "window capture returned no image".
+    if (png.length === 0 && opts && opts.restoreMinimized === true && !didRestore) {
+      const known = opts.windowHint
+      const looksMinimized = known === undefined ? true : known.minimized === true
+      if (looksMinimized) {
+        const res = await restoreWindow(t.pid, t.windowId)
+        if (res.ok) {
+          didRestore = true
+          restored = ' [was minimized — restored via bring_to_front (' + res.detail + '); the no-foreground contract is broken for this call]'
+          await sleep(settleMs, opts && opts.signal)
+          const r2 = await grab()
+          const png2 = Buffer.from((r2.images[0] && r2.images[0].dataBase64) ?? '', 'base64')
+          if (png2.length > 0) { r = r2; png = png2; sc = structured(r2) }
+        }
+      }
+    }
+    if (png.length === 0) throw new Error('window capture returned no image' + (didRestore ? ' (even after restoring the minimized window)' : ''))
+    const els = sc.elements ?? []
+    if (els.length > 0) last = { ...t, tokensByIndex: Object.fromEntries(els.map((e) => [e.element_index, e.element_token])) }
+    // Window captures arrive pre-resized by the driver (set_config max_image_
+    // dimension), so a saved file is capped at the model frame — only the
+    // desktop path can write true native resolution.
+    let saved = ''
+    if (typeof (opts && opts.save) === 'string' && opts.save !== '') saved = ' ' + (await saveCapture(opts.save, png))
+    return {
+      summary: ((opts && opts.summary) || ('Window "' + (sc.window_title ?? t.title ?? '') + '" captured (pid ' + t.pid + ', window ' + t.windowId + ').')) + restored + saved,
+      frameText: 'Coordinates for this window = pixels of THIS image (window-local, top-left origin). Screen bounds: ' + JSON.stringify(sc.window_bounds ?? {}) + '.',
+      elements: renderElements(els, sc.total_element_count ?? els.length),
+      image: await attach(png, 'win.png'),
+    }
+  }
+
+  /**
+   * Window capture with the two degradations the driver needs help with:
+   * a hung UIA tree (retry screenshot-only) and a STALE hwnd (re-resolve the
+   * window by pid/name and retry once). Window ids are volatile — `launch_app`
+   * can hand back an hwnd that is already gone by the time the capture runs —
+   * so a handle is never treated as ground truth.
+   */
+  const shotFor = async (target, opts) => {
+    try {
+      return await captureWindow(target, opts)
+    } catch (e) {
+      const msg = String(e && e.message ? e.message : e)
+      if (/timed out|unresponsive/i.test(msg)) {
+        const shot = await captureWindow(target, { ...opts, tree: false })
+        return { ...shot, summary: shot.summary + ' (element tree unavailable: the UIA provider did not answer — act by pixel from this screenshot, or re-capture later)' }
+      }
+      if (/No window with window_id|window_id .*not found|no longer exists|invalid window/i.test(msg)) {
+        const app = target.app ?? (opts && opts.windowHint && opts.windowHint.app)
+        const fresh = app === undefined ? null : await windowFor(app, target.pid)
+        if (fresh !== null) {
+          const shot = await captureWindow(fresh, { ...opts, windowHint: fresh })
+          return { ...shot, summary: shot.summary + ' (the window handle had changed — re-resolved it by pid/name before capturing)' }
+        }
+      }
+      throw e
+    }
+  }
+
+  /** Primary-desktop capture → SHOT value. `save` writes the ORIGINAL
+   *  full-resolution PNG (before the model-frame downscale) to disk. */
+  const captureDesktop = async (summary, save) => {
+    const r = await call('get_desktop_state', {})
+    const sc = structured(r)
+    const png = Buffer.from((r.images[0] && r.images[0].dataBase64) ?? '', 'base64')
+    if (png.length === 0) throw new Error('desktop capture returned no image')
+    let img = pngDecode(png)
+    const long = Math.max(img.width, img.height)
+    if (long > maxDim) img = resizeRgba(img, Math.round((img.width * maxDim) / long), Math.round((img.height * maxDim) / long))
+    deskFrame = { sw: sc.screen_width ?? img.width, sh: sc.screen_height ?? img.height, fw: img.width, fh: img.height }
+    const scale = typeof sc.scale_factor === 'number' && sc.scale_factor > 0 ? ' @' + sc.scale_factor + 'x' : ''
+    const dpiWarn = dpiState.aware ? '' : ' ⚠ host DPI awareness inactive (' + dpiState.text + ') — on scaled displays this frame may cover only part of the primary display and desktop coordinates drift; prefer window-scoped actions via app=.'
+    let saved = ''
+    if (typeof save === 'string' && save !== '') saved = ' ' + (await saveCapture(save, png))
+    return {
+      summary: (summary ?? 'Primary display captured') + ' (' + sc.screen_width + 'x' + sc.screen_height + scale + ' px' + dpiWarn + ')' + saved,
+      frameText: 'Desktop coordinate frame = pixels of THIS image (top-left origin of the PRIMARY display). Windows on OTHER monitors are NOT in this image — capture and act on them via app=/computer_windows.',
+      image: await attach(pngEncode(img), 'desktop.png'),
+    }
+  }
+
+  /** Frame px → driver desktop-space px (physical-px input auto-mapped; see deskMapXY). */
+  const deskXY = (x, y, label) => deskMapXY(deskFrame, x, y, label)
+
+  // ── action plumbing ────────────────────────────────────────────────────────
+  const agentsGranted = new Set()
+  const agentKey = (agent) => (agent && typeof agent.id === 'string' && agent.id !== '') ? agent.id : '__no-agent__'
+
+  // The harness approval service ('approval') owns a per-session policy: 'ask'
+  // prompts, 'never' (approvals disabled / full-access mode) auto-REJECTS every
+  // ask. Emitting ask there would only self-block, so when the session cannot
+  // prompt we pass actions through — the user's global policy is the gate.
+  //
+  // effectivePolicy is private upstream; the public overrideOf(session) reads
+  // the session's own 'approval/policy' fold and misses only the configured
+  // default (policy: never, i.e. danger-full-access deployments). Probe both
+  // shapes; when neither resolves, assume the session CANNOT be prompted — an
+  // unnecessary ask under 'never' is auto-rejected and locks every tool, while
+  // a skipped ask under 'ask' still surfaces in the next screenshot.
+  const approval = ctx.get('approval')
+  const sessionRefusesPrompt = (exec) => {
+    const session = exec && exec.agent && exec.agent.session
+    if (approval === undefined || session === undefined) return false
+    try {
+      // Most complete first: session fold + configured default in one answer.
+      if (typeof approval.effectivePolicy === 'function') return approval.effectivePolicy(session) === 'never'
+      // Public API: the session's own 'approval/policy' fold, else undefined.
+      if (typeof approval.overrideOf === 'function') {
+        const override = approval.overrideOf(session)
+        if (override === 'never') return true
+        if (override === 'ask') return false
+      }
+      // Configured deployment default ('never' under danger-full-access).
+      const policy = approval.config && approval.config.policy
+      const value = policy && typeof policy.get === 'function' ? policy.get() : policy
+      if (value === 'never') return true
+      if (value === 'ask') return false
+    } catch { /* undecidable: fall through */ }
+    // No probe resolved: assume prompting is impossible. An ask the approval
+    // service would auto-reject locks every gated tool; passing through only
+    // risks an unasked action, which the next screenshot still reveals.
+    return true
+  }
+
+  const isEscalationHint = (r) => {
+    const blob = String(r.text ?? '') + String(r.rawJson ?? '')
+    // XAML hotkey refusals are NOT escalatable (the UIA-accelerator route ignores
+    // delivery_mode) — their guidance must reach the model verbatim instead.
+    return /background_unavailable|"effect":"refused"|not accepted in the background/i.test(blob)
+  }
+
+  /**
+   * Run one input call: background first; if the driver refuses the background
+   * route, retry the exact same call in foreground mode (driver restores the
+   * previous foreground afterwards).
+   */
+  const action = async (tool, base) => {
+    const r = await raw(tool, base)
+    if (r.isError && isEscalationHint(r)) {
+      const r2 = await raw(tool, { ...base, delivery_mode: 'foreground' })
+      if (r2.isError) throw new Error(tool + ': ' + String(r2.text ?? 'failed').slice(0, 400))
+      r2.escalated = true
+      return r2
+    }
+    if (r.isError) throw new Error(tool + ': ' + String(r.text ?? 'failed').slice(0, 400))
+    return r
+  }
+  const actionNote = (r) => (r.escalated ? ' [background input was refused; re-delivered with a brief foreground swap]' : /"effect":"suspected_noop"/.test(String(r.rawJson ?? '')) ? ' [driver suspects the target ignored the input — verify on the screenshot]' : '')
+
+  /**
+   * Press one chord. XAML/WinUI/UWP targets have no hotkey route beyond a
+   * discoverable UIA AcceleratorKey (hidden menu items are invisible, so
+   * ctrl+something often cannot be found) — when hotkey refuses, fall back to
+   * press_key with a modifiers array in FOREGROUND: a real SendInput chord the
+   * target's input pipeline cannot ignore; the driver restores the previous
+   * foreground after the keystrokes flush.
+   */
+  const pressChord = async (targetArg, mods, key) => {
+    if (mods.length === 0) return await action('press_key', { ...targetArg, key })
+    const r = await raw('hotkey', { ...targetArg, keys: [...mods, key] })
+    if (!r.isError) return r
+    // Windows gates SetForegroundWindow (foreground lock), so the first swap can
+    // be refused with foreground_unavailable; the delivery attempt itself grants
+    // the process foreground rights, making a quick retry usually succeed.
+    let r2 = await raw('press_key', { ...targetArg, key, modifiers: mods, delivery_mode: 'foreground' })
+    if (r2.isError && /foreground_unavailable/i.test(String(r2.text ?? '') + String(r2.rawJson ?? ''))) {
+      await sleep(350)
+      r2 = await raw('press_key', { ...targetArg, key, modifiers: mods, delivery_mode: 'foreground' })
+    }
+    if (r2.isError) throw new Error('hotkey ' + mods.join('+') + '+' + key + ': ' + String(r.text ?? 'failed').slice(0, 260) + ' (foreground fallback too: ' + String(r2.text ?? 'failed').slice(0, 160) + ')')
+    r2.escalated = true
+    return r2
+  }
+
+  // ── key vocabulary (driver names) ─────────────────────────────────────────
+  const KEY_ALIAS = {
+    enter: 'return', return: 'return', esc: 'escape', escape: 'escape', tab: 'tab', space: 'space',
+    backspace: 'backspace', delete: 'delete', del: 'delete', insert: 'insert',
+    home: 'home', end: 'end', pageup: 'pageup', pagedown: 'pagedown', pgup: 'pageup', pgdn: 'pagedown',
+    up: 'up', down: 'down', left: 'left', right: 'right',
+    win: 'win', meta: 'win', cmd: 'win', super: 'win',
+    ctrl: 'ctrl', control: 'ctrl', alt: 'alt', option: 'alt', shift: 'shift',
+  }
+  const keyName = (tok) => {
+    const t = tok.toLowerCase()
+    if (KEY_ALIAS[t]) return KEY_ALIAS[t]
+    if (/^f([1-9]|1[0-2])$/.test(t)) return t
+    if (/^.$/.test(t)) return t // letters, digits, simple punctuation
+    return null
+  }
+  const parseKeys = (spec) => {
+    const toks = String(spec).toLowerCase().split('+').map((t) => t.trim()).filter((t) => t !== '')
+    if (toks.length === 0) throw new Error('keys must look like "ctrl+s" or "alt+F4"')
+    const mods = []
+    let key = null
+    for (const t of toks) {
+      const n = keyName(t)
+      if (n === null) throw new Error('unknown key "' + t + '" (a-z, 0-9, f1-f12, enter, esc, tab, space, backspace, delete, insert, home, end, pageup, pagedown, up, down, left, right, ctrl, alt, shift, win)')
+      if (n === 'ctrl' || n === 'alt' || n === 'shift' || n === 'win') mods.push(n)
+      else key = n
+    }
+    if (key === null) throw new Error('chord needs one non-modifier key after the modifiers')
+    return { mods, key }
+  }
+
+  const COORD_DESC = 'Coordinate frames: with a window target, x/y are pixels of the LAST computer_screenshot OF THAT WINDOW; desktop scope uses pixels of the last desktop screenshot (physical-desktop px are auto-mapped into the frame).'
+  const KEYB_FIRST = ' KEYBOARD-FIRST: prefer computer_open / computer_key / computer_sequence over pixel clicks whenever a keyboard path exists. ELEMENT-FIRST: if the last window screenshot listed an element for the target, click by its element= token — it works on backgrounded/minimized windows and never touches the user\'s cursor.'
+  const register = (definition) => ctx.effect(() => ctx.tools.register(defineTool(definition)), 'computer-use: tool ' + definition.name)
+
+  /** Shared action wrapper: grant, run, settle, re-capture the acted-on view. */
+  const actAndShot = async (exec, grant, summary, run) => {
+    grant()
+    const r = await run()
+    const note = actionNote(r) + (r.fallbackNote ?? '') + (r.verification && r.verification.verified === false ? ' [driver could not verify the effect]' : '')
+    await sleep(settleMs, exec.signal)
+    let value
+    if (r.scopeView === 'desktop') value = await captureDesktop(summary + note)
+    else value = await shotFor(r.target ?? last, { tree: false, summary: summary + note })
+    return value
+  }
+  const granting = (exec) => { agentsGranted.add(agentKey(exec.agent)) }
+
+  // Foreground SendInput typing goes through the ACTIVE IME, which corrupts
+  // non-ASCII text — measured on a real run: 这→！！, computer-use→computer--se,
+  // 👋(U+1F44B)→🙏(U+1F64F). Route such text through the driver clipboard and a
+  // real ctrl+v instead, restoring the user's clipboard afterwards (best-effort:
+  // a non-text clipboard cannot be saved and is left as the pasted text).
+  const NON_ASCII = /[^\x00-\x7F]/
+  const pasteDesktop = (exec, text) => actAndShot(exec, () => granting(exec),
+    'Pasted ' + text.length + ' chars into the foreground app (non-ASCII text is clipboard-pasted; typing it directly corrupts it through the IME).',
+    async () => {
+      let saved = null
+      try {
+        const r = await raw('clipboard_read', { include_text: true })
+        if (!r.isError && typeof structured(r).text === 'string') saved = structured(r).text
+      } catch {}
+      let clipErr = null
+      try {
+        await call('clipboard_write', { text })
+      } catch (e) { clipErr = e }
+      if (clipErr !== null) {
+        // Clipboard unavailable: degrade to direct typing rather than failing.
+        const r = await action('type_text', { target: { kind: 'desktop', display_id: 'primary' }, text })
+        r.fallbackNote = ' [clipboard unavailable (' + String(clipErr && clipErr.message ? clipErr.message : clipErr).slice(0, 120) + ') — typed directly; the IME may have corrupted non-ASCII chars, verify on the screenshot]'
+        return r
+      }
+      const r = await pressChord({ target: { kind: 'desktop', display_id: 'primary' } }, ['ctrl'], 'v')
+      // Let the target consume the paste before putting the user's text back.
+      if (saved !== null && saved !== text) {
+        const prev = saved
+        setTimeout(() => { raw('clipboard_write', { text: prev }).catch(() => {}) }, 800)
+      }
+      return r
+    })
+
+  // ── tools ──────────────────────────────────────────────────────────────────
+  register({
+    name: 'computer_screenshot',
+    description: 'Capture a WINDOW (default target: the last window acted on) or the PRIMARY desktop. A window capture returns the screenshot PLUS the accessibility tree elements (indexed, with element= tokens valid for the NEXT action against that window). Pass app="name" to target any app — including windows on other monitors, hidden, or minimized. No args = desktop overview. save="path.png" additionally writes the capture to disk (desktop captures at native resolution, window captures at the frame cap) and puts it on the clipboard — use it whenever a file or a pasteable screenshot is the goal instead of a pwsh detour. ' + COORD_DESC,
+    parameters: {
+      app: { type: 'string', description: 'App/window name to capture (substring match), e.g. "notepad", "Chrome".' },
+      pid: { type: 'number', description: 'Target pid (alternative to app).' },
+      window_id: { type: 'number', description: 'Exact window under pid (from computer_windows).' },
+      query: { type: 'string', description: 'Project the element list to this case-insensitive substring (window captures).' },
+      desktop: { type: 'boolean', description: 'true = force the primary-desktop capture.' },
+      elements: { type: 'boolean', description: 'false = skip the accessibility tree (screenshot only).' },
+      save: { type: 'string', description: 'Optional absolute .png path: also write the capture to disk and stage it on the system clipboard (paste with computer_key desktop ctrl+v).' },
+    },
+    output: SHOT_RENDER,
+    isConcurrencySafe: () => true,
+    timeoutMs: 30000,
+    async execute(a) {
+      const save = typeof a.save === 'string' && a.save !== '' ? a.save : undefined
+      if (a.desktop === true || (a.app === undefined && a.pid === undefined && a.window_id === undefined && last === null)) {
+        return await captureDesktop(undefined, save)
+      }
+      if (a.desktop === undefined && a.app === undefined && a.pid === undefined && a.window_id === undefined) {
+        return await shotFor(last, { tree: a.elements !== false, save })
+      }
+      const t = await resolveWindow(a)
+      return await shotFor(t, { tree: a.elements !== false, query: typeof a.query === 'string' ? a.query : undefined, save })
+    },
+  })
+
+  register({
+    name: 'computer_windows',
+    description: 'List all top-level windows: pid, window_id, app name, title, screen bounds, z-order, on-screen flag. Read-only. Use it to find the pid/window_id for screenshots and actions, or to see what is open on monitors the desktop screenshot does not cover.',
+    parameters: {
+      app: { type: 'string', description: 'Optional substring filter on app name / title.' },
+      on_screen_only: { type: 'boolean', description: 'Drop off-screen/minimized windows. Default false (they are capturable!).' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { table: { type: 'string', required: true } } },
+      render: (_a, v) => [{ type: 'text', text: v.table }],
+    },
+    isConcurrencySafe: () => true,
+    timeoutMs: 15000,
+    async execute(a) {
+      const sc = await listWindows({ on_screen_only: a.on_screen_only === true })
+      let wins = sc.windows ?? []
+      if (a.app !== undefined) {
+        const needle = String(a.app).toLowerCase()
+        wins = wins.filter((x) => String(x.app_name ?? '').toLowerCase().includes(needle) || String(x.title ?? '').toLowerCase().includes(needle))
+      }
+      if (wins.length === 0) return { table: 'no windows matched' }
+      const rows = wins.slice(0, 40).map((w) => 'pid=' + w.pid + ' win=' + (w.window_id ?? w.windowId) + (w.is_on_screen === false ? ' [off-screen]' : '') + (w.minimized ? ' [minimized]' : '') + ' z=' + (w.z_index ?? '?') + ' ' + JSON.stringify(w.app_name ?? '') + ' ' + JSON.stringify(String(w.title ?? '').slice(0, 60)) + ' ' + JSON.stringify(w.bounds ?? {}))
+      return { table: rows.join('\n') + (wins.length > 40 ? '\n… ' + (wins.length - 40) + ' more (filter with app=)' : '') }
+    },
+  })
+
+  register({
+    name: 'computer_click',
+    description: 'Click IN A TARGET WINDOW (background — your cursor and focus are untouched) or on the desktop. Addressing, best first: element=<token from the last computer_screenshot of that window>; else window-local x,y of that window screenshot (the driver UIA hit-tests first, then posts raw events); else desktop x,y for taskbar/wallpaper. button=left|right|middle, clicks=1-3, keys=modifier chord held during the click. ' + COORD_DESC,
+    parameters: {
+      app: { type: 'string', description: 'Target app (default: last captured window). Omit with x,y only for DESKTOP clicks.' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      element: { type: 'string', description: 'element token from the last window capture.' },
+      x: { type: 'number', description: 'X px of the last screenshot of the SAME target.' },
+      y: { type: 'number', description: 'Y px of the last screenshot of the SAME target.' },
+      button: { type: 'string', description: 'left | right | middle. Default left.' },
+      clicks: { type: 'number', description: 'Click count 1-3. Default 1.' },
+      keys: { type: 'string', description: 'Optional held modifiers, e.g. "ctrl" or "ctrl+shift". Windows background clicks DROP modifiers (UIA/PostMessage carry no key state) — they land only when the click escalates to foreground.' },
+      desktop: { type: 'boolean', description: 'true = click on the primary desktop at desktop-screenshot x,y (moves the real pointer).' },
+      from_zoom: { type: 'boolean', description: 'true = x,y are pixels of the latest computer_zoom image of this window (the driver maps them back to window coordinates).' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 30000,
+    async execute(a, exec) {
+      const button = a.button === undefined ? 'left' : String(a.button)
+      if (button !== 'left' && button !== 'right' && button !== 'middle') throw new Error('button must be left|right|middle')
+      const count = a.clicks === undefined ? 1 : Math.round(Number(a.clicks))
+      if (!(count >= 1 && count <= 3)) throw new Error('clicks must be 1-3')
+      const modifier = a.keys === undefined ? undefined : parseKeys(a.keys).mods
+      let where
+      let deskNote = ''
+      if (a.desktop === true || (a.app === undefined && a.pid === undefined && a.element === undefined && last === null)) {
+        if (a.x === undefined || a.y === undefined) throw new Error('desktop click needs x,y (pixels of the last desktop screenshot)')
+        const p = deskXY(Number(a.x), Number(a.y), 'click target')
+        if (p.scaled) deskNote = ' [x,y were physical desktop px — mapped into the screenshot frame]'
+        where = { target: { kind: 'desktop', display_id: 'primary' }, x: p.x, y: p.y }
+      } else {
+        const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : (last ?? await resolveWindow(a))
+        if (typeof a.element === 'string' && a.element !== '') {
+          // element_token uses the legacy addressing form: token + its (pid, window_id) scope.
+          where = { pid: t.pid, window_id: t.windowId, element_token: a.element }
+        } else {
+          if (a.x === undefined || a.y === undefined) throw new Error('pass element= or window-local x,y (pixels of the last computer_screenshot of this window)')
+          where = { target: windowTarget(t), x: Number(a.x), y: Number(a.y) }
+        }
+      }
+      const desc = 'Clicked ' + button + (count > 1 ? ' x' + count : '') + (a.keys ? ' holding ' + a.keys : '') + (a.element ? ' on element ' + a.element : a.x !== undefined ? ' at (' + a.x + ',' + a.y + ')' : '') + '.' + deskNote
+      return await actAndShot(exec, () => granting(exec), desc, async () => {
+        const r = await action('click', { ...where, button, count, ...(modifier ? { modifier } : {}), ...(a.from_zoom === true ? { from_zoom: true } : {}) })
+        r.scopeView = where.target && where.target.kind === 'desktop' ? 'desktop' : 'window'
+        return r
+      })
+    },
+  })
+
+  register({
+    name: 'computer_drag',
+    description: 'Press-drag-release in a target window (window-local px of its last screenshot) or on the desktop (desktop px, real pointer). Title-bar/resize drags cannot be posted in background — the plugin auto-escalates those to foreground. moves real windows; prefer app-internal drags on content only.',
+    parameters: {
+      app: { type: 'string' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      fromX: { type: 'number', required: true },
+      fromY: { type: 'number', required: true },
+      toX: { type: 'number', required: true },
+      toY: { type: 'number', required: true },
+      desktop: { type: 'boolean', description: 'true = drag on the primary desktop (coordinates from the last desktop screenshot).' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 30000,
+    async execute(a, exec) {
+      let args
+      let view
+      let deskNote = ''
+      if (a.desktop === true || (a.app === undefined && a.pid === undefined && last === null)) {
+        const p1 = deskXY(Number(a.fromX), Number(a.fromY), 'drag start')
+        const p2 = deskXY(Number(a.toX), Number(a.toY), 'drag end')
+        if (p1.scaled || p2.scaled) deskNote = ' [coordinates were physical desktop px — mapped into the screenshot frame]'
+        args = { target: { kind: 'desktop', display_id: 'primary' }, from_x: p1.x, from_y: p1.y, to_x: p2.x, to_y: p2.y }
+        view = 'desktop'
+      } else {
+        const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : last
+        args = { target: windowTarget(t), from_x: Number(a.fromX), from_y: Number(a.fromY), to_x: Number(a.toX), to_y: Number(a.toY) }
+        view = 'window'
+      }
+      return await actAndShot(exec, () => granting(exec), 'Dragged (' + a.fromX + ',' + a.fromY + ') → (' + a.toX + ',' + a.toY + ').' + deskNote, async () => {
+        const r = await action('drag', args)
+        r.scopeView = view
+        return r
+      })
+    },
+  })
+
+  register({
+    name: 'computer_scroll',
+    description: 'Scroll a target window (posted to the window — background, no pointer move). direction=up|down|left|right, amount=1-20 ticks (default 3), by=line|page (default line).',
+    parameters: {
+      app: { type: 'string' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      direction: { type: 'string', required: true, description: 'up | down | left | right.' },
+      amount: { type: 'number', description: 'Scroll ticks 1-20. Default 3.' },
+      by: { type: 'string', description: 'line | page. Default line.' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 30000,
+    async execute(a, exec) {
+      const direction = String(a.direction)
+      if (!['up', 'down', 'left', 'right'].includes(direction)) throw new Error('direction must be up|down|left|right')
+      const amount = a.amount === undefined ? 3 : Math.round(Number(a.amount))
+      if (!(amount >= 1 && amount <= 20)) throw new Error('amount must be 1-20')
+      const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : last
+      if (!t) throw new Error('no target window: pass app= or capture first')
+      return await actAndShot(exec, () => granting(exec), 'Scrolled ' + direction + ' x' + amount + ' in window.', async () =>
+        await action('scroll', { target: windowTarget(t), direction, amount, ...(a.by === 'page' ? { by: 'page' } : {}) }))
+    },
+  })
+
+  register({
+    name: 'computer_type',
+    description: 'Type text into a target window IN THE BACKGROUND (UIA SetValue for fields listed in the last capture — pass element= for reliability; XAML/Store apps require element=; classic Win32 accepts plain WM_CHAR). Pass desktop=true to type into whatever the user currently has focused instead — non-ASCII text (CJK, emoji) is then delivered via clipboard + ctrl+v, because direct typing goes through the active IME and comes out corrupted; the user\'s clipboard is restored afterwards. Newlines are not typed in the window path; send computer_key enter between lines (a desktop paste carries them as-is).',
+    parameters: {
+      app: { type: 'string' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      element: { type: 'string', description: 'element token of the field (last window capture).' },
+      text: { type: 'string', required: true, description: 'Text to type. Max 5000 chars.' },
+      desktop: { type: 'boolean', description: 'true = type into the current foreground app (no window target).' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 30000,
+    async execute(a, exec) {
+      if (typeof a.text !== 'string' || a.text.length === 0) throw new Error('text must be a non-empty string')
+      if (a.text.length > 5000) throw new Error('text too long (max 5000 chars)')
+      if (a.desktop === true) {
+        // Non-ASCII must not go through the IME-ridden SendInput path (see
+        // pasteDesktop); window-scope typing is Unicode-native (UIA/WM_CHAR).
+        if (NON_ASCII.test(a.text)) return await pasteDesktop(exec, a.text)
+        return await actAndShot(exec, () => granting(exec), 'Typed ' + a.text.length + ' chars into the foreground app.', async () => {
+          const r = await action('type_text', { target: { kind: 'desktop', display_id: 'primary' }, text: a.text })
+          r.scopeView = 'desktop'
+          return r
+        })
+      }
+      const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : last
+      if (!t) throw new Error('no target window: pass app= or capture first')
+      const args = typeof a.element === 'string' && a.element !== ''
+        ? { pid: t.pid, window_id: t.windowId, element_token: a.element, text: a.text }
+        : { target: windowTarget(t), text: a.text }
+      return await actAndShot(exec, () => granting(exec), 'Typed ' + a.text.length + ' chars into window.', () => action('type_text', args))
+    },
+  })
+
+  register({
+    name: 'computer_key',
+    description: 'Press a key or chord in a target window (background; driver picks UIA-accelerator/PostMessage/SendInput automatically), repeat 1-10. For chords on XAML/WinUI/UWP apps that hide shortcuts behind menus (e.g. Notepad ctrl+a), it auto-falls back to a real foreground SendInput chord that briefly swaps focus then restores. Names: a-z, 0-9, f1-f12, enter, esc, tab, space, backspace, delete, insert, home, end, pageup, pagedown, up, down, left, right, ctrl, alt, shift, win. desktop=true sends to the foreground app instead.',
+    parameters: {
+      app: { type: 'string' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      keys: { type: 'string', required: true, description: 'Plus-joined key names, e.g. "ctrl+shift+s".' },
+      repeat: { type: 'number', description: 'Press the chord N times, 1-10. Default 1.' },
+      desktop: { type: 'boolean', description: 'true = send to the current foreground app.' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 30000,
+    async execute(a, exec) {
+      const { mods, key } = parseKeys(a.keys)
+      const repeat = a.repeat === undefined ? 1 : Math.round(Number(a.repeat))
+      if (!(repeat >= 1 && repeat <= 10)) throw new Error('repeat must be 1-10')
+      let targetArg
+      if (a.desktop === true) {
+        targetArg = { target: { kind: 'desktop', display_id: 'primary' } }
+      } else {
+        const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : last
+        if (!t) throw new Error('no target window: pass app= or capture first')
+        targetArg = { target: windowTarget(t) }
+      }
+      const view = a.desktop === true ? 'desktop' : 'window'
+      return await actAndShot(exec, () => granting(exec), 'Pressed ' + a.keys + (repeat > 1 ? ' x' + repeat : '') + '.', async () => {
+        let r
+        for (let i = 0; i < repeat; i++) {
+          r = await pressChord(targetArg, mods, key)
+        }
+        r.scopeView = view
+        return r
+      })
+    },
+  })
+
+  register({
+    name: 'computer_open',
+    description: 'Open an app by name WITHOUT ever starting a second instance of something that is already running: an existing window is reused (a minimized one is restored), and an app that is ALREADY RUNNING but exposes no window (tray state) is reported instead of relaunched —  ask the user to open it, or pass activate_running=true to let its own launcher try. Only a truly absent app is launched. Returns that window captured, with the element tree. PREFERRED over Start-menu clicking. Launching is always background; restoring a minimized window is the one path that takes the foreground.',
+    parameters: {
+      name: { type: 'string', required: true, description: 'App name as the OS knows it, e.g. "notepad", "微信", "Chrome". Max 100 chars.' },
+      settle_seconds: { type: 'number', description: 'Extra wait for a newly launched window to materialize, 0-15. Default 2.' },
+      activate_running: { type: 'boolean', description: 'true = when the app is already running but has no window (tray-only), let its own launcher try to activate it. Default false: report it and let the user open it from the tray, because re-entering a chat app\'s startup path can drop its stored session.' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 45000,
+    async execute(a, exec) {
+      const appName = typeof a.name === 'string' ? a.name.trim() : ''
+      if (appName === '' || appName.length > 100) throw new Error('name must be 1-100 chars')
+      const settle = a.settle_seconds === undefined ? 2000 : Math.min(15000, Math.max(0, Number(a.settle_seconds) * 1000))
+      const mayActivate = a.activate_running === true || activateRunningCfg
+      granting(exec)
+
+      // Order matters, and this is the order: PROCESS FIRST, window second.
+      //
+      // "Is a process for this app alive?" is the cheapest and most reliable
+      // signal (the driver derives list_apps.running from the process table and
+      // the foreground pid). The window layer is the fragile one — measured:
+      // list_windows can report zero windows for the whole lifetime of a
+      // long-lived host, and it is also session/DPI sensitive. Deciding "it is
+      // not running, so launch it" from a WINDOW lookup therefore relaunches an
+      // app that is plainly alive, which is precisely the reported bug. So:
+      // ask the process table first, and only launch when it says no.
+
+      // 1) Already running? Then never launch. Reuse its window when there is
+      //    one (restoring it if minimized); otherwise it is a tray-state app.
+      const entry = await findInstalledApp(appName)
+      if (entry !== null && entry.running === true) {
+        let target = await windowFor(appName, entry.pid)
+        for (let waited = 0; target === null && waited < 2000; waited += 400) {
+          await sleep(400, exec.signal)
+          target = await windowFor(appName, entry.pid)
+        }
+        if (target !== null) {
+          last = target
+          const shot = await shotFor(target, { restoreMinimized: true, signal: exec.signal, summary: 'Reused the window of the already-running "' + appName + '" (pid ' + target.pid + ') — no new instance was started.' })
+          return { ...shot, summary: shot.summary + ' Nothing was relaunched.' }
+        }
+        // Alive, no window: for chat apps (WeChat / WeCom / QQ / DingTalk) that
+        // IS the tray state, and walking them through their launcher can drop a
+        // stored session and demand a fresh QR scan. Report; let the user click
+        // the tray icon, which restores the real window without starting
+        // anything. activate_running=true opts into letting its launcher try.
+        if (mayActivate) {
+          const activate = entry.kind === 'uwp'
+            ? await launchSelectorFor(appName)
+            : (typeof entry.launch_path === 'string' && entry.launch_path !== '' ? { launch_path: entry.launch_path } : (typeof entry.bundle_id === 'string' && entry.bundle_id !== '' ? { path: entry.bundle_id } : null))
+          if (activate !== null) {
+            await call('launch_app', { ...activate, start_minimized: true }).catch(() => null)
+            for (let waited = 0; waited < 6000; waited += 600) {
+              await sleep(600, exec.signal)
+              const t = await windowFor(appName, entry.pid)
+              if (t !== null) {
+                last = t
+                return await shotFor(last, { restoreMinimized: true, signal: exec.signal, summary: 'Activated the already-running "' + appName + '" through its own launcher (pid ' + t.pid + ') — no second instance.' })
+              }
+            }
+          }
+        }
+        return await captureDesktop('"' + appName + '" is ALREADY RUNNING (pid ' + entry.pid + ') but exposes no window — this is usually its tray state, so nothing was started. Ask the user to open it from the tray (clicking the tray icon restores the real window and keeps the session), then retry. If the app truly has no window and no tray icon, retry with activate_running=true to let its launcher try.')
+      }
+
+      // 2) Not running: launch it (aumid for Store apps, shortcut commandline
+      //    for desktop apps — see launchSelectorFor).
+      const launched = await launchAndSettle(await launchSelectorFor(appName), settle, exec.signal)
+      if (launched.target !== null) {
+        last = launched.target
+        return await shotFor(last, { restoreMinimized: true, windowHint: last, signal: exec.signal, summary: 'Launched "' + appName + '" (pid ' + last.pid + ', background — foreground untouched).' })
+      }
+
+      // 3) Launch produced no window. It may still be starting (slow packaged
+      //    apps take ~10 s) — give it one more patient look before giving up.
+      let late = await windowFor(appName)
+      for (let waited = 0; late === null && waited < 6000; waited += 600) {
+        await sleep(600, exec.signal)
+        late = await windowFor(appName)
+      }
+      if (late !== null) {
+        last = late
+        return await shotFor(last, { restoreMinimized: true, windowHint: last, signal: exec.signal, summary: 'Launched "' + appName + '" (slow start; pid ' + late.pid + ').' })
+      }
+      const why = launched.died === true
+        ? 'its process exited immediately — the app did NOT start (check the app name, or launch it by path)'
+        : 'no window appeared'
+      return await captureDesktop('Tried to open "' + appName + '" but ' + why + '. Nothing to show; check computer_windows, or ask the user to open it.')
+    },
+  })
+
+  const compileStep = (rawStep) => {
+    const s = String(rawStep)
+    const c1 = s.indexOf(':')
+    const head = (c1 === -1 ? s : s.slice(0, c1)).toLowerCase().trim()
+    const rest = c1 === -1 ? '' : s.slice(c1 + 1)
+    if (head === 'key') {
+      const { mods, key } = parseKeys(rest)
+      return { kind: 'key', mods, key }
+    }
+    if (head === 'type') {
+      if (rest === '' || rest.length > 5000) throw new Error('type text must be 1-5000 chars')
+      return { kind: 'type', text: rest }
+    }
+    if (head === 'wait') {
+      const sec = parseFloat(rest)
+      if (!isFinite(sec) || sec < 0 || sec > 15) throw new Error('wait seconds must be 0-15')
+      return { kind: 'wait', ms: Math.round(sec * 1000) }
+    }
+    if (head === 'click') {
+      let button = 'left'
+      let clicks = 1
+      let xy = rest
+      if (rest.indexOf(':') !== -1) {
+        const li = rest.lastIndexOf(':')
+        xy = rest.slice(li + 1)
+        rest.slice(0, li).split(':').forEach((m) => {
+          if (m === 'left' || m === 'right' || m === 'middle') button = m
+          else if (/^[1-3]$/.test(m)) clicks = parseInt(m, 10)
+          else if (m !== '') throw new Error('click modifiers must be left|right|middle or 1-3, got "' + m + '"')
+        })
+      }
+      const seg = xy.split(',').map((t) => t.trim())
+      if (seg.length !== 2 || !isFinite(Number(seg[0])) || !isFinite(Number(seg[1]))) throw new Error('click needs "x,y" in the target window\'s last screenshot px')
+      return { kind: 'click', x: Number(seg[0]), y: Number(seg[1]), button, clicks }
+    }
+    if (head === 'scroll') {
+      const seg = rest.split(',').map((t) => t.trim())
+      if (!['up', 'down', 'left', 'right'].includes(seg[0])) throw new Error('scroll direction must be up|down|left|right')
+      const amt = seg[1] !== undefined && seg[1] !== '' ? Number(seg[1]) : 3
+      if (!(amt >= 1 && amt <= 20)) throw new Error('scroll amount must be 1-20')
+      return { kind: 'scroll', direction: seg[0], amount: amt }
+    }
+    if (head === 'open') {
+      const appName = rest.trim()
+      if (appName === '' || appName.length > 100) throw new Error('open name must be 1-100 chars')
+      return { kind: 'open', name: appName }
+    }
+    throw new Error('unknown action "' + head + '" (use key/type/wait/click/scroll/open — for held-modifier clicks use click:ctrl not keydown)')
+  }
+
+  register({
+    name: 'computer_sequence',
+    description: 'Run a multi-step flow atomically in ONE call with ONE approval and ONE final screenshot (intermediate states not shown). Steps target the last window (or app= for this sequence); step DSL, one string per step: key:ctrl+s · type:任意文本 · wait:1.5 · click:x,y or click:right:2:x,y · scroll:down,5 · open:微信 (launch + retarget). All steps validate before the first input. Coordinates = px of the last screenshot of the acting window.' + KEYB_FIRST,
+    parameters: {
+      steps: { type: 'array', required: true, description: 'Ordered step strings, max 30 steps.', items: { type: 'string' } },
+      app: { type: 'string', description: 'Optional app to retarget this sequence to first.' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 90000,
+    async execute(a, exec) {
+      if (!Array.isArray(a.steps) || a.steps.length === 0) throw new Error('steps must be a non-empty array of step strings')
+      if (a.steps.length > 30) throw new Error('max 30 steps per sequence')
+      const compiled = []
+      for (let i = 0; i < a.steps.length; i++) {
+        try { compiled.push(compileStep(a.steps[i])) } catch (e) {
+          throw new Error('step ' + (i + 1) + ' "' + String(a.steps[i]).slice(0, 60) + '": ' + e.message)
+        }
+      }
+      granting(exec)
+      if (a.app !== undefined) await resolveWindow({ app: a.app })
+      const notes = []
+      let view = last ? 'window' : 'desktop'
+      for (const step of compiled) {
+        if (step.kind === 'wait') { await sleep(step.ms, exec.signal); continue }
+        if (step.kind === 'open') {
+          // Same order as computer_open: ask the process table FIRST, and only
+          // launch when it says the app is not running.
+          const entry = await findInstalledApp(step.name)
+          if (entry !== null && entry.running === true) {
+            const t = await windowFor(step.name, entry.pid)
+            if (t !== null) {
+              last = t
+              view = 'window'
+              // Only un-minimize; the single final capture at the end covers it.
+              const w = await listWindows({ pid: t.pid })
+              const me = (w.windows ?? []).find((x) => (x.window_id ?? x.windowId) === t.windowId)
+              if (me !== undefined && me.minimized === true && restoreCfg) await restoreWindow(t.pid, t.windowId)
+              continue
+            }
+            // Running with no window (tray state): do not relaunch it.
+            notes.push('"' + step.name + '" was already running with no window (tray state) — not relaunched')
+            continue
+          }
+          const r = await call('launch_app', await launchSelectorFor(step.name))
+          const sc = structured(r)
+          await sleep(1200, exec.signal)
+          const t = await windowFor(step.name, sc.pid)
+          if (t !== null) { last = t; view = 'window' }
+          continue
+        }
+        if (!last) throw new Error('sequence step needs a window target (pass app= or open: first): ' + step.kind)
+        const t = last
+        if (step.kind === 'key') {
+          await pressChord({ target: windowTarget(t) }, step.mods, step.key)
+        } else if (step.kind === 'type') {
+          await action('type_text', { target: windowTarget(t), text: step.text })
+        } else if (step.kind === 'click') {
+          await action('click', { target: windowTarget(t), x: step.x, y: step.y, button: step.button, count: step.clicks })
+        } else if (step.kind === 'scroll') {
+          await action('scroll', { target: windowTarget(t), direction: step.direction, amount: step.amount })
+        }
+      }
+      await sleep(settleMs, exec.signal)
+      const summary = 'Ran ' + a.steps.length + ' steps: ' + a.steps.join(' → ').slice(0, 300) + (notes.length > 0 ? ' [' + notes.join('; ') + ']' : '')
+      return view === 'window' ? await shotFor(last, { tree: false, summary }) : await captureDesktop(summary)
+    },
+  })
+
+  register({
+    name: 'computer_zoom',
+    description: 'Zoom into a region of a WINDOW at native resolution (reads small text/icons the model frame blurs). x0,y0,x1,y1 are px of the last screenshot OF THAT WINDOW; region ≤ ~500px wide (the driver pads 20% per side). The zoom image is NOT the coordinate frame — pass from_zoom=true to computer_click to click inside it.',
+    parameters: {
+      app: { type: 'string' },
+      pid: { type: 'number' },
+      window_id: { type: 'number' },
+      x0: { type: 'number', required: true },
+      y0: { type: 'number', required: true },
+      x1: { type: 'number', required: true, description: 'Must be > x0.' },
+      y1: { type: 'number', required: true, description: 'Must be > y0.' },
+    },
+    output: SHOT_RENDER,
+    isConcurrencySafe: () => true,
+    timeoutMs: 25000,
+    async execute(a) {
+      const t = (a.app !== undefined || a.pid !== undefined) ? await resolveWindow(a) : last
+      if (!t) throw new Error('zoom needs a window: pass app= (or capture a window first). For desktop regions just look at the desktop screenshot again.')
+      const r = await call('zoom', { pid: t.pid, window_id: t.windowId, x1: Number(a.x0), y1: Number(a.y0), x2: Number(a.x1), y2: Number(a.y1) })
+      const img = r.images[0]
+      if (!img) throw new Error('zoom returned no image')
+      const png = Buffer.from(img.dataBase64, 'base64')
+      const ref = await ctx.attachments.saveImage({ data: png, mediaType: img.mimeType === 'image/png' ? 'image/png' : (img.mimeType || 'image/jpeg'), name: 'zoom.jpg' })
+      return {
+        summary: 'Zoomed window region (' + a.x0 + ',' + a.y0 + ')-(' + a.x1 + ',' + a.y1 + ') at native resolution.',
+        frameText: 'This zoom is NOT the coordinate frame; computer_click with from_zoom=true maps clicks from THIS image back to the window.',
+        image: { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height },
+      }
+    },
+  })
+
+  register({
+    name: 'computer_cursor',
+    description: 'Read the real OS cursor position (primary-desktop pixel space, same as the desktop screenshot). Window actions do not use the real cursor — they post to the target window directly.',
+    parameters: {},
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { physical: { type: 'string', required: true } } },
+      render: (_a, v) => [{ type: 'text', text: 'cursor at ' + v.physical + ' (primary-desktop px; background window actions ignore the pointer)' }],
+    },
+    isConcurrencySafe: () => true,
+    timeoutMs: 15000,
+    async execute() {
+      const sc = structured(await call('get_cursor_position', {}))
+      return { physical: sc.x + ',' + sc.y }
+    },
+  })
+
+  register({
+    name: 'computer_move',
+    description: 'Move the REAL OS pointer on the primary desktop to (x, y) of the last desktop screenshot and leave it there (hover state for the user/foreground apps). Background window actions never move the pointer, so use this only when a FOREGROUND app needs hover. Does not click.',
+    parameters: {
+      x: { type: 'number', required: true },
+      y: { type: 'number', required: true },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 25000,
+    async execute(a, exec) {
+      const p = deskXY(Number(a.x), Number(a.y), 'move target')
+      return await actAndShot(exec, () => granting(exec), 'Real pointer moved to desktop px (' + a.x + ',' + a.y + ').' + (p.scaled ? ' [x,y were physical desktop px — mapped into the screenshot frame]' : ''), async () => {
+        const r = await call('move_cursor', { target: { kind: 'desktop', display_id: 'primary' }, x: p.x, y: p.y })
+        r.scopeView = 'desktop'
+        return r
+      })
+    },
+  })
+
+  register({
+    name: 'computer_wait',
+    description: 'Wait for a few seconds (animations, loading) and return a fresh screenshot of the current target (window if captured, else desktop).',
+    parameters: {
+      seconds: { type: 'number', required: true, description: 'Seconds to wait, 0.1-15.' },
+    },
+    output: SHOT_RENDER,
+    timeoutMs: 25000,
+    async execute(a, exec) {
+      const s = Number(a.seconds)
+      if (!isFinite(s) || s < 0.1 || s > 15) throw new Error('seconds must be 0.1-15')
+      await sleep(Math.round(s * 1000), exec.signal)
+      return last ? await shotFor(last, { tree: false, summary: 'Waited ' + s + 's.' }) : await captureDesktop('Waited ' + s + 's.')
+    },
+  })
+
+  const MUTATING = new Set(['computer_move', 'computer_click', 'computer_drag', 'computer_scroll', 'computer_type', 'computer_key', 'computer_open', 'computer_sequence'])
+  ctx.on('tools/pre-execute', (exec, next) => {
+    if (!MUTATING.has(exec.name)) return next()
+    if (askPolicy === 'never') return next()
+    if (askPolicy === 'once-per-agent' && agentsGranted.has(agentKey(exec.agent))) return next()
+    // Full-access / approvals-disabled session: asking would be auto-rejected by
+    // the approval service — honor the session's mode instead of self-blocking.
+    if (sessionRefusesPrompt(exec)) return next()
+    return { kind: 'ask', reason: '允许 computer-use 操作应用？一次批准覆盖同一会话的后续动作（askPolicy: always 可改为每次一询）；默认后台注入——不移动你的鼠标、不抢焦点，仅个别拒收后台输入的应用会短暂前置。首个动作: ' + exec.name + '。' }
+  })
+
+  ctx.logger.info('computer-use v2.4: cua-driver backend (session "' + SESSION_LABEL + '", all calls labelled); ' + MUTATING.size + ' mutating tools gated; askPolicy=' + askPolicy + '; telemetry=' + telemetry + '; restoreExisting=' + restoreCfg)
+
+  // Best-effort: push the model-frame cap into the driver for window captures
+  // (the driver resizes window screenshots AND keeps x,y/zoom coordinates
+  // consistent with the resized image; desktop captures are resized plugin-side).
+  getDriver().then(() => raw('set_config', { key: 'max_image_dimension', value: maxDim })).then(
+    () => ctx.logger.info('computer-use: max_image_dimension=' + maxDim),
+    () => {},
+  )
+}