dsh-codex-style-computer-use 2.0.0 → 2.2.3

package/lib/host-debug.js

@@ -0,0 +1,88 @@
+// host-debug.js — the two gates that decide whether the agent may drive its OWN Harness window.
+//
+// WHY THIS EXISTS
+// The host guard refuses every driving op aimed at the DSH window. That is right for ordinary
+// work (the agent must never approve its own approvals, type as the human, or press Stop), but it
+// also makes self-iteration — debugging another plugin inside the same instance — impossible.
+// The answer is not to weaken the default; it is an explicit DEBUG MODE with two gates:
+//
+//   1. the CALLING CONVERSATION has full permission: its sandbox mode is danger-full-access;
+//   2. debug mode was switched on BY HAND in Settings → 电脑操控（调试）.
+//
+// Neither gate can be turned on from inside a tool call: gate 1 is the session's own policy (the
+// human sets it in the composer) and gate 2 is a host-side file that only the settings page
+// writes. Tools can read both; they cannot write either.
+//
+// SETTINGS PAGE CONTRACT (host side):
+//   GET  /api/computer-use/host-debug  -> { enabled, since, session:{id,sandbox,fullAccess}, lastBlockedAt }
+//   POST /api/computer-use/host-debug  -> { enabled: boolean }  (writes the file, returns the same shape)
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+const dshHome = () => process.env.DSH_HOME || path.join(process.env.USERPROFILE || process.env.HOME || '.', '.dsh')
+
+/** Where the debug switch lives. Deliberately NOT inside any profile: one machine, one switch. */
+export const HOST_DEBUG_FILE = () => path.join(dshHome(), 'data', 'computer-use', 'host-debug.json')
+
+function readJson (file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null }
+}
+
+/** Hot read; the worker also polls this file (500 ms cache) so a toggle needs no restart. */
+export function readHostDebug () {
+  const j = readJson(HOST_DEBUG_FILE())
+  if (!j || typeof j !== 'object') return { enabled: false, since: null, lastBlockedAt: null }
+  return {
+    enabled: j.enabled === true,
+    since: typeof j.since === 'string' ? j.since : null,
+    lastBlockedAt: typeof j.lastBlockedAt === 'string' ? j.lastBlockedAt : null,
+  }
+}
+
+export function writeHostDebug (enabled) {
+  const file = HOST_DEBUG_FILE()
+  mkdirSync(path.dirname(file), { recursive: true })
+  const previous = readHostDebug()
+  const next = {
+    enabled: enabled === true,
+    since: enabled === true ? (previous.enabled ? previous.since : new Date().toISOString()) : null,
+    lastBlockedAt: previous.lastBlockedAt,
+  }
+  writeFileSync(file, JSON.stringify(next, null, 2) + '\n', 'utf8')
+  return next
+}
+
+/** Record that a host-driving call was refused by a gate, so the settings page can say so. */
+export function noteHostBlocked () {
+  try {
+    const file = HOST_DEBUG_FILE()
+    const current = readHostDebug()
+    if (!existsSync(file)) return
+    writeFileSync(file, JSON.stringify({ ...current, lastBlockedAt: new Date().toISOString() }, null, 2) + '\n', 'utf8')
+  } catch { /* a failed note must never break the refusal itself */ }
+}
+
+const SESSION_ROOTS = () => [
+  path.join(dshHome(), 'storages', 'session_projcache', 'sessions'),
+  path.join(dshHome(), 'storages', 'sessions'),
+  path.join(dshHome(), 'sessions'),
+]
+
+/** The session record is a live cache under DSH_HOME; find the one for this id (cheap, per call). */
+function sessionRecord (sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') return null
+  for (const root of SESSION_ROOTS()) {
+    const file = path.join(root, `${sessionId}.json`)
+    if (existsSync(file)) return readJson(file)
+  }
+  return null
+}
+
+/** Gate 1: does the CALLING conversation hold full permission? Unknown => false (fail closed). */
+export function sessionPermission (sessionId) {
+  const rec = sessionRecord(sessionId)
+  const rows = rec?.record?.rows
+  const sandbox = rows?.permissions?.val?.sandbox || rows?.sandboxMode?.val || null
+  const approval = rows?.permissions?.val?.approval || rows?.approvalState?.val?.policy || null
+  return { id: sessionId || null, sandbox, approval, fullAccess: sandbox === 'danger-full-access' }
+}

package/lib/image-output.js

@@ -43,10 +43,16 @@ export async function attachScreenshot (ctx, exec, value, data, options = {}) {
     value.imageReason = reason
     value.view = reason === 'model-text-only'
       ? 'Image not attached: this model does not declare image input. Use UIA/text or switch to an image-capable model.'
-      : 'Image not attached. Use read_image on path if visual inspection is needed.'
+      : reason === 'delivery-path'
+        ? 'Path delivery requested: no image block was attached. The file is on path; call read_image only if visual inspection is actually needed.'
+        : 'Image not attached. Use read_image on path if visual inspection is needed.'
     if (value.settled === false) value.view = 'NOT settled — re-shoot. ' + value.view
     return value
   }
+  // delivery:"path" — the caller has another way to verify (UIA/OCR/window text), so the pixels
+  // are not evidence it will read. The file is still written and the path still returned; only
+  // the image block is withheld, which is what keeps it out of the re-sent conversation history.
+  if (options.delivery === 'path') return fallback('delivery-path')
   try {
     if (!validImageSize(value.imageSize)) return fallback('invalid-source-image-size')
     const sourceSize = [...value.imageSize]
@@ -107,7 +113,12 @@ export function renderScreenshot (value) {
 
 // A batch exposes one latest image as its checkpoint. Earlier explicit captures
 // keep their paths for deliberate later reads, without multiplying vision input.
-export function selectBatchScreenshot (result, automatic, kind = 'image') {
+//
+// `delivery` is the batch-level request, and it has to reach further than the checkpoint: when
+// no checkpoint happens (shot:"never", a readback tail, or a later failure) the observation
+// falls back to the last explicit step image. A batch that asked for paths must not hand one
+// back as a picture just because the checkpoint was skipped — same pixels, quieter route.
+export function selectBatchScreenshot (result, automatic, kind = 'image', delivery = 'auto') {
   let latest = automatic
   let index
   if (!latest) {
@@ -118,19 +129,30 @@ export function selectBatchScreenshot (result, automatic, kind = 'image') {
       }
     }
   }
+  const pathDelivery = delivery === 'path'
+  const pathNote = 'Path delivery requested: no image block was attached. Use read_image on this path only if these pixels are the evidence.'
   for (const action of result.actions) {
     const shot = action.result
     if (shot?.image && shot !== latest) {
       delete shot.image
       restoreFileGeometry(shot)
       shot.imageStatus = 'path-only'
-      shot.imageReason = 'earlier-batch-image'
-      shot.view = kind === 'state'
-        ? 'A newer UIA state is returned. This earlier image remains at its path.'
-        : 'Only the latest batch screenshot is attached. Use read_image on this path if this earlier frame is needed.'
+      shot.imageReason = pathDelivery ? 'delivery-path' : 'earlier-batch-image'
+      shot.view = pathDelivery
+        ? pathNote
+        : kind === 'state'
+          ? 'A newer UIA state is returned. This earlier image remains at its path.'
+          : 'Only the latest batch screenshot is attached. Use read_image on this path if this earlier frame is needed.'
     }
   }
   if (latest) {
+    if (pathDelivery && latest.image) {
+      delete latest.image
+      restoreFileGeometry(latest)
+      latest.imageStatus = 'path-only'
+      latest.imageReason = 'delivery-path'
+      latest.view = pathNote
+    }
     result.observation = latest
     if (kind === 'state') result.observationSource = 'automatic final UIA state'
     else result.imageSource = automatic ? 'automatic final screenshot' : `action ${index + 1}; captured before any later actions`

package/lib/index.js

@@ -1,4 +1,5 @@
 import { installApprovalAttribution } from './approval-attribution.js'
+import { HOST_DEBUG_FILE, noteHostBlocked, readHostDebug, sessionPermission, writeHostDebug } from './host-debug.js'
 import { installHumanAttention } from './attention.js'
 // dsh-computer-use — DSH Cordis plugin
 //
@@ -410,6 +411,87 @@ export const Config = Schema.object({
   ]).default('stop').description('legacy setting; ignored — ordinary completion releases computer use automatically'),
 })
 
+// ---- host-driving debug gates: the settings page talks to this same-origin route ----
+// GET  returns the two gates' state for a session; POST writes ONLY the debug switch. Neither gate
+// can be flipped from a tool call: the route is host-side and the switch is a file a tool cannot
+// write (the agent has no filesystem tool that could reach it without the user seeing it in
+// tool output; see lib/host-debug.js for the contract).
+function installHostDebugRoute (ctx, log) {
+  if (typeof ctx?.inject !== 'function') return
+  ctx.inject(['webServer'], (sctx) => {
+    try {
+      sctx.effect(() => sctx.webServer.register({
+        kind: 'prefix',
+        path: '/api/computer-use/host-debug',
+        handler: (req, res) => handleHostDebug(req, res, sctx),
+      }), 'dsh-computer-use: host-debug settings route')
+    } catch (e) { log.info('[dsh-computer-use] host-debug route not mounted: ' + (e?.message ?? e)) }
+  })
+}
+
+function handleHostDebug (req, res, sctx) {
+  const send = (code, body) => { try { res.statusCode = code; res.setHeader('content-type', 'application/json; charset=utf-8'); res.end(JSON.stringify(body)) } catch { } }
+  try {
+    let connection = null
+    try { connection = sctx.get('connection') } catch { connection = null }
+    const rejection = connection && typeof connection.requestRejection === 'function' ? connection.requestRejection(req) : null
+    if (rejection) { send(403, { error: 'rejected by host', detail: String(rejection) }); return }
+    const url = new URL(req.url, 'http://127.0.0.1')
+    const sid = url.searchParams.get('session') || process.env.DSH_SESSION_ID || null
+    const status = () => {
+      const debug = readHostDebug()
+      const perm = sessionPermission(sid)
+      return { enabled: debug.enabled, since: debug.since, lastBlockedAt: debug.lastBlockedAt, session: perm, ready: debug.enabled && perm.fullAccess }
+    }
+    if (req.method === 'GET') { send(200, status()); return }
+    if (req.method === 'POST') {
+      const chunks = []
+      req.on('data', (c) => { if (chunks.length < 64) chunks.push(c) })
+      req.on('end', () => {
+        try {
+          const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+          if (typeof body.enabled !== 'boolean') { send(400, { error: 'enabled must be a boolean' }); return }
+          writeHostDebug(body.enabled)
+          send(200, status())
+        } catch (e) { send(400, { error: String(e?.message ?? e) }) }
+      })
+      return
+    }
+    send(405, { error: 'GET or POST' })
+  } catch (e) { send(500, { error: String(e?.message ?? e) }) }
+}
+
+// ---- gate notice: one card, not a stream of them --------------------------------------------
+// A refused host-driving call is the moment the human can act, and the tool error alone is easy to
+// miss inside a long turn. This pops ONE ask card (10-minute dedupe, never blocks the failed tool
+// call) that names both gates and where to open them. It is a NOTICE: choosing "去开启" only tells
+// the human where the switch is — the plugin must never flip either gate itself.
+let gateNoticeAt = 0
+let gateNoticePending = false
+function notifyHostGate (log) {
+  try {
+    if (gateNoticePending) return
+    if (Date.now() - gateNoticeAt < 10 * 60_000) return
+    if (!asker || typeof asker.ask !== 'function') return
+    gateNoticePending = true
+    gateNoticeAt = Date.now()
+    Promise.resolve()
+      .then(() => asker.ask({
+        questions: [{
+          id: 'computer_use_host_gate',
+          header: '电脑操控 · 调试门禁',
+          question: '检测到自迭代调试被门禁拦住：需要 ① 本对话为「完全权限」，② 在 设置 → 电脑操控（调试） 中手动打开调试模式。两项都满足后，AI 才能点击/输入 Harness 自身的窗口。',
+          options: [
+            { label: '我去开启调试模式', description: '打开 设置 → 电脑操控（调试） 并切换开关；本对话还需保持「完全权限」。' },
+            { label: '先不开启，做别的', description: 'AI 继续只读观察 Harness，不驱动它；关闭/最小化宿主始终禁止。' },
+          ],
+        }],
+      }))
+      .catch(() => { })
+      .finally(() => { gateNoticePending = false })
+  } catch { gateNoticePending = false }
+}
+
 export function apply (ctx, config) {
   const log = ctx.logger('dsh-computer-use')
   if (process.env.DSH_COMPUTER_USE_KILL === '1') {
@@ -418,6 +500,11 @@ export function apply (ctx, config) {
   }
   if (!config.enabled) return
   installApprovalAttribution(ctx, log)
+  // Harness compatibility: several fixtures evaluate this module with the `import` lines stripped
+  // and only a fixed argument list (test-cycle-no-timeout and friends). `typeof <binding>` is safe
+  // even when the binding was stripped, so the debug-gate wiring degrades to "not mounted" there
+  // instead of throwing a ReferenceError — the production module always has the real imports.
+  try { if (typeof installHostDebugRoute === 'function') installHostDebugRoute(ctx, log) } catch { }
   registerBundledSkill(ctx, log)
   enableHumanAttention(ctx, log)
   // THE QUESTION SERVICE, INJECTED LAZILY (merge-design.md §5.3 item 16 — defence in depth).
@@ -436,12 +523,29 @@ export function apply (ctx, config) {
   })
 
   const dataDir = mkDataDir(config.snapshotDir)
+  // The two host-driving gates are resolved PER CALL: the debug switch is hot (a settings toggle
+  // needs no restart), and gate 1 is the CALLING conversation's own policy, not the host's.
+  const gateSessionId = (context) => {
+    try {
+      return context?.sessionKey || (typeof context?.session === 'string' ? context.session : context?.session?.id) ||
+        context?.sessionId || process.env.DSH_SESSION_ID || null
+    } catch { return process.env.DSH_SESSION_ID || null }
+  }
   const cu = new ComputerUse({
     workerExe: config.workerExe || undefined,
     dryRun: config.dryRun,
     kickoffRequired: config.automationMode !== 'read-only',
     rateLimit: { max: config.maxActionsPerMinute, windowMs: 60_000 },
     log: (m) => log.info(m),
+    hostDebugFile: typeof HOST_DEBUG_FILE === 'function' ? HOST_DEBUG_FILE() : '',
+    hostGate: typeof readHostDebug === 'function' && typeof sessionPermission === 'function'
+      ? (context) => {
+          try { return { debug: readHostDebug().enabled, full: sessionPermission(gateSessionId(context)).fullAccess } } catch { return null }
+        }
+      : null,
+    onHostBlocked: typeof noteHostBlocked === 'function'
+      ? () => { try { noteHostBlocked() } catch { } notifyHostGate(log) }
+      : null,
   })
   const detachAudit = installAudit(cu, dataDir)
 

package/lib/launch.js

@@ -0,0 +1,67 @@
+// launch.js — validation for computer_launch. EXECUTION lives in the worker (lib/core/worker.cs
+// `launch` op) on purpose: a launch must go through the SAME funnel as every other actuation —
+// brake/pause checks, the status halo, the audit JSONL and the rate window — and the human has
+// to SEE that the machine was just acted on. A Node-side spawn skipped all of that (measured
+// 2026-11-07: the halo never lit, so nothing told the human an app was opening).
+//
+// Validation still lives here so an impossible target is refused BEFORE dispatch: the receipt
+// says outcome:"not-dispatched", and that has to be true. The policy layer also needs the string.
+//
+// RESOLUTION IS ShellExecute's (worker: ProcessStartInfo.UseShellExecute). Measured on this
+// machine: `explorer.exe calc` opens a FILE EXPLORER window (a bare word is a location to
+// explorer), while ShellExecute("calc") starts Calculator — so the launcher, not a shell
+// wrapper, is the correct resolver for App Paths aliases, shell: verbs, URLs and associations.
+//
+// The target crosses as ONE value: no command line is composed here or in the worker, and no
+// shell interpreter is involved. The deny-list below is defence in depth for anything
+// downstream that might interpolate the string — the boundary is the single-value call.
+const MAX_LEN = 2000
+
+// Control characters: C0 (includes \r \n \t), DEL, C1, and the Unicode line/paragraph
+// separators (U+2028/U+2029 still break line discipline in several parsers). None has an
+// honest use in a path, URL or alias.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/
+
+// Metacharacters for a shell or a string interpolator. Percent is deliberately NOT here:
+// "%20"-style percent-encoding is a legitimate, unavoidable part of URLs, and no shell is
+// involved, so there is no %VAR% expansion to fear.
+const INJECTIVE = /["'&|;<>$`^]/
+
+const badTarget = (why) => {
+  throw Object.assign(new Error(`bad launch target: ${why}`), { code: 'LAUNCH_BAD_TARGET', outcome: 'not-dispatched' })
+}
+
+/** Trim and validate a launch target; throws LAUNCH_BAD_TARGET (not-dispatched) when impossible.
+ *  Everything is checked on the TRIMMED string, i.e. on exactly what the worker will receive. */
+export function validateLaunchTarget (target) {
+  if (typeof target !== 'string') badTarget('must be a string')
+  const t = target.trim()
+  if (!t) badTarget('empty (or only whitespace)')
+  if (t.length > MAX_LEN) badTarget(`longer than ${MAX_LEN} characters`)
+  const c = CONTROL.exec(t)
+  if (c) badTarget(`control character U+${c[0].codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`)
+  const m = INJECTIVE.exec(t)
+  if (m) badTarget(`forbidden character ${JSON.stringify(m[0])}`)
+  return t
+}
+
+const badArgs = (why) => {
+  throw Object.assign(new Error(`bad launch arguments: ${why}`), { code: 'LAUNCH_BAD_ARGS', outcome: 'not-dispatched' })
+}
+
+/** Validate the optional argument array. Each entry is ONE argument VALUE — never a command
+ *  line, never shell syntax: the worker quotes each entry exactly once. Spaces, backslashes and
+ *  `--flag=value` are ordinary; only NUL, control characters and empties are impossible. */
+export function validateLaunchArgs (args) {
+  if (args === undefined || args === null) return undefined
+  if (!Array.isArray(args)) badArgs('must be an array of strings')
+  if (args.length > 64) badArgs('more than 64 arguments')
+  return args.map((value, index) => {
+    if (typeof value !== 'string') badArgs(`argument ${index} must be a string`)
+    if (value.length === 0) badArgs(`argument ${index} is empty`)
+    if (value.length > MAX_LEN) badArgs(`argument ${index} longer than ${MAX_LEN} characters`)
+    const c = CONTROL.exec(value)
+    if (c) badArgs(`argument ${index} contains control character U+${c[0].codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`)
+    return value
+  })
+}

package/lib/policy.js

@@ -27,9 +27,18 @@ export const OBSERVATION_TOOLS = new Set([
 export const ACTUATION_TOOLS = new Set([
   'computer_click', 'computer_move', 'computer_drag', 'computer_scroll', 'computer_select',
   'computer_key', 'computer_type', 'computer_uia_act', 'computer_window', 'computer_batch',
+  'computer_launch', 'computer_focus',
 ])
 
 export const HIGH_RISK_NOTE = 'high-risk action (destructive key / closing a window / password field) — always requires human approval'
+export const LAUNCH_HIGH_RISK_NOTE = 'high-risk launch (executable / script / installer / UNC / file: target) — explorer will run what it resolves; always requires human approval'
+
+// A launch target that IS code (or points at it) escalates everywhere it can: the launcher
+// executes what it resolves, so argv discipline cannot make an .exe/.bat/UNC target "just a
+// file". Extensions only by design: bare App-Paths aliases (calc, cmd) stay allowed — the
+// measured trap here was the opposite direction (explorer opened a FOLDER for an alias), and
+// a path spelling of the same binary asks while an alias does not carry arguments either way.
+const LAUNCH_CODE_TARGET = /\.(exe|scr|msi|hta|bat|cmd|com|pif|cpl|msc|reg|jse|vbe|vbs|ws|wsf|wsh|ps1|lnk|url|jar|application|appref-ms|appx|msix|gadget|sct)$/i
 
 /** @returns {{kind:'allow'|'deny'|'ask', reason?: string}} */
 export function policyDecision (name, args, mode) {
@@ -76,14 +85,15 @@ export function policyDecision (name, args, mode) {
 function decideActuation (name, a, mode) {
   let hr
   try { hr = highRisk(name, a) } catch (error) { return { kind: 'deny', reason: error.message } }
+  const note = name === 'computer_launch' ? LAUNCH_HIGH_RISK_NOTE : HIGH_RISK_NOTE
   switch (mode) {
     case 'read-only':
       return { kind: 'deny', reason: `automationMode=read-only: ${name} drives the machine` }
     case 'standard':
-      return hr ? { kind: 'ask', reason: HIGH_RISK_NOTE + riskSuffix(name, a) }
+      return hr ? { kind: 'ask', reason: note + riskSuffix(name, a) }
         : { kind: 'ask', reason: `automationMode=standard: actuation ${name}` }
     case 'autonomous':
-      return hr ? { kind: 'ask', reason: HIGH_RISK_NOTE + riskSuffix(name, a) } : { kind: 'allow' }
+      return hr ? { kind: 'ask', reason: note + riskSuffix(name, a) } : { kind: 'allow' }
     case 'unrestricted':
       return { kind: 'allow' }
     default:
@@ -98,6 +108,7 @@ function riskSuffix (name, a) {
   if (name === 'computer_key') return ` [combo=${a.combo}]`
   if (name === 'computer_window') return ` [op=${a.op}]`
   if (name === 'computer_type') return ' [allowPassword]'
+  if (name === 'computer_launch') return ` [target=${String(a.target || '').slice(0, 80)}]`
   if (name === 'computer_batch') {
     const actions = Array.isArray(a.actions) ? a.actions : []
     for (let i = 0; i < actions.length; i++) {
@@ -118,6 +129,15 @@ export function highRisk (name, args) {
   }
   if (name === 'computer_window' && String(a.op || 'activate') === 'close') return true
   if (name === 'computer_type' && a.allowPassword) return true
+  if (name === 'computer_launch') {
+    // Win32 strips trailing dots/spaces/ADS-colons when resolving, so "x.exe." RUNS as x.exe —
+    // normalize before matching or the $ anchor is bypassable. http(s) targets lose ?query and
+    // #fragment first so "x.exe?dl=1" is judged exactly like "x.exe". Forward slashes map to
+    // backslashes at resolve time, so //server/share is the UNC it will become.
+    let target = String(a.target || '').trim().replace(/[.\s:]+$/, '')
+    if (/^\w+:\/\//i.test(target)) target = target.replace(/[?#].*$/, '')
+    if (LAUNCH_CODE_TARGET.test(target) || /^\\\\|^\/\//.test(target) || /^file:/i.test(target)) return true
+  }
   if (name === 'computer_batch') {
     const actions = Array.isArray(a.actions) ? a.actions : []
     for (const step of actions) {

package/lib/tools.js

@@ -1,6 +1,6 @@
 // tools.js — defineTool registrations for dsh-computer-use.
 //
-// 18 TOOLS. The previous 28 were merged, not deleted; every capability still exists and the
+// 20 TOOLS. The previous 28 were merged, not deleted; every capability still exists and the
 // behavioural detail lives in the skill (loaded only for computer-use work, while these
 // definitions are paid for on EVERY request).
 //
@@ -22,11 +22,13 @@ import { ObservationStore } from './observations.js'
 import { feedbackPolicy, feedbackActions, feedbackVerification, selectFeedbackDetail } from './feedback.js'
 import { collectCompactState, limitCompactFeedback, feedbackViewport } from './compact-feedback.js'
 import { handoffResult } from './continuation.js'
+import { validateLaunchArgs, validateLaunchTarget } from './launch.js'
 import { join } from 'node:path'
 
 const P = (type, description, extra = {}) => ({ type, description, ...extra })
 const cooperativeTools = new Set(['computer_click', 'computer_move', 'computer_drag', 'computer_scroll',
-  'computer_select', 'computer_key', 'computer_type', 'computer_window', 'computer_uia_act', 'computer_batch', 'computer_clip'])
+  'computer_select', 'computer_key', 'computer_type', 'computer_window', 'computer_uia_act', 'computer_batch', 'computer_clip',
+  'computer_focus'])
 const usesInput = (name, args = {}) => name === 'computer_clip' ? args.text !== undefined :
   name === 'computer_batch' ? (args.actions || []).some(step => usesInput(step.tool, step.args)) :
   cooperativeTools.has(name)
@@ -73,8 +75,21 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     return saveOwnedShot(dataDir, p, buf)
   }
 
+  // Per-call image delivery. `auto` is the existing behaviour and stays the default; `path`
+  // withholds the image block without withholding the file. An unknown value refuses here
+  // rather than silently behaving like auto — a typo must not quietly reintroduce the cost the
+  // caller asked to avoid.
+  const deliveryMode = (value) => {
+    if (value === undefined || value === 'auto') return 'auto'
+    if (value === 'path') return 'path'
+    throw Object.assign(new Error('delivery must be "auto" or "path"'), { code: 'BAD_DELIVERY', outcome: 'not-dispatched' })
+  }
+
   // Shared by direct calls, explicit batch steps, and the batch checkpoint.
   const takeScreenshot = async (args, exec) => {
+    // Refuse a bad value BEFORE the capture: a refused request that already wrote a file and
+    // reports outcome:"not-dispatched" is a false receipt.
+    const delivery = deliveryMode(args.delivery)
     const r = rect(args.region)
     const shot = await cu.screenshot({
       x: r && r.x, y: r && r.y, width: r && r.width, height: r && r.height,
@@ -83,7 +98,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     })
     const path = saveShot(shot.image, shot.mime === 'image/png' ? 'png' : 'jpg')
     const res = { path, mime: shot.mime, region: shot.region, ...screenshotMetadata(shot) }
-    return attachScreenshot(ctx, exec, res, shot.image, { rules: config.feedbackRules })
+    return attachScreenshot(ctx, exec, res, shot.image, { rules: config.feedbackRules, delivery })
   }
 
   const clickTarget = async (args) => {
@@ -149,7 +164,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     if (exec?.signal?.aborted || cu.stopped || cu.exited || cu.cooperation?.active) return true
     try { return !!hooks?.askBlocked?.('computer_shot') } catch { return true }
   }
-  const captureFeedback = async (exec, policy, context = {}) => {
+  const captureFeedback = async (exec, policy, context = {}, delivery = 'auto') => {
     // Route resolution is async: the human can brake while it is pending.
     if (feedbackBlocked(exec)) return { observationSkipped: 'cancelled-or-paused' }
     const compact = policy.detail === 'compact'
@@ -160,7 +175,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     const observation = policy.kind === 'state'
       ? compact ? await collectCompactState(cu, { ...context, checkAllowed,
         archive: raw => hooks?.archiveFeedback ? hooks.archiveFeedback(exec, raw) : archiveFeedback(exec, raw) }) : await observeState({}, exec)
-      : await takeScreenshot(compact ? { region: feedbackViewport(context.args, context.receipt).region } : {}, exec)
+      : await takeScreenshot(compact ? { region: feedbackViewport(context.args, context.receipt).region, delivery } : { delivery }, exec)
     const envelope = { observation, feedback: policy, verification: feedbackVerification }
     if (compact && policy.kind === 'state' && observation.inlineEvidence) {
       // Resource fallback deliberately favors recoverable evidence over the
@@ -354,6 +369,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
       preset: P('string', 'taskbar'),
       png: P('boolean', 'PNG instead of JPEG'),
       wait: P('string', 'auto (default) | none'),
+      delivery: P('string', 'auto (default) | path — path writes the file and returns its absolute path with no image block'),
     },
     output: out((a, v) => renderScreenshot(v)),
     isConcurrencySafe: () => false,
@@ -496,6 +512,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
       clicks: P('number', '1 | 2 (double) | 3 (triple)'),
       shift: P('boolean', 'hold SHIFT (range selection)'),
       verificationRegion: P('string', 'expected effect region "x,y,w,h" in screen pixels; may differ from click point; a change alone does not prove task success'),
+      allowCovered: P('boolean', 'click a pixel owned by the target app\'s OWN embedded renderer (a descendant process of the target, e.g. a WeChat article panel); an unrelated window on top is still refused and the receipt says COVERED-UNRELATED'),
     },
     output: outJSON(),
     isConcurrencySafe: () => false,
@@ -626,6 +643,49 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     async execute (args) { return args.text === undefined ? cu.clipRead() : cu.clipWrite(args.text) },
   })
 
+  // ---------------- launch ----------------
+  // ONE call replaces the Win+R route (activate, combo, type, enter, verify): the worker resolves
+  // the target with ShellExecute, so App Paths aliases (calc), shell: folders, URLs, folders and
+  // document associations all work. The launch is a real actuation — brake checks, the status
+  // halo (with a short self-expiring tail, because a launch returns in milliseconds) and the
+  // audit trail all come from the worker op, not from this file.
+  reg({
+    name: 'computer_launch',
+    description: 'Open an app/URL/folder/document in one call — replaces the Win+R route (activate, combo, type, enter). Aliases (calc), shell: folders, http/https URLs, absolute paths. Pass `args` to start an executable with arguments (a dedicated browser profile: target "…\\msedge.exe", args ["--user-data-dir=…", "--new-window", "<url>"]); each entry is one argument value, quoted once in the worker. Launched means the target reached the launcher, not that the app is ready; verify with computer_state.',
+    parameters: {
+      target: P('string', 'app alias (calc) | shell: folder | http/https URL | absolute path', { required: true }),
+      args: P('array', 'optional argument values for an executable target, one array entry per argument (e.g. ["--user-data-dir=D:\\\\profiles\\\\job", "--new-window", "https://…"]); no shell quoting — spaces and backslashes are ordinary'),
+      tailMs: P('number', 'how long to keep the status halo lit after the launch, 0–10000 ms (default 2500)'),
+    },
+    output: outJSON(),
+    isConcurrencySafe: () => false,
+    timeoutMs: 15_000,
+    async execute (args) { return cu.launch(validateLaunchTarget(args.target), { args: validateLaunchArgs(args.args) }) },
+  })
+
+  // ---------------- focus before typing ----------------
+  reg({
+    name: 'computer_focus',
+    description: 'Put keyboard focus on a FIELD and PROVE it before typing: clicks x,y, then reports the focused UIA control and whether a caret is provable there (OS caret, else a two-frame blink check). Typing follows the focused control, not the window — activating a dialog can leave focus in the document, where text is silently swallowed. Type only when verified:true.',
+    parameters: {
+      x: P('number', 'field centre x in screen pixels', { required: true }),
+      y: P('number', 'field centre y in screen pixels', { required: true }),
+      hwnd: P('number', 'target window; a modal dialog of the same app is accepted'),
+      verifyCaret: P('boolean', 'when the OS reports no caret, fall back to a two-frame blink check (default true)'),
+    },
+    output: outJSON(),
+    isConcurrencySafe: () => false,
+    timeoutMs: 15_000,
+    async execute (args) {
+      return cu.focusField({
+        x: args.x,
+        y: args.y,
+        ...(args.hwnd !== undefined ? { hwnd: args.hwnd } : {}),
+        ...(args.verifyCaret !== undefined ? { verifyCaret: args.verifyCaret } : {}),
+      })
+    },
+  })
+
   // ---------------- the agent asks ----------------
   reg({
     name: 'computer_ask',
@@ -686,6 +746,7 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     parameters: {
       actions: P('array', '[{tool:"computer_click", args:{mark:"M3"}}, ...]', { required: true }),
       shot: P('string', 'auto (default) | always | never; no automatic image after failure, cancel or pause'),
+      delivery: P('string', 'auto (default) | path — the checkpoint keeps its absolute path but attaches no image'),
     },
     output: out((a, v) => {
       const { observation, ...receipt } = v
@@ -699,6 +760,9 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     isConcurrencySafe: () => false,
     timeoutMs: 120_000,
     async execute (args, exec) {
+      // Validate before any step runs: a bad delivery value must not be discovered only at the
+      // checkpoint, after the actions have already been dispatched.
+      const delivery = deliveryMode(args.delivery)
       let automatic, feedback, lastContext = {}
       const detail = selectFeedbackDetail(args.feedback,
         config.actionFeedback === false ? 'none' : config.actionFeedbackDetail ?? 'compact')
@@ -719,15 +783,15 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
           if (feedbackBlocked(exec)) { feedback = { observationSkipped: 'cancelled-or-paused' }; return null }
           if (!policy.kind) { feedback = { feedback: policy, observationSkipped: policy.reason || 'disabled' }; return null }
           hooks?.assertOwnership?.(exec)
-          if (policy.kind === 'state') { feedback = await captureFeedback(exec, policy, lastContext); return null }
-          const captured = await captureFeedback(exec, policy, lastContext)
+          if (policy.kind === 'state') { feedback = await captureFeedback(exec, policy, lastContext, delivery); return null }
+          const captured = await captureFeedback(exec, policy, lastContext, delivery)
           const { observation, ...details } = captured
           automatic = observation
           feedback = details
           if (!automatic) return null
           return automatic.path
         } })
-      return { ...selectBatchScreenshot(result, feedback?.observation ?? automatic, feedback?.feedback?.kind), ...feedback }
+      return { ...selectBatchScreenshot(result, feedback?.observation ?? automatic, feedback?.feedback?.kind, delivery), ...feedback }
     },
   })
 
@@ -798,6 +862,8 @@ export function registerTools ({ ctx, cu, config, dataDir, log, snapshotPath, de
     computer_type: (a) => cu.type(a.text, { mode: a.mode, allowPassword: a.allowPassword }),
     computer_window: (a) => ((a.op || 'activate') === 'activate' ? cu.activateWindow({ hwnd: a.hwnd }) : cu.windowOp({ hwnd: a.hwnd }, a.op, rect(a.rect) || {})),
     computer_clip: (a) => (a.text === undefined ? cu.clipRead() : cu.clipWrite(a.text)),
+    computer_launch: (a) => cu.launch(validateLaunchTarget(a.target), { args: validateLaunchArgs(a.args) }),
+  computer_focus: (a) => cu.focusField({ x: a.x, y: a.y, ...(a.hwnd !== undefined ? { hwnd: a.hwnd } : {}), ...(a.verifyCaret !== undefined ? { verifyCaret: a.verifyCaret } : {}) }),
     computer_uia_act: actUia,
     computer_ask: (a, exec) => askQuestion(a, exec),
     computer_wait: (a) => a.mode === 'stable' ? cu.waitStable({ timeoutMs: a.timeoutMs, hwnd: a.hwnd })