deepseek-computer-use 0.0.0-stage → 0.1.0

package/lib/build-helper.mjs

@@ -0,0 +1,106 @@
+/**
+ * Build the Windows helper with the system C# compiler.
+ *
+ * Why compile instead of shipping a binary: Windows 10/11 always carry
+ * csc.exe (part of .NET Framework 4.x), so this needs no SDK, no npm native
+ * module, and no build server. The exe is cached and rebuilt only when a
+ * source file is newer.
+ *
+ * @module deepseek-computer-use/build-helper
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = path.resolve(here, '..');
+export const NATIVE_DIR = path.join(PLUGIN_ROOT, 'native');
+export const BIN_DIR = path.join(NATIVE_DIR, 'bin');
+export const HELPER_EXE = path.join(BIN_DIR, 'dsh-computer-use-helper.exe');
+export const OVERLAY_EXE = path.join(BIN_DIR, 'dsh-cu-overlay.exe');
+
+const SOURCES = ['Json.cs', 'Driver.cs', 'Program.cs'].map(name => path.join(NATIVE_DIR, name));
+const OVERLAY_SOURCES = ['Overlay.cs'].map(name => path.join(NATIVE_DIR, name));
+
+/** GAC assembly paths the compiler needs (UIAutomation + WindowsBase are not default refs). */
+const GAC_ROOT = 'C:\\Windows\\Microsoft.NET\\assembly\\GAC_MSIL';
+const GAC_REFS = ['WindowsBase', 'UIAutomationClient', 'UIAutomationTypes'];
+
+function cscCandidates() {
+  return [
+    'C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\csc.exe',
+    'C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\csc.exe',
+  ];
+}
+
+function findGacAssembly(name) {
+  const dir = path.join(GAC_ROOT, name);
+  if (!fs.existsSync(dir)) return null;
+  for (const version of fs.readdirSync(dir)) {
+    const candidate = path.join(dir, version, name + '.dll');
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function findCompiler() {
+  for (const candidate of cscCandidates()) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function isHelperFresh(exe = HELPER_EXE) {
+  if (!fs.existsSync(exe)) return false;
+  const exeTime = fs.statSync(exe).mtimeMs;
+  return SOURCES.every(source => fs.existsSync(source) && fs.statSync(source).mtimeMs <= exeTime);
+}
+
+/**
+ * Compile the helper if it is missing or stale.
+ * @returns {{ exe: string, built: boolean, reason?: string }}
+ */
+export function ensureHelper({ force = false, exe = HELPER_EXE, log } = {}) {
+  if (!force && isHelperFresh(exe)) return { exe, built: false };
+  if (process.platform !== 'win32') return { exe, built: false, reason: 'not-windows' };
+
+  const compiler = findCompiler();
+  if (compiler === null) throw new Error('cannot build the Computer Use helper: csc.exe (.NET Framework 4.x) was not found');
+
+  const refs = [];
+  for (const name of GAC_REFS) {
+    const found = findGacAssembly(name);
+    if (found === null) throw new Error('cannot build the Computer Use helper: reference assembly ' + name + ' is missing from the GAC');
+    refs.push('/r:' + found);
+  }
+
+  fs.mkdirSync(path.dirname(exe), { recursive: true });
+  const args = ['/nologo', '/target:exe', '/platform:anycpu', '/out:' + exe, ...SOURCES, ...refs];
+  log?.('[dsh-computer-use] compiling helper with ' + compiler);
+  const output = execFileSync(compiler, args, { encoding: 'utf8', windowsHide: true });
+  if (!fs.existsSync(exe)) throw new Error('helper compilation produced no executable: ' + output);
+  return { exe, built: true };
+}
+
+/** The in-use indicator (breathing frame + virtual cursor) is a separate win-exe. */
+export function isOverlayFresh(exe = OVERLAY_EXE) {
+  if (!fs.existsSync(exe)) return false;
+  const exeTime = fs.statSync(exe).mtimeMs;
+  return OVERLAY_SOURCES.every(source => fs.existsSync(source) && fs.statSync(source).mtimeMs <= exeTime);
+}
+
+export function ensureOverlay({ force = false, exe = OVERLAY_EXE, log } = {}) {
+  if (!force && isOverlayFresh(exe)) return { exe, built: false };
+  if (process.platform !== 'win32') return { exe, built: false, reason: 'not-windows' };
+  const compiler = findCompiler();
+  if (compiler === null) throw new Error('cannot build the Computer Use overlay: csc.exe (.NET Framework 4.x) was not found');
+
+  fs.mkdirSync(path.dirname(exe), { recursive: true });
+  const args = ['/nologo', '/target:winexe', '/platform:anycpu', '/out:' + exe, ...OVERLAY_SOURCES,
+    '/r:System.Windows.Forms.dll', '/r:System.Drawing.dll'];
+  log?.('[dsh-computer-use] compiling overlay with ' + compiler);
+  const output = execFileSync(compiler, args, { encoding: 'utf8', windowsHide: true });
+  if (!fs.existsSync(exe)) throw new Error('overlay compilation produced no executable: ' + output);
+  return { exe, built: true };
+}

package/lib/build-native.mjs

@@ -0,0 +1,52 @@
+/**
+ * Build the optional native helpers:
+ *   capture/  Windows.Graphics.Capture tool (net48 + SharpDX)
+ *   audio/    WASAPI loopback recorder (net48 + NAudio)
+ *
+ * Both target .NET Framework 4.8 - no runtime for the user to install - but they
+ * do need the .NET SDK to compile (NuGet restore). When dotnet is missing the
+ * plugin still works: capture falls back to PrintWindow and audio reports
+ * `audio_missing`.
+ *
+ * @module deepseek-computer-use/build-native
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BIN_DIR, PLUGIN_ROOT } from './build-helper.mjs';
+
+const PROJECTS = [
+  { name: 'capture', csproj: path.join(PLUGIN_ROOT, 'native', 'wgcfw', 'Capture.csproj'), output: path.join(BIN_DIR, 'capture'), exe: 'dsh-cu-capture.exe' },
+  { name: 'audio', csproj: path.join(PLUGIN_ROOT, 'native', 'audio', 'Audio.csproj'), output: path.join(BIN_DIR, 'audio'), exe: 'dsh-cu-audio.exe' },
+];
+
+function hasDotnet() {
+  try { execFileSync('dotnet', ['--version'], { stdio: 'ignore', windowsHide: true }); return true; } catch { return false; }
+}
+
+export function buildNative({ log } = {}) {
+  if (!hasDotnet()) {
+    log?.('[dsh-computer-use] .NET SDK not found: skipping capture/audio (fallbacks stay active)');
+    return { built: [], skipped: PROJECTS.map(p => p.name) };
+  }
+  const built = [];
+  const skipped = [];
+  for (const project of PROJECTS) {
+    if (!fs.existsSync(project.csproj)) { skipped.push(project.name); continue; }
+    try {
+      log?.('[dsh-computer-use] building native/' + project.name);
+      execFileSync('dotnet', ['build', project.csproj, '-c', 'Release', '-v', 'q', '--nologo'], { stdio: 'inherit', windowsHide: true });
+      const produced = path.join(path.dirname(project.csproj), 'bin', 'Release', 'net48');
+      fs.mkdirSync(project.output, { recursive: true });
+      for (const file of fs.readdirSync(produced)) {
+        if (!file.endsWith('.pdb')) fs.copyFileSync(path.join(produced, file), path.join(project.output, file));
+      }
+      if (fs.existsSync(path.join(project.output, project.exe))) built.push(project.name);
+      else skipped.push(project.name);
+    } catch (error) {
+      log?.('[dsh-computer-use] ' + project.name + ' build failed: ' + error.message);
+      skipped.push(project.name);
+    }
+  }
+  return { built, skipped };
+}

package/lib/build.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Build every native piece this plugin uses:
+ *   helper   UIA / SendInput / capture dispatch   (csc, always available)
+ *   overlay  in-use indicator                     (csc, always available)
+ *   capture  Windows.Graphics.Capture             (needs .NET SDK)
+ *   audio    WASAPI loopback recorder             (needs .NET SDK)
+ */
+import { ensureHelper, ensureOverlay, HELPER_EXE, OVERLAY_EXE } from './build-helper.mjs';
+import { buildNative } from './build-native.mjs';
+
+const log = message => console.log(message);
+
+const helper = ensureHelper({ force: process.argv.includes('--force'), log });
+log('[dsh-computer-use] helper  ' + (helper.built ? 'built' : 'up to date') + ' -> ' + HELPER_EXE);
+
+const overlay = ensureOverlay({ force: process.argv.includes('--force'), log });
+log('[dsh-computer-use] overlay ' + (overlay.built ? 'built' : 'up to date') + ' -> ' + OVERLAY_EXE);
+
+const native = buildNative({ log });
+log('[dsh-computer-use] capture/audio built: ' + (native.built.join(', ') || 'none') +
+    (native.skipped.length > 0 ? ' | skipped: ' + native.skipped.join(', ') : ''));

package/lib/config.js

@@ -0,0 +1,95 @@
+/**
+ * Configuration for deepseek-computer-use.
+ *
+ * Every field has a safe default: an empty config block must boot without
+ * touching a mouse, a keyboard, or the network.
+ *
+ * @module deepseek-computer-use/config
+ */
+
+/** Accessible names that almost always carry an irreversible side effect. */
+export const DEFAULT_RISKY_PATTERN =
+  '(\\bdelete\\b|\\bremove\\b|\\buninstall\\b|\\bformat\\b|\\berase\\b|\\bwipe\\b|\\breset\\b|' +
+  '\\bpay\\b|\\bpurchase\\b|\\bbuy\\b|\\btransfer\\b|\\bsubmit\\b|\\bsend\\b|\\bpublish\\b|\\bpost\\b|' +
+  '\\binstall\\b|删除|移除|卸载|格式化|清空|重置|支付|付款|转账|购买|下单|提交|发送|发布|安装|运行)';
+
+const DEFAULTS = {
+  /** 'never' | 'sensitive' | 'always' — when to ask the DSH approval seam. */
+  approval: 'sensitive',
+  /** Empty array means "every app is reachable". Substrings of exe path or process name. */
+  allowApps: [],
+  denyApps: [],
+  /** Codex parity: get_window_state captures a screenshot unless told otherwise. */
+  defaultIncludeScreenshot: true,
+  maxElements: 260,
+  snapshotTtlMs: 120000,
+  /** Codex waits for the UI to settle before the next capture; same idea here. */
+  settleMs: 1000,
+  /** Ask once per app before Computer Use touches it ('session') or never ('never'). */
+  appConsent: 'session',
+  /** Apps whose screenshots must never be captured (substring match on path/name). */
+  redactApps: [],
+  /** WASAPI loopback recording tools (Codex gates the same feature behind SKY_ENABLE_AUDIO). */
+  audio: false,
+  /** Record actions in the result instead of injecting them (integration rehearsals). */
+  dryRun: false,
+  /** Prefix for every tool name, e.g. 'cu_' when another plugin already owns click/type_text. */
+  toolPrefix: '',
+  /** Request budget. Codex uses 10s for ordinary calls and 15s for launch_app. */
+  timeoutMs: 10000,
+  launchTimeoutMs: 15000,
+  helperPath: null,
+  riskyPattern: DEFAULT_RISKY_PATTERN,
+};
+
+const APPROVAL_MODES = new Set(['never', 'sensitive', 'always']);
+
+function clampInt(value, min, max, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+
+function stringList(value, fallback) {
+  if (!Array.isArray(value)) return fallback;
+  return value.map(item => String(item).trim()).filter(item => item.length > 0);
+}
+
+/**
+ * Normalize an untrusted config block into the resolved shape the plugin uses.
+ * Unknown keys are dropped; invalid values fall back instead of throwing so a
+ * bad config can never keep the host from starting.
+ */
+export function resolveConfig(raw = {}) {
+  const input = raw && typeof raw === 'object' ? raw : {};
+  const approval = APPROVAL_MODES.has(input.approval) ? input.approval : DEFAULTS.approval;
+  let riskyPattern = DEFAULTS.riskyPattern;
+  if (typeof input.riskyPattern === 'string' && input.riskyPattern.length > 0) {
+    try {
+      new RegExp(input.riskyPattern);
+      riskyPattern = input.riskyPattern;
+    } catch {
+      riskyPattern = DEFAULTS.riskyPattern;
+    }
+  }
+  return {
+    approval,
+    allowApps: stringList(input.allowApps, DEFAULTS.allowApps),
+    denyApps: stringList(input.denyApps, DEFAULTS.denyApps),
+    defaultIncludeScreenshot: input.defaultIncludeScreenshot !== false,
+    maxElements: clampInt(input.maxElements, 20, 2000, DEFAULTS.maxElements),
+    snapshotTtlMs: clampInt(input.snapshotTtlMs, 1000, 3600000, DEFAULTS.snapshotTtlMs),
+    settleMs: clampInt(input.settleMs, 0, 10000, DEFAULTS.settleMs),
+    appConsent: input.appConsent === 'never' ? 'never' : DEFAULTS.appConsent,
+    redactApps: stringList(input.redactApps, DEFAULTS.redactApps),
+    audio: input.audio === true,
+    dryRun: input.dryRun === true,
+    toolPrefix: typeof input.toolPrefix === 'string' ? input.toolPrefix : DEFAULTS.toolPrefix,
+    timeoutMs: clampInt(input.timeoutMs, 1000, 120000, DEFAULTS.timeoutMs),
+    launchTimeoutMs: clampInt(input.launchTimeoutMs, 1000, 120000, DEFAULTS.launchTimeoutMs),
+    helperPath: typeof input.helperPath === 'string' && input.helperPath.length > 0 ? input.helperPath : null,
+    riskyPattern,
+  };
+}
+
+export { DEFAULTS };

package/lib/index.js

@@ -0,0 +1,156 @@
+/**
+ * deepseek-computer-use - Windows Computer Use for DeepSeek Harness.
+ *
+ * Registers the Codex window2 tool surface on top of a native Windows driver
+ * (UI Automation + SendInput + PrintWindow). The heavy lifting lives in a
+ * long-lived C# helper so element indexes stay valid across calls; this module
+ * owns the DSH seams: tool registration, image attachment, approval gating and
+ * config.
+ *
+ * @module deepseek-computer-use
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HelperBridge } from './bridge.js';
+import { resolveConfig } from './config.js';
+import { ensureHelper, ensureOverlay, findCompiler, HELPER_EXE, isHelperFresh, isOverlayFresh } from './build-helper.mjs';
+import { buildTools } from './tools.js';
+
+export const name = 'deepseek-computer-use';
+/** Only the tool registry is mandatory; skills/attachments/approval are optional. */
+export const inject = ['tools'];
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.resolve(here, '..', 'skills', 'computer-use');
+
+function readSkill() {
+  try {
+    const text = fs.readFileSync(path.join(SKILL_DIR, 'SKILL.md'), 'utf8').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+    const match = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*\n?/.exec(text);
+    if (match === null) return null;
+    let skillName = '';
+    let description = '';
+    for (const rawLine of match[1].split('\n')) {
+      const keyMatch = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*)$/.exec(rawLine.trim());
+      if (keyMatch === null) continue;
+      if (keyMatch[1] === 'name') skillName = keyMatch[2].replace(/^["']|["']$/g, '').trim();
+      if (keyMatch[1] === 'description') description = keyMatch[2].replace(/^["']|["']$/g, '').trim();
+    }
+    const content = text.slice(match[0].length).trimStart();
+    if (skillName === '' || description === '' || content.length === 0) return null;
+    return { name: skillName, description, content };
+  } catch {
+    return null;
+  }
+}
+
+export function apply(ctx, rawConfig = {}) {
+  const config = resolveConfig(rawConfig);
+  const warn = message => {
+    try { ctx.logger?.warn?.(message); } catch { /* logger is optional */ }
+  };
+
+  const states = new Map();
+  let bridge = null;
+  let starting = null;
+  const exePath = config.helperPath ?? HELPER_EXE;
+
+  async function startBridge() {
+    const built = ensureHelper({ exe: exePath, log: warn });
+    // The in-use indicator is a second exe; build it eagerly so the very first
+    // action already shows the breathing frame instead of a silent no-op.
+    try { ensureOverlay({ log: warn }); } catch (error) { warn('overlay build skipped: ' + error.message); }
+    return new HelperBridge({ exe: built.exe, timeoutMs: config.timeoutMs, log: warn });
+  }
+
+  async function getBridge() {
+    if (bridge !== null) return bridge;
+    if (starting === null) starting = startBridge();
+    try {
+      bridge = await starting;
+      return bridge;
+    } catch (error) {
+      starting = null;
+      throw error;
+    }
+  }
+
+  let configured = false;
+  let lastToken = null;
+
+  async function request(method, params = {}, opts = {}) {
+    const active = await getBridge();
+
+    if (!configured) {
+      // The helper refuses windows whose app was never approved; keep that switch in
+      // sync with the plugin policy.
+      try {
+        await active.request('configure', { requireAppApproval: config.appConsent !== 'never' }, { timeoutMs: config.timeoutMs });
+      } catch { /* older helper */ }
+      configured = true;
+    }
+
+    const token = opts.turnToken;
+    if (token !== undefined && token !== lastToken) {
+      if (lastToken !== null) {
+        // Turn boundary: drop element snapshots, screenshot regions and the Esc block.
+        try { await active.request('end_turn', {}, { timeoutMs: 5000 }); } catch { /* best effort */ }
+      }
+      lastToken = token;
+    }
+
+    const timeoutMs = opts.timeoutMs ?? (method === 'launch_app' ? config.launchTimeoutMs : config.timeoutMs);
+    return active.request(method, params, { ...opts, timeoutMs });
+  }
+
+  const describeHelper = () => {
+    try {
+      return {
+        path: exePath,
+        exists: fs.existsSync(exePath),
+        fresh: isHelperFresh(exePath),
+        compiler: findCompiler(),
+        overlay: isOverlayFresh(),
+        platform: process.platform,
+      };
+    } catch (error) {
+      return { path: exePath, error: error.message };
+    }
+  };
+
+  const disposers = [];
+  for (const definition of buildTools(config, { request, ctx, log: warn, states, describeHelper })) {
+    disposers.push(ctx.tools.register(definition));
+  }
+
+  // Optional: publish the bundled operator guide as a DSH skill.
+  try {
+    const skills = ctx.get?.('skills') ?? ctx.skills;
+    const skill = readSkill();
+    if (skill !== null && skills !== undefined && typeof skills.register === 'function') {
+      disposers.push(skills.register({
+        name: skill.name,
+        description: skill.description,
+        content: skill.content,
+        resourceBase: { kind: 'directory', path: SKILL_DIR },
+        source: 'runtime',
+      }));
+    }
+  } catch (error) {
+    warn('[dsh-computer-use] skill registration skipped: ' + error.message);
+  }
+
+  if (typeof ctx.on === 'function') {
+    ctx.on('dispose', () => {
+      try { bridge?.dispose(); } catch { /* already gone */ }
+      bridge = null;
+      for (const dispose of disposers) {
+        try { dispose(); } catch { /* registry may be tearing down */ }
+      }
+    });
+  }
+}
+
+export { resolveConfig, buildTools, HelperBridge };
+export default { name, inject, apply };

package/lib/safety.js

@@ -0,0 +1,247 @@
+/**
+ * Safety layers for deepseek-computer-use.
+ *
+ * Three independent gates, in the order the action hits them:
+ *   1. hard deny   - never automatable, not even with user approval
+ *                    (terminals, Run dialog, password managers, security
+ *                     software, auth dialogs, the agent's own app, Win key)
+ *   2. reachability - is this app inside allowApps and outside denyApps?
+ *   3. confirmation - should the user approve this specific action?
+ *
+ * Ported from Codex's computer-use guidance.md ("Non-negotiable Windows
+ * Automation Safety") and confirmations.md.
+ *
+ * @module deepseek-computer-use/safety
+ */
+
+export class PolicyError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'PolicyError';
+    this.code = code;
+  }
+}
+
+/**
+ * Processes that must never be driven by UI automation.
+ * Matched as lowercase substrings against the exe path, process name and title.
+ */
+export const HARD_DENY_APPS = [
+  // terminals and shells
+  'windowsterminal', 'windows terminal', 'wt.exe', 'cmd.exe', 'conhost', 'consolewindowclass',
+  'powershell.exe', 'pwsh.exe', 'powershell ise', 'mintty', 'git-bash', 'bash.exe', 'wsl.exe', 'ubuntu.exe',
+  // launch surfaces that can run arbitrary commands
+  'run dialog', '运行', 'shellexperiencehost',
+  // credential stores
+  '1password', 'keepass', 'bitwarden', 'lastpass', 'dashlane', 'keeper', 'enpass', 'nordpass', 'roboform',
+  // security and anti-malware
+  'securityhealth', 'windows security', 'windows 安全中心', 'msmpeng', 'defender', 'malwarebytes',
+  'avast', 'avg', 'kaspersky', 'bitdefender', 'eset', 'norton', 'mcafee', 'sophos', 'crowdstrike', 'sentinelone',
+  // authentication and elevation surfaces
+  'consent.exe', 'credentialuibroker', 'logonui', 'useraccountcontrol',
+  // the agent's own host and other assistants: automating them invites prompt loops
+  'deepseek harness', 'chatgpt', 'codex',
+];
+
+/** Window classes that are terminal-like regardless of the owning exe name. */
+const HARD_DENY_CLASSES = [
+  'consolewindowclass', 'cascadia_hosting_window_class', 'mintty', '#32770',
+];
+
+/** Key tokens that are banned outright (Windows key family). */
+const DENY_KEY_TOKENS = new Set([
+  'win', 'win_l', 'win_r', 'lwin', 'rwin', 'super', 'super_l', 'super_r', 'meta', 'meta_l', 'meta_r',
+  'cmd', 'command', 'os', 'os_l', 'os_r', 'windows', 'windows_l', 'windows_r', 'lwindows', 'rwindows',
+]);
+
+function lower(value) {
+  return String(value ?? '').toLowerCase();
+}
+
+function matchesAny(haystack, needles) {
+  const value = lower(haystack);
+  return needles.some(needle => value.includes(needle.toLowerCase()));
+}
+
+/**
+ * Gate 1: refuse windows that must never be automated.
+ * Runs before allowApps/denyApps so a user cannot opt into it by accident.
+ */
+export function assertNotHardDenied(window, extraDeny = HARD_DENY_APPS) {
+  const app = window?.app ?? {};
+  const fields = {
+    appId: String(app.id ?? ''),
+    appName: String(app.name ?? ''),
+    displayName: String(app.displayName ?? ''),
+    title: String(window?.title ?? ''),
+    className: String(window?.className ?? ''),
+  };
+  const hit = Object.values(fields).find(value => matchesAny(value, extraDeny));
+  if (hit !== undefined) {
+    throw new PolicyError(
+      'hard_denied',
+      'Computer Use refuses to automate "' + (fields.title || fields.appName || fields.className) +
+        '": terminals, Run dialogs, credential stores, security software, authentication dialogs and the agent host are hard-denied and cannot be approved.',
+    );
+  }
+  const deniedClass = HARD_DENY_CLASSES.find(name => fields.className.toLowerCase().startsWith(name));
+  if (deniedClass !== undefined) {
+    throw new PolicyError(
+      'hard_denied',
+      'Computer Use refuses to automate window class "' + fields.className + '": console/dialog classes are hard-denied (Run dialog, terminals, generic system dialogs).',
+    );
+  }
+}
+
+/**
+ * Gate 1 for keyboard: the Windows key family is banned, alone or in a chord.
+ * Windows+anything can open Run, Settings, lock the desktop or trigger shell jumps.
+ */
+export function assertKeyAllowed(key) {
+  const parts = String(key ?? '').split('+').map(part => lower(part).trim()).filter(part => part.length > 0);
+  const banned = parts.find(part => DENY_KEY_TOKENS.has(part));
+  if (banned !== undefined) {
+    throw new PolicyError(
+      'hard_denied',
+      'the Windows/Meta/Super key ("' + banned + '") is hard-denied: it opens Run, Settings and shell surfaces that Computer Use must never drive.',
+    );
+  }
+}
+
+/** Gate 1 for launch targets. */
+export function assertLaunchAllowed(app) {
+  const value = lower(app);
+  const banned = HARD_DENY_APPS.find(needle => value.includes(needle.toLowerCase()));
+  if (banned !== undefined) {
+    throw new PolicyError('hard_denied', 'Computer Use refuses to launch "' + app + '": that surface is hard-denied.');
+  }
+}
+
+/** Gate 2: allowApps / denyApps. */
+export function assertAppAllowed(config, app, window) {
+  const id = String(app?.id ?? '');
+  const name = String(app?.name ?? app?.displayName ?? '');
+  const title = String(window?.title ?? '');
+  if (matchesAny(id, config.denyApps) || matchesAny(name, config.denyApps) || matchesAny(title, config.denyApps)) {
+    throw new PolicyError('app_denied', 'the Computer Use policy denies app "' + (name || id) + '" (denyApps)');
+  }
+  if (config.allowApps.length > 0 && !matchesAny(id, config.allowApps) && !matchesAny(name, config.allowApps)) {
+    throw new PolicyError('app_not_allowed', 'app "' + (name || id) + '" is outside allowApps; add it to the plugin config to permit this action');
+  }
+}
+
+/** The accessible label an action would hit, from the cached observation. */
+export function labelOfElement(state, elementIndex) {
+  if (state === undefined || elementIndex === undefined || elementIndex === null) return '';
+  const elements = state.elements;
+  if (!Array.isArray(elements)) return '';
+  const hit = elements.find(element => Number(element.index) === Number(elementIndex));
+  if (hit === undefined) return '';
+  return String(hit.name ?? '') + ' ' + String(hit.role ?? '');
+}
+
+/**
+ * Gate 3: decide whether an action needs a human answer.
+ * 'sensitive' asks when the target label looks irreversible; launch_app always asks;
+ * 'always' asks for everything.
+ */
+export function needsApproval(config, { toolName, label = '' }) {
+  if (config.approval === 'never') return false;
+  if (config.approval === 'always') return true;
+  if (toolName === 'launch_app') return true;
+  if (label.length === 0) return false;
+  try {
+    return new RegExp(config.riskyPattern, 'i').test(label);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask the DSH approval seam and fail closed.
+ * A missing answerer rejects the action; it never silently proceeds.
+ */
+export async function requestApproval(ctx, exec, { toolName, reason }) {
+  const approval = ctx?.get?.('approval');
+  // The user's session preset may disable prompting entirely ("approval: never",
+  // e.g. the full-access preset). Honour that instead of failing every action:
+  // the hard denies above still apply, and asking would only return "rejected".
+  try {
+    if (typeof approval?.effectivePolicy === 'function') {
+      const policy = approval.effectivePolicy(exec?.agent?.session);
+      if (policy === 'never') return;
+    }
+  } catch { /* policy lookup is best effort */ }
+  if (approval === undefined || approval === null || typeof approval.request !== 'function') {
+    throw new PolicyError(
+      'approval_unavailable',
+      'this action needs user confirmation but no approval service is mounted; switch the session approval policy or change approval mode in the plugin config',
+    );
+  }
+  const outcome = await approval.request({
+    agent: exec?.agent,
+    toolName,
+    callId: exec?.callId,
+    reason,
+    signal: exec?.signal,
+  });
+  if (outcome !== 'allowed-once') {
+    throw new PolicyError('approval_denied', 'the user did not approve this action (' + outcome + ')');
+  }
+}
+
+/**
+ * Codex stops issuing input once a turn ends. The DSH session log is the only
+ * place that knows, so read it defensively: an unknown session shape never
+ * blocks an action, but a provably closed turn does.
+ */
+export function assertTurnOpen(exec) {
+  const session = exec?.agent?.session;
+  if (session === undefined || session === null) return;
+  if (typeof session.seq !== 'number' || typeof session.eventAt !== 'function') return;
+  const floor = Math.max(0, session.seq - 400);
+  for (let index = session.seq - 1; index >= floor; index -= 1) {
+    let type;
+    try { type = session.eventAt(index)?.type; } catch { return; }
+    if (type === 'turn/start') return;
+    if (type === 'turn/end') {
+      throw new PolicyError('turn_ended', 'the turn that requested this action has ended, so Computer Use stops issuing input. Ask the user to continue in a new turn.');
+    }
+  }
+}
+
+/**
+ * A token that identifies the current turn. Codex blocks further Computer Use
+ * calls for the rest of a turn once the user hits Esc; the helper cannot know
+ * about turns, so the plugin sends this token with every call.
+ */
+export function turnTokenOf(exec) {
+  const session = exec?.agent?.session;
+  if (session === undefined || session === null) return 'none';
+  if (typeof session.seq !== 'number' || typeof session.eventAt !== 'function') return 'none';
+  const floor = Math.max(0, session.seq - 400);
+  for (let index = session.seq - 1; index >= floor; index -= 1) {
+    let type;
+    try { type = session.eventAt(index)?.type; } catch { return 'none'; }
+    if (type === 'turn/start') {
+      // Include the session so a persisted Esc marker can never block a later session
+      // that happens to reuse the same turn index (Codex scopes markers the same way).
+      const id = session.id ?? session.sessionId ?? session.key;
+      const scope = typeof id === 'string' && id.length > 0 ? id : 'session';
+      return scope + ':' + 'turn-' + index;
+    }
+  }
+  return 'none';
+}
+
+/**
+ * Windows whose pixels must never leave the machine ("appshot" guard). Codex mounts a
+ * prepared overlay around the capture; here the same intent is enforced by refusing the
+ * screenshot for the listed apps and reporting it.
+ */
+export function isRedacted(config, app) {
+  const list = Array.isArray(config?.redactApps) ? config.redactApps : [];
+  if (list.length === 0) return false;
+  const haystack = (String(app?.id ?? '') + ' ' + String(app?.name ?? '') + ' ' + String(app?.displayName ?? '')).toLowerCase();
+  return list.some(needle => haystack.includes(String(needle).toLowerCase()));
+}