dsh-codex-style-computer-use 1.2.0-rc.3

package/lib/observations.js

@@ -0,0 +1,78 @@
+import { randomBytes } from 'node:crypto'
+
+const clone = value => JSON.parse(JSON.stringify(value))
+const encode = value => JSON.stringify(value)
+const elementKey = e => e.target || (e.runtimeId ? `uia:${e.pid ?? ''}:${e.runtimeId}` : null)
+const windowKey = w => w.hwnd ? `window:${w.pid ?? ''}:${w.hwnd}` : null
+
+// An explicit base prevents implicit deltas after compaction or in an unrelated Agent.
+// Full immutable observations are retained, including every provider field; only the wire view differs.
+export class ObservationStore {
+  constructor ({ capacity = 64 } = {}) {
+    this.capacity = capacity
+    this.scopes = new WeakMap()
+    this.unscoped = {}
+    this.sequence = 0
+    this.prefix = randomBytes(4).toString('hex')
+  }
+  scope (exec) {
+    const owner = exec?.agent || this.unscoped
+    let cache = this.scopes.get(owner)
+    if (!cache) { cache = new Map(); this.scopes.set(owner, cache) }
+    return cache
+  }
+  get (exec, id, kind) {
+    const entry = this.scope(exec).get(id)
+    if (!entry || entry.kind !== kind) throw new Error('OBSERVATION_UNAVAILABLE: snapshot expired or belongs to another Agent/tool; request a fresh full observation')
+    return clone(entry.full)
+  }
+  ownsTarget (exec, target) {
+    return [...this.scope(exec).values()].some(entry => (entry.full.elements || []).some(e => e.target === target))
+  }
+  publish (exec, kind, query, value, since) {
+    const cache = this.scope(exec)
+    const fields = kind === 'uia' ? { elements: elementKey } : { windows: windowKey, uiaFlat: elementKey }
+    const full = clone({ ...value, observation: `O${this.prefix}-${++this.sequence}`, mode: 'full' })
+    // The scope includes the exact query and observed window/process. A change forces a full view.
+    const scope = encode([query, value.hwnd ?? value.active?.hwnd ?? null, value.pid ?? value.active?.pid ?? null])
+    const previous = since && cache.get(since)
+    let wire = full
+    if (since) {
+      let reason = !previous ? 'base-unavailable' : previous.kind !== kind || previous.scope !== scope ? 'scope-changed'
+        : previous.full.truncated || previous.full.uiaTruncated || full.truncated || full.uiaTruncated ? 'incomplete-observation' : null
+      if (!reason) {
+        const delta = {}
+        for (const [field, keyOf] of Object.entries(fields)) {
+          const before = previous.full[field] || [], after = full[field] || []
+          const keyMap = rows => {
+            const map = new Map()
+            for (const row of rows) {
+              const key = keyOf(row)
+              if (!key || map.has(key)) return null
+              map.set(key, row)
+            }
+            return map
+          }
+          const oldMap = keyMap(before), newMap = keyMap(after)
+          if (!oldMap || !newMap) { reason = 'ambiguous-identity'; break }
+          delta[field] = { added: [], changed: [], removed: [] }
+          for (const [key, row] of newMap) {
+            if (!oldMap.has(key)) delta[field].added.push({ key, element: row })
+            else if (encode(oldMap.get(key)) !== encode(row)) delta[field].changed.push({ key, element: row })
+          }
+          for (const key of oldMap.keys()) if (!newMap.has(key)) delta[field].removed.push(key)
+          if (encode([...oldMap.keys()]) !== encode([...newMap.keys()])) delta[field].order = [...newMap.keys()]
+        }
+        if (!reason) {
+          wire = { ...full, mode: 'diff', base: since, delta }
+          for (const field of Object.keys(fields)) delete wire[field]
+          if (encode(wire).length >= encode(full).length) reason = 'delta-not-smaller'
+        }
+      }
+      if (reason) wire = { ...full, resetReason: reason }
+    }
+    cache.set(full.observation, { full, kind, scope })
+    while (cache.size > this.capacity) cache.delete(cache.keys().next().value)
+    return wire
+  }
+}

package/lib/policy.js

@@ -0,0 +1,109 @@
+// policy.js — pure approval decision for dsh-computer-use.
+// Modeled on @anweat/dsh-browser's approval-policy.js: a pure function mapping
+// (toolName, args, automationMode) -> {kind:'allow'|'deny'|'ask', reason}.
+// Fail-closed by construction: unknown tool names are denied.
+//
+// ⚠️ KEEP IN SYNC WITH THE TOOL SURFACE. A fail-closed list is only safe if it is also COMPLETE.
+// 2026-09-13: the tool set was rewritten from 28 names to 17 (merged + renamed) and this
+// allow-list was NOT updated, so the plugin's own gate would have denied most of its own tools
+// with "unknown computer-use tool" — before they ever ran. `build/test-policy.mjs` now fails if
+// any registered tool falls through to that branch, so the next rename cannot silently do this.
+//
+// Two tools cannot be classified by name alone and are decided by their ARGUMENTS:
+//   computer_clip   — no text = read the clipboard; text = write it
+//   computer_ctrl   — selftest = health;  stop = the brake;  exit = end the session;
+//                     calibrate / indicator = control
+// (`resume` is NOT among them any more: it was removed from the tool surface on 2026-09-13 because
+// it un-latched Ctrl+Alt+Q, i.e. a TOOL CALL could re-open a cycle the human had ended. Only the
+// plugin's session/event turn/start opens a cycle, and only the human's Ctrl+Alt+R releases a pause.)
+// computer_ask is argument-independent and BRAKE-LIKE — see its branch below.
+
+export const OBSERVATION_TOOLS = new Set([
+  'computer_shot', 'computer_state', 'computer_marks', 'computer_uia', 'computer_wait',
+])
+
+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',
+])
+
+// combos that escalate: run dialog, window close, signout/lock/taskmgr, delete-key
+const HIGH_RISK_KEY = /(^|\+)(win\+r|alt\+f4|ctrl\+shift\+esc|win\+l|win\+d)(\+|$)/i
+const DESTRUCTIVE_KEY = /(^|\+)(del|delete|bksp|backspace)(\+|$)/i
+
+export const HIGH_RISK_NOTE = 'high-risk action (destructive key / closing a window / password field) — always requires human approval'
+
+/** @returns {{kind:'allow'|'deny'|'ask', reason?: string}} */
+export function policyDecision (name, args, mode) {
+  const a = args || {}
+
+  // ---- the two argument-dependent tools -------------------------------------------------
+  if (name === 'computer_ctrl') {
+    const act = String(a.action || 'selftest')
+    // The brake is available in EVERY mode, including read-only, and it drives nothing.
+    if (act === 'stop') return { kind: 'allow' }
+    if (act === 'recover') return mode === 'read-only'
+      ? { kind: 'deny', reason: 'read-only mode cannot recover control' } : { kind: 'allow' }
+    if (act === 'selftest') return { kind: 'allow' }      // input-path health, never moves the pointer
+    // ends the session: it drives nothing, and the human's own Ctrl+Alt+Q is unconditional. It is
+    // the second answer of the ask protocol ("I cannot proceed") and the ask notice promises the
+    // human the agent can give it — denying it made that answer dead in all four modes.
+    if (act === 'exit') return { kind: 'allow' }
+    if (act === 'calibrate' || act === 'indicator') return decideActuation(name, a, mode)
+    return { kind: 'deny', reason: `unknown computer_ctrl action: ${act}` }
+  }
+
+  // ---- BRAKE-LIKE, and therefore NEVER gated -------------------------------------------------
+  // computer_ask actuates NOTHING: it stops the machine, raises the host window and asks the human
+  // a question. That is the SAFETY DIRECTION — it is the one call that must never sit behind an
+  // approval prompt, because what it is asking for IS human attention. Gating it is exactly
+  // backwards. Until 2026-09-13 it fell through to the fail-closed "unknown computer-use tool"
+  // branch and was DENIED in all four modes, which silently killed the human's own "ask + 5 秒"
+  // rule (their spec: "一旦出现 computer ask, 这时候返回到 DSH desktop 窗口. 若5秒规则内有回应,
+  // 则进入暂停态").
+  if (name === 'computer_ask') return { kind: 'allow' }
+  if (name === 'computer_clip') {
+    if (a.text === undefined) return { kind: 'allow' }     // read
+    return decideActuation(name, a, mode)                  // write
+  }
+
+  if (OBSERVATION_TOOLS.has(name)) return { kind: 'allow' }
+  if (ACTUATION_TOOLS.has(name)) return decideActuation(name, a, mode)
+  return { kind: 'deny', reason: `unknown computer-use tool: ${name}` }
+}
+
+function decideActuation (name, a, mode) {
+  const hr = highRisk(name, a)
+  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 }
+        : { kind: 'ask', reason: `automationMode=standard: actuation ${name}` }
+    case 'autonomous':
+      return hr ? { kind: 'ask', reason: HIGH_RISK_NOTE } : { kind: 'allow' }
+    case 'unrestricted':
+      return { kind: 'allow' }
+    default:
+      return { kind: 'deny', reason: `unknown automationMode: ${mode}` }
+  }
+}
+
+export function highRisk (name, args) {
+  const a = args || {}
+  if (name === 'computer_key') {
+    const combo = String(a.combo || '')
+    if (HIGH_RISK_KEY.test(combo) || DESTRUCTIVE_KEY.test(combo)) return true
+  }
+  if (name === 'computer_window' && String(a.op || 'activate') === 'close') return true
+  if (name === 'computer_type' && a.allowPassword) return true
+  if (name === 'computer_batch') {
+    const actions = Array.isArray(a.actions) ? a.actions : []
+    for (const step of actions) {
+      if (!step) continue
+      const t = String(step.tool || '')
+      if ((ACTUATION_TOOLS.has(t) || t === 'computer_clip' || t === 'computer_ctrl') && highRisk(t, step.args || {})) return true
+    }
+  }
+  return false
+}

package/lib/recovery.js

@@ -0,0 +1,8 @@
+// Host facts checked independently of the native pause credential.
+export function recoveryProblem (permit, claim, cycle, pendingApprovals, exited) {
+  if (!permit || !claim.sessionKey || !claim.agentKey) return 'no temporary pause owned by this execution'
+  if (pendingApprovals) return 'human approval is pending'
+  if (exited || cycle.state !== 'paused' || cycle.id !== permit.cycleId) return 'the original paused cycle changed'
+  if (cycle.ownerIdent !== claim.ident || permit.ownerIdent !== claim.ident) return 'the pause belongs to another owner'
+  return null
+}

package/lib/skill-gate.js

@@ -0,0 +1,68 @@
+// skill-gate.js — "READ THE PROCEDURE BEFORE DRIVING".
+//
+// The human's rule (2026-09-13, verbatim): "未先读 skill 时拒绝驱动类 op". It exists because an
+// agent that skipped the manual improvised its way through a two-call job: it never looked at the
+// window list, spent three rounds attacking an occlusion that did not exist (the windows were
+// MINIMIZED), guessed taskbar coordinates from a scaled screenshot, and then reported all of it to
+// the human as "the environment blocked it".
+//
+// No tool layer can SEE whether a model read a document. So the receipt is a PHRASE THAT ONLY EXISTS
+// INSIDE SKILL.md — the model has to open the file to produce it. That is the strongest honest
+// version of "force it to read": not guessable by accident, verifiable by exact string equality, and
+// free. build/test-skill-gate.mjs asserts this constant against SKILL.md itself, so the manual and
+// the gate can never drift apart (a phrase that lived in only one of the two would either lock the
+// agent out forever or let it in without reading anything).
+//
+// Deliberately NOT in here: any way for the gate to block the safety direction. `computer_ask`, and
+// `computer_ctrl {action:"stop"|"exit"}`, are decided by the caller and never gated — a gate that can
+// block a brake is worse than no gate.
+
+import { ACTUATION_TOOLS } from './policy.js'
+
+export const REQUIRED_PHRASE = 'A MINIMIZED window is not an occluded window'
+
+export const ACK_HINT =
+  'Before the first DRIVING call of a session, read the computer-use skill ' +
+  '(skills/computer-use/SKILL.md) and acknowledge it once: ' +
+  'computer_ctrl {action:"acknowledge", text:"' + REQUIRED_PHRASE + '"}. ' +
+  'Observation tools are never gated, and neither is the safety direction (computer_ask, ' +
+  'computer_ctrl stop/exit).'
+
+const acked = new Set()
+
+/** @returns {boolean} true when `text` is the exact phrase from the skill. */
+export function acknowledge (text, key) {
+  if (String(text == null ? '' : text).trim() !== REQUIRED_PHRASE) return false
+  acked.add(String(key == null ? 'default' : key))
+  return true
+}
+
+export function isAcked (key) {
+  return acked.has(String(key == null ? 'default' : key))
+}
+
+/** Tests only. */
+export function resetAcks () { acked.clear() }
+
+/**
+ * Does this call DRIVE the machine — i.e. does it need the receipt?
+ * It mirrors policy.js's own classification instead of keeping a second list: a drifted list either
+ * locks the agent out of its own tools or lets it through without reading anything.
+ * Never driving: observation, `computer_ask` (the safety direction), and computer_ctrl
+ * stop/selftest/exit/indicator.
+ * Driving: everything in ACTUATION_TOOLS, a clipboard WRITE, calibrate (it moves the pointer) — and a
+ * BATCH only when something INSIDE it drives. Classifying the wrapper alone blocked batches built
+ * from pure observation steps: a false positive that buys no safety and costs a round trip. Recursion
+ * means a nested batch is judged by its innermost steps.
+ */
+export function isDrivingCall (name, args) {
+  const a = args || {}
+  if (name === 'computer_ask') return false
+  if (name === 'computer_ctrl') return String(a.action || 'selftest') === 'calibrate'
+  if (name === 'computer_clip') return a.text !== undefined
+  if (name === 'computer_batch') {
+    const steps = Array.isArray(a.actions) ? a.actions : []
+    return steps.some((step) => step && isDrivingCall(String(step.tool || ''), step.args || {}))
+  }
+  return ACTUATION_TOOLS.has(name)
+}