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

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 })

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "dsh-codex-style-computer-use",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Codex-style Computer Use for DeepSeek Harness: Windows desktop control, screenshots, UI Automation, human input handoff, approval gates and prebuilt native workers. Install and update from dsh-market without PowerShell 7 or build steps.",
   "type": "module",
   "main": "lib/index.js",
+  "bin": {
+    "dsh-codex-style-computer-use": "mcp/src/index.js",
+    "dsh-computer-use-mcp": "mcp/src/index.js"
+  },
   "exports": {
     ".": "./lib/index.js",
     "./package.json": "./package.json",

package/scripts/verify-package.mjs

@@ -23,6 +23,15 @@ for (const [source, binary] of [
   assert.equal(manifest.architecture, 'x64')
 }
 for (const file of ['lib/index.js', 'lib/approval-attribution.js', 'lib/core/native-runtime.js', 'lib/attention-native.js', 'skills/computer-use/SKILL.md', 'mcp/src/index.js']) assert(fs.existsSync(path.join(root, file)), file)
+// The npx entry is model-facing documentation: a bin that is absent, points at a missing file,
+// or lacks the node shebang is a broken promise that the marketplace cannot detect.
+const bins = pkg.bin ?? {}
+assert(Object.keys(bins).length > 0, 'package must expose a bin for the embedded MCP server')
+for (const [name, target] of Object.entries(bins)) {
+  const file = path.join(root, target)
+  assert(fs.existsSync(file), `bin ${name} target missing: ${target}`)
+  assert(fs.readFileSync(file, 'utf8').startsWith('#!/usr/bin/env node'), `bin ${name} target needs a node shebang`)
+}
 const attention = fs.readFileSync(path.join(root, 'lib/attention-native.js'), 'utf8')
 assert(attention.includes("'./core/native-runtime.js'"), 'attention helper must use the bundled core')
 console.log(`ok package: ${pkg.name}@${pkg.version}; prebuilt helpers verified; no install hooks`)