dsh-win-cua 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Wesley Wang
+Copyright (c) 2026 WJPGKZ
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,4 @@
-# dsh-win32-cua
+# dsh-win-cua
 
 Windows computer-use for DeepSeek Harness: **real** mouse and keyboard input plus screen
 capture, with no external driver.
@@ -19,18 +19,30 @@ the virtual screen; the primary display's top-left is `(0, 0)`.
 
 ## Tools
 
-- `cua_screenshot` — capture the virtual screen to a PNG, return path and size
-- `cua_mouse_move` — move the pointer
-- `cua_mouse_click` — click / double-click / right / middle, optionally at x,y
-- `cua_scroll` — wheel
+**Look**
+- `cua_screenshot` — capture the whole virtual screen to a PNG
+- `cua_screenshot_window` — capture one window by handle (`PrintWindow`, screen-blit fallback)
+- `cua_zoom` — capture a region and upscale it x1–x4 for reading small UI text
+- `cua_windows` — visible top-level windows with bounds and flags
+- `cua_app_list` — same list enriched with the process executable name
+- `cua_cursor` — pointer position and virtual-screen geometry
+
+**Act**
+- `cua_mouse_move` — move the pointer along a human path
+- `cua_mouse_click` — click / double / right / middle, optionally at x,y
+- `cua_drag` — press, travel and release with the button held
+- `cua_scroll` — wheel, vertical or horizontal
 - `cua_key` — one key with optional modifiers
-- `cua_type` — type text
-- `cua_windows` — visible top-level windows
-- `cua_focus_window` — restore and focus a window
-- `cua_cursor` — pointer position and screen geometry
+- `cua_type` — type text (unicode, incl. surrogate pairs)
+
+**Window & app**
+- `cua_focus_window` — restore and foreground a window
+- `cua_wait` — sleep and/or poll until a window title appears
+- `cua_app_launch` — launch an executable without a shell
 
 Every tool declares `output { schema, render }` — the DSH tool registry rejects raw
-definitions without it, so keep that shape when adding tools.
+definitions without it, so keep that shape when adding tools. Read-only tools are marked
+`readOnly` and register as `isConcurrencySafe`.
 
 ## Config
 
@@ -39,16 +51,36 @@ Set in this bundle's `cordis.patch.yml` under `config`:
 | Key | Default | Meaning |
 |---|---|---|
 | `humanize` | `true` | Pointer travels a smoothstep path, typing and clicking keep a human cadence |
-| `keepScreenshots` | `30` | Newest screenshots kept per capture directory |
+| `keepScreenshots` | `30` | Newest captures kept per directory |
 | `moveSteps` | `16` | Max pointer steps for a humanized move |
 | `keyDelayMs` | `[12, 34]` | Per-character delay range for humanized typing |
 | `clickSettleMs` | `[60, 140]` | Pause between the pointer arriving and the button press |
+| `zoomFactor` | `2` | Default `cua_zoom` upscale factor (hard cap 4) |
+| `zoomMaxPixels` | `24000000` | Largest upscaled image allowed |
+| `maxWaitMs` | `10000` | Upper bound for `cua_wait` |
+| `allowLaunch` | `true` | Set `false` to disable `cua_app_launch` |
 
 Pointer targets are clamped into the virtual screen, and astral code points (emoji,
 CJK extension B) are sent as surrogate pairs so `KEYEVENTF_UNICODE` types them correctly.
 
+## No external driver
+
+Unlike `dsh-computer-use` (which shells out to the `cua-driver` binary) this plugin calls
+Win32 through koffi **inside the host process**: nothing to install, no daemon, no
+`CUA_DRIVER_BIN`. The trade-off is honest: without the driver there is no UIA/accessibility
+tree, so targeting is pixel-based — use `cua_zoom` / `cua_screenshot_window` to read a
+window precisely before clicking.
+
 ## Install
 
+From npm:
+
+```powershell
+dsh plugin --profile <profile> add dsh-win-cua
+```
+
+Or from a checkout / local directory:
+
 ```powershell
 dsh plugin --profile <profile> add <this directory>
 ```
@@ -57,3 +89,19 @@ Or in the Desktop app: Plugin Manager → install bundle → pick this directory
 
 Windows only. `SendInput` injects into the session whose input queue is active — a window
 on a locked or disconnected desktop receives nothing.
+
+## Changelog
+
+### 0.2.0
+
+- New look tools: `cua_screenshot_window` (PrintWindow with screen-blit fallback),
+  `cua_zoom` (region capture upscaled x1–x4), `cua_app_list` (windows with process names).
+- New act tools: `cua_drag`, `cua_wait`, `cua_app_launch` (disabled with `allowLaunch: false`).
+- `humanize` is now a real config knob: smoothstep pointer path, per-character typing
+  delay and click settle range, with `moveSteps` / `keyDelayMs` / `clickSettleMs` tuning.
+- PNG encoder, screenshot retention (`keepScreenshots`) and coordinate clamping tightened.
+
+### 0.1.0
+
+First public release: screenshot, cursor, window list/focus, mouse move/click/scroll,
+key press and unicode typing.

package/cordis.patch.yml

@@ -4,4 +4,7 @@
       config:
         humanize: true
         keepScreenshots: 30
+        zoomFactor: 2
+        maxWaitMs: 10000
+        allowLaunch: true
 

package/index.js

@@ -1,5 +1,5 @@
 /**
- * @local/dsh-win32-cua — Windows computer-use for DeepSeek Harness.
+ * dsh-win-cua — Windows computer-use for DeepSeek Harness.
  *
  * Real mouse and keyboard input through user32 `SendInput`, screen capture through
  * GDI `BitBlt` (CAPTUREBLT so layered windows are included), and a top-level window
@@ -11,7 +11,8 @@
  */
 import { deflateSync } from 'node:zlib';
 import { createRequire } from 'node:module';
-import { mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readdirSync, unlinkSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -50,6 +51,7 @@ function loadNative() {
 
   const user32 = koffi.load('user32.dll');
   const gdi32 = koffi.load('gdi32.dll');
+  const kernel32 = koffi.load('kernel32.dll');
 
   koffi.alias('HANDLE', 'void *');
   koffi.alias('HWND', 'HANDLE');
@@ -105,6 +107,11 @@ function loadNative() {
     DeleteDC: gdi32.func('bool __stdcall DeleteDC(HANDLE dc)'),
     BitBlt: gdi32.func('bool __stdcall BitBlt(HANDLE dst, int x, int y, int w, int h, HANDLE src, int sx, int sy, uint32_t rop)'),
     GetDIBits: gdi32.func('int __stdcall GetDIBits(HANDLE dc, HANDLE bmp, uint32_t start, uint32_t lines, void *bits, _Inout_ BITMAPINFOHEADER *bmi, uint32_t usage)'),
+    PrintWindow: user32.func('bool __stdcall PrintWindow(HWND hwnd, HANDLE dc, uint32_t flags)'),
+    GetWindowDC: user32.func('HANDLE __stdcall GetWindowDC(HWND hwnd)'),
+    OpenProcess: kernel32.func('HANDLE __stdcall OpenProcess(uint32_t access, bool inherit, uint32_t pid)'),
+    QueryFullProcessImageNameW: kernel32.func('bool __stdcall QueryFullProcessImageNameW(HANDLE proc, uint32_t flags, _Out_ uint16_t *buf, _Inout_ uint32_t *size)'),
+    CloseHandle: kernel32.func('bool __stdcall CloseHandle(HANDLE handle)'),
     structs: { POINT, RECT, INPUT, BITMAPINFOHEADER },
   };
   try {
@@ -134,6 +141,10 @@ const KEYEVENTF_KEYUP = 0x0002;
 const KEYEVENTF_UNICODE = 0x0004;
 const MAX_COORD = 65535;
 const SW_RESTORE = 9;
+const MOUSEEVENTF_HWHEEL = 0x01000;
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
+const PW_RENDERFULLCONTENT = 0x00000002;
+const MAX_CAPTURE_PIXELS = 40_000_000;
 
 /** Behaviour defaults; the host may override them through cordis.patch.yml config. */
 const DEFAULTS = {
@@ -142,18 +153,35 @@ const DEFAULTS = {
   moveSteps: 16,
   keyDelayMs: [12, 34],
   clickSettleMs: [60, 140],
+  zoomFactor: 2,
+  zoomMaxPixels: 24_000_000,
+  maxWaitMs: 10_000,
+  allowLaunch: true,
 };
 const CFG = { ...DEFAULTS };
 
 const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
 const between = ([min, max]) => min + Math.random() * Math.max(0, max - min);
 
+/**
+ * Raw `tools.register()` does not validate arguments the way `defineTool` does,
+ * so every coordinate has to be checked here — otherwise a missing number turns
+ * into a NaN deep inside Buffer.alloc instead of a message the model can act on.
+ */
+function requireNumber(value, name) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new Error(`${name} must be a finite number (received ${JSON.stringify(value)})`);
+  return n;
+}
+
 /** Clamp a pointer target into the virtual screen so a bad coordinate cannot fly off. */
 function clampPoint(A, x, y) {
   const screen = virtualScreen(A);
+  const px = Math.round(requireNumber(x, 'x'));
+  const py = Math.round(requireNumber(y, 'y'));
   return {
-    x: Math.min(Math.max(Math.round(x), screen.x), screen.x + Math.max(0, screen.width - 1)),
-    y: Math.min(Math.max(Math.round(y), screen.y), screen.y + Math.max(0, screen.height - 1)),
+    x: Math.min(Math.max(px, screen.x), screen.x + Math.max(0, screen.width - 1)),
+    y: Math.min(Math.max(py, screen.y), screen.y + Math.max(0, screen.height - 1)),
   };
 }
 
@@ -213,30 +241,37 @@ function toAbsolute(A, x, y) {
   };
 }
 
-/** Grab the whole virtual screen as raw BGRA rows. */
-function captureScreen(A) {
-  const screen = virtualScreen(A);
-  const width = Math.max(1, screen.width);
-  const height = Math.max(1, screen.height);
+/** Pull BGRA rows out of a selected bitmap. */
+function readBits(A, dc, bmp, width, height) {
+  if (width * height > MAX_CAPTURE_PIXELS) throw new Error(`capture too large: ${width}x${height}`);
+  const bmi = {
+    biSize: A.koffi.sizeof(A.structs.BITMAPINFOHEADER),
+    biWidth: width, biHeight: -height, biPlanes: 1, biBitCount: 32,
+    biCompression: 0, biSizeImage: 0, biXPelsPerMeter: 0, biYPelsPerMeter: 0,
+    biClrUsed: 0, biClrImportant: 0,
+  };
+  const buffer = Buffer.alloc(width * height * 4);
+  const lines = A.GetDIBits(dc, bmp, 0, height, buffer, bmi, 0);
+  if (lines !== height) throw new Error(`GetDIBits returned ${lines}/${height} lines`);
+  return { width, height, data: buffer };
+}
+
+/** BitBlt a screen rectangle (virtual-screen coordinates) into a fresh memory bitmap. */
+function captureRect(A, sx, sy, width, height) {
+  const left = Math.round(requireNumber(sx, 'x'));
+  const top = Math.round(requireNumber(sy, 'y'));
+  const w = Math.max(1, Math.round(requireNumber(width, 'width')));
+  const h = Math.max(1, Math.round(requireNumber(height, 'height')));
   const srcDc = A.GetDC(null);
   if (!srcDc) throw new Error('GetDC returned null');
   const memDc = A.CreateCompatibleDC(srcDc);
-  const bmp = A.CreateCompatibleBitmap(srcDc, width, height);
+  const bmp = A.CreateCompatibleBitmap(srcDc, w, h);
   const old = A.SelectObject(memDc, bmp);
   try {
-    if (!A.BitBlt(memDc, 0, 0, width, height, srcDc, screen.x, screen.y, SRCCOPY | CAPTUREBLT)) {
+    if (!A.BitBlt(memDc, 0, 0, w, h, srcDc, left, top, SRCCOPY | CAPTUREBLT)) {
       throw new Error('BitBlt failed');
     }
-    const bmi = {
-      biSize: A.koffi.sizeof(A.structs.BITMAPINFOHEADER),
-      biWidth: width, biHeight: -height, biPlanes: 1, biBitCount: 32,
-      biCompression: 0, biSizeImage: 0, biXPelsPerMeter: 0, biYPelsPerMeter: 0,
-      biClrUsed: 0, biClrImportant: 0,
-    };
-    const buffer = Buffer.alloc(width * height * 4);
-    const lines = A.GetDIBits(memDc, bmp, 0, height, buffer, bmi, 0);
-    if (lines !== height) throw new Error(`GetDIBits returned ${lines}/${height} lines`);
-    return { width, height, data: buffer };
+    return readBits(A, memDc, bmp, w, h);
   } finally {
     A.SelectObject(memDc, old);
     A.DeleteObject(bmp);
@@ -245,6 +280,74 @@ function captureScreen(A) {
   }
 }
 
+/** Grab the whole virtual screen as raw BGRA rows. */
+function captureScreen(A) {
+  const screen = virtualScreen(A);
+  return captureRect(A, screen.x, screen.y, screen.width, screen.height);
+}
+
+/**
+ * Capture one window. PrintWindow asks the window to render itself into our DC
+ * (so occluded windows still come out right); when the window refuses, fall back
+ * to blitting its on-screen rectangle.
+ */
+function captureWindow(A, hwnd) {
+  const rect = { left: 0, top: 0, right: 0, bottom: 0 };
+  if (!A.GetWindowRect(hwnd, rect)) throw new Error(`GetWindowRect failed for handle ${hwnd}`);
+  const width = Math.max(1, rect.right - rect.left);
+  const height = Math.max(1, rect.bottom - rect.top);
+  const bounds = { x: rect.left, y: rect.top, width, height };
+  if (width * height > MAX_CAPTURE_PIXELS) throw new Error(`window too large to capture: ${width}x${height}`);
+  const winDc = A.GetWindowDC(hwnd);
+  if (!winDc) throw new Error(`GetWindowDC returned null for handle ${hwnd}`);
+  const memDc = A.CreateCompatibleDC(winDc);
+  const bmp = A.CreateCompatibleBitmap(winDc, width, height);
+  const old = A.SelectObject(memDc, bmp);
+  try {
+    const printed = A.PrintWindow(hwnd, memDc, PW_RENDERFULLCONTENT);
+    if (!printed) {
+      const screenDc = A.GetDC(null);
+      if (!screenDc) throw new Error('GetDC returned null');
+      try {
+        if (!A.BitBlt(memDc, 0, 0, width, height, screenDc, bounds.x, bounds.y, SRCCOPY | CAPTUREBLT)) {
+          throw new Error('window capture failed (PrintWindow and BitBlt both refused)');
+        }
+      } finally {
+        A.ReleaseDC(null, screenDc);
+      }
+    }
+    return { ...readBits(A, memDc, bmp, width, height), bounds, printed: Boolean(printed) };
+  } finally {
+    A.SelectObject(memDc, old);
+    A.DeleteObject(bmp);
+    A.DeleteDC(memDc);
+    A.ReleaseDC(hwnd, winDc);
+  }
+}
+
+/** Nearest-neighbour upscale: crisp pixels, which is what reading small UI text needs. */
+function scaleBgra({ width, height, data }, factor) {
+  const scale = Math.max(1, Math.floor(factor));
+  if (scale === 1) return { width, height, data };
+  const ow = width * scale;
+  const oh = height * scale;
+  if (ow * oh > MAX_CAPTURE_PIXELS) throw new Error(`zoomed image too large: ${ow}x${oh}`);
+  const out = Buffer.alloc(ow * oh * 4);
+  for (let y = 0; y < oh; y += 1) {
+    const rowBase = Math.min(height - 1, Math.floor(y / scale)) * width;
+    const target = y * ow;
+    for (let x = 0; x < ow; x += 1) {
+      const s = (rowBase + Math.min(width - 1, Math.floor(x / scale))) * 4;
+      const t = (target + x) * 4;
+      out[t] = data[s];
+      out[t + 1] = data[s + 1];
+      out[t + 2] = data[s + 2];
+      out[t + 3] = data[s + 3];
+    }
+  }
+  return { width: ow, height: oh, data: out };
+}
+
 const CRC_TABLE = (() => {
   const table = new Uint32Array(256);
   for (let n = 0; n < 256; n += 1) {
@@ -439,25 +542,30 @@ function clickMouse(A, button = 'left', double = false) {
   }
 }
 
-/** Scroll the wheel; positive is up. */
-function scrollWheel(A, amount) {
-  const delta = Math.round(Number(amount) || 0);
+/** Scroll the wheel; positive is up (or right on the horizontal axis). */
+function scrollWheel(A, amount, axis = 'vertical') {
+  const delta = Math.round(requireNumber(amount, 'amount'));
   if (!delta) return;
-  sendInput(A, mouseInput({ data: delta, flags: MOUSEEVENTF_WHEEL }));
+  const flag = String(axis).toLowerCase() === 'horizontal' ? MOUSEEVENTF_HWHEEL : MOUSEEVENTF_WHEEL;
+  sendInput(A, mouseInput({ data: delta, flags: flag }));
 }
 
-/** Screen capture to a PNG on disk, keeping only the newest screenshots. */
-function screenshot(A, directory) {
+/** Encode one frame to PNG on disk, then prune old captures. */
+function savePng(frame, directory, prefix = 'screen') {
   const target = directory || SCREEN_DIR;
   mkdirSync(target, { recursive: true });
-  const frame = captureScreen(A);
   const png = encodePng(frame);
-  const path = join(target, `screen-${Date.now()}.png`);
+  const path = join(target, `${prefix}-${Date.now()}.png`);
   writeFileSync(path, png);
   pruneScreens(target);
   return { path, width: frame.width, height: frame.height, bytes: png.length };
 }
 
+/** Screen capture to a PNG on disk, keeping only the newest screenshots. */
+function screenshot(A, directory) {
+  return savePng(captureScreen(A), directory);
+}
+
 /** Retention is best effort: a locked or unreadable file must not fail the capture. */
 function pruneScreens(directory) {
   const keep = Number(CFG.keepScreenshots);
@@ -485,6 +593,84 @@ function cursorPosition(A) {
   return { x: point.x, y: point.y };
 }
 
+/** Executable file name behind a process id, or '' when it cannot be read. */
+function exeName(A, pid) {
+  if (!pid) return '';
+  const handle = A.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid);
+  if (!handle) return '';
+  try {
+    const size = [512];
+    const buffer = Buffer.alloc(512 * 2);
+    if (!A.QueryFullProcessImageNameW(handle, 0, buffer, size)) return '';
+    const full = buffer.toString('utf16le', 0, Math.max(0, size[0]) * 2);
+    return full.split(/[\\/]/).pop() || full;
+  } finally {
+    A.CloseHandle(handle);
+  }
+}
+
+/**
+ * Press, travel and release like a hand: the button stays down for the whole
+ * path so drag targets that watch hover state still see it.
+ */
+async function dragMouse(A, fromX, fromY, toX, toY, humanize) {
+  const start = clampPoint(A, fromX, fromY);
+  const end = clampPoint(A, toX, toY);
+  await moveMouseHuman(A, start.x, start.y, humanize);
+  if (humanize) await sleep(between([40, 90]));
+  sendInput(A, mouseInput({ flags: MOUSEEVENTF_LEFTDOWN }));
+  try {
+    if (humanize) {
+      const steps = Math.max(6, Math.min(CFG.moveSteps * 2, Math.round(Math.hypot(end.x - start.x, end.y - start.y) / 35)));
+      for (let i = 1; i <= steps; i += 1) {
+        const t = i / steps;
+        const eased = t * t * (3 - 2 * t);
+        moveMouse(A, start.x + (end.x - start.x) * eased, start.y + (end.y - start.y) * eased);
+        await sleep(8 + Math.random() * 10);
+      }
+    }
+    moveMouse(A, end.x, end.y);
+    if (humanize) await sleep(between([50, 110]));
+  } finally {
+    sendInput(A, mouseInput({ flags: MOUSEEVENTF_LEFTUP }));
+  }
+  return { from: start, to: end };
+}
+
+/** Sleep, and optionally poll until a window whose title contains `title` exists. */
+async function waitFor(A, { ms, title, timeoutMs }) {
+  const budget = Math.max(0, Math.min(timeoutMs === undefined ? CFG.maxWaitMs : requireNumber(timeoutMs, 'timeoutMs'), CFG.maxWaitMs));
+  const started = Date.now();
+  const sleepBudget = Math.min(ms === undefined ? 0 : Math.max(0, requireNumber(ms, 'ms')), budget);
+  if (sleepBudget > 0) await sleep(sleepBudget);
+  if (!title) return { waitedMs: Date.now() - started, matched: false, timedOut: false };
+  const needle = String(title).toLowerCase();
+  while (Date.now() - started < budget) {
+    if (listWindows(A).some((w) => w.title.toLowerCase().includes(needle))) {
+      return { waitedMs: Date.now() - started, matched: true, timedOut: false };
+    }
+    await sleep(150);
+  }
+  return { waitedMs: Date.now() - started, matched: false, timedOut: true };
+}
+
+/** Resolve an executable name or path without ever going through a shell. */
+function resolveExe(name) {
+  const raw = String(name || '').trim();
+  if (!raw) throw new Error('empty executable name');
+  if (/[\\/]/.test(raw)) {
+    if (!existsSync(raw)) throw new Error(`executable not found: ${raw}`);
+    return raw;
+  }
+  const exe = raw.toLowerCase().endsWith('.exe') ? raw : `${raw}.exe`;
+  const dirs = (process.env.PATH || '').split(';').filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = join(dir, exe);
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`executable not found on PATH: ${raw} (pass an absolute path instead)`);
+}
+
 /**
  * JSON-Schema helpers for raw `tools.register()` definitions. The host registry
  * requires every tool to carry `output { schema, render }` and a lossless-JSON
@@ -501,6 +687,35 @@ const num = (description) => ({ type: 'number', description });
 const bool = (description) => ({ type: 'boolean', description });
 const text = (value) => [{ type: 'text', text: String(value) }];
 
+/** Reusable output-schema fragments so every object node declares its fields. */
+const point = (description) => ({
+  type: 'object',
+  description,
+  properties: { x: num('X in virtual-screen pixels.'), y: num('Y in virtual-screen pixels.') },
+});
+const rect = (description) => ({
+  type: 'object',
+  description,
+  properties: {
+    x: num('Left in virtual-screen pixels.'),
+    y: num('Top in virtual-screen pixels.'),
+    width: num('Width in pixels.'),
+    height: num('Height in pixels.'),
+  },
+});
+const windowItem = (description) => ({
+  type: 'object',
+  description,
+  properties: {
+    handle: { type: 'integer', description: 'Window handle; pass it to cua_focus_window.' },
+    title: str('Window title.'),
+    pid: { type: 'integer', description: 'Owner process id.' },
+    active: bool('Is the foreground window.'),
+    minimized: bool('Is minimized.'),
+    bounds: rect('Window rect on the virtual screen.'),
+  },
+});
+
 const TOOL_DECLS = [
   {
     name: 'cua_screenshot',
@@ -519,6 +734,7 @@ const TOOL_DECLS = [
       }),
       render: (_args, v) => text(`Screenshot saved: ${v.path} (${v.width}x${v.height}, ${v.bytes} bytes). Read this file to view it.`),
     },
+    readOnly: true,
   },
   {
     name: 'cua_mouse_move',
@@ -571,12 +787,13 @@ const TOOL_DECLS = [
   },
   {
     name: 'cua_scroll',
-    description: 'Turn the real mouse wheel at the pointer position; positive scrolls up.',
+    description: 'Turn the real mouse wheel at the pointer position; positive scrolls up (or right on the horizontal axis).',
     parameters: obj({
       amount: num('Wheel delta (120 per notch).'),
+      axis: { type: 'string', enum: ['vertical', 'horizontal'], description: 'Scroll axis; defaults to vertical.' },
     }, ['amount']),
     run: (A, args) => {
-      scrollWheel(A, args.amount);
+      scrollWheel(A, args.amount, args.axis);
       return { ok: true };
     },
     out: {
@@ -623,13 +840,14 @@ const TOOL_DECLS = [
     run: (A) => ({ windows: listWindows(A) }),
     out: {
       schema: obj({
-        windows: { type: 'array', items: { type: 'object' }, description: 'Visible top-level windows.' },
+        windows: { type: 'array', items: windowItem('One visible window.'), description: 'Visible top-level windows.' },
       }),
       render: (_args, v) => text(
         `Found ${v.windows.length} window(s):\n` + v.windows.map((w) =>
           `#${w.handle}${w.active ? ' [active]' : ''}${w.minimized ? ' [minimized]' : ''} "${w.title}" pid=${w.pid} ${w.bounds.width}x${w.bounds.height} @ (${w.bounds.x},${w.bounds.y})`
         ).join('\n')),
     },
+    readOnly: true,
   },
   {
     name: 'cua_focus_window',
@@ -638,7 +856,7 @@ const TOOL_DECLS = [
       handle: num('Window handle from cua_windows.'),
     }, ['handle']),
     run: (A, args) => {
-      const hwnd = A.koffi.address(args.handle);
+      const hwnd = A.koffi.address(requireNumber(args.handle, 'handle'));
       A.ShowWindow(hwnd, SW_RESTORE);
       A.SetForegroundWindow(hwnd);
       A.BringWindowToTop(hwnd);
@@ -658,10 +876,183 @@ const TOOL_DECLS = [
       schema: obj({
         x: num('Pointer X.'),
         y: num('Pointer Y.'),
-        screen: { type: 'object', description: 'Virtual-screen geometry.' },
+        screen: rect('Virtual-screen geometry.'),
       }),
       render: (_args, v) => text(`Cursor at (${v.x}, ${v.y}); virtual screen: ${JSON.stringify(v.screen)}.`),
     },
+    readOnly: true,
+  },
+  {
+    name: 'cua_zoom',
+    description:
+      'Capture a screen region and upscale it so small text, icons and menu items become readable. Coordinates are virtual-screen pixels.',
+    parameters: obj({
+      x: num('Region left in virtual-screen pixels.'),
+      y: num('Region top in virtual-screen pixels.'),
+      width: num('Region width in pixels.'),
+      height: num('Region height in pixels.'),
+      factor: num('Integer upscale factor (default 2, max 4).'),
+      directory: str('Optional output directory for the PNG.'),
+    }, ['x', 'y', 'width', 'height']),
+    run: (A, args) => {
+      const screen = virtualScreen(A);
+      const x = Math.max(screen.x, Math.round(args.x));
+      const y = Math.max(screen.y, Math.round(args.y));
+      const right = Math.min(screen.x + screen.width, Math.round(args.x + args.width));
+      const bottom = Math.min(screen.y + screen.height, Math.round(args.y + args.height));
+      const w = right - x;
+      const h = bottom - y;
+      if (w <= 0 || h <= 0) throw new Error('zoom region falls outside the virtual screen');
+      let factor = Math.max(1, Math.min(4, Math.floor(Number(args.factor) || CFG.zoomFactor)));
+      while (factor > 1 && w * factor * h * factor > CFG.zoomMaxPixels) factor -= 1;
+      const scaled = scaleBgra(captureRect(A, x, y, w, h), factor);
+      const saved = savePng(scaled, args.directory, 'zoom');
+      return { ...saved, factor, source: { x, y, width: w, height: h } };
+    },
+    out: {
+      schema: obj({
+        path: str('Absolute path of the written PNG.'),
+        width: { type: 'integer', description: 'Saved width in pixels.' },
+        height: { type: 'integer', description: 'Saved height in pixels.' },
+        bytes: { type: 'integer', description: 'PNG size in bytes.' },
+        factor: { type: 'integer', description: 'Upscale factor actually used.' },
+        source: rect('Captured region in virtual-screen pixels.'),
+      }),
+      render: (_args, v) => text(
+        `Zoom saved: ${v.path} — ${v.source.width}x${v.source.height} at (${v.source.x},${v.source.y}) scaled x${v.factor} to ${v.width}x${v.height}.`),
+    },
+    readOnly: true,
+  },
+  {
+    name: 'cua_screenshot_window',
+    description:
+      'Capture one window by handle. Uses PrintWindow so occluded windows still render correctly, with a screen blit fallback.',
+    parameters: obj({
+      handle: num('Window handle from cua_windows.'),
+      directory: str('Optional output directory for the PNG.'),
+    }, ['handle']),
+    run: (A, args) => {
+      const hwnd = A.koffi.address(requireNumber(args.handle, 'handle'));
+      const frame = captureWindow(A, hwnd);
+      const saved = savePng(frame, args.directory, 'window');
+      return { ...saved, bounds: frame.bounds, printed: frame.printed };
+    },
+    out: {
+      schema: obj({
+        path: str('Absolute path of the written PNG.'),
+        width: { type: 'integer', description: 'Image width in pixels.' },
+        height: { type: 'integer', description: 'Image height in pixels.' },
+        bytes: { type: 'integer', description: 'PNG size in bytes.' },
+        printed: bool('True when PrintWindow rendered it; false means screen fallback.'),
+        bounds: rect('Window rect on the virtual screen.'),
+      }),
+      render: (_args, v) => text(
+        `Window captured (${v.printed ? 'PrintWindow' : 'screen fallback'}): ${v.path} — ${v.width}x${v.height} at (${v.bounds.x},${v.bounds.y}).`),
+    },
+    readOnly: true,
+  },
+  {
+    name: 'cua_drag',
+    description:
+      'Drag with the real left button held down: press at fromX/fromY, travel, release at toX/toY. Use it for sliders, selections, window moves and drag-and-drop.',
+    parameters: obj({
+      fromX: num('Press X in virtual-screen pixels.'),
+      fromY: num('Press Y in virtual-screen pixels.'),
+      toX: num('Release X in virtual-screen pixels.'),
+      toY: num('Release Y in virtual-screen pixels.'),
+    }, ['fromX', 'fromY', 'toX', 'toY']),
+    run: async (A, args) => {
+      const moved = await dragMouse(A, args.fromX, args.fromY, args.toX, args.toY, CFG.humanize);
+      return { ok: true, ...moved };
+    },
+    out: {
+      schema: obj({
+        ok: bool('Always true.'),
+        from: point('Actual press point after clamping.'),
+        to: point('Actual release point after clamping.'),
+      }),
+      render: (_args, v) => text(`Dragged (${v.from.x}, ${v.from.y}) -> (${v.to.x}, ${v.to.y}).`),
+    },
+  },
+  {
+    name: 'cua_wait',
+    description:
+      'Wait for the desktop to settle: sleep for a number of milliseconds and/or poll until a window whose title contains the given text exists.',
+    parameters: obj({
+      ms: num('Milliseconds to sleep first (default 0).'),
+      title: str('Optional window-title substring to wait for, case-insensitive.'),
+      timeoutMs: num('Upper bound for the wait; capped by the plugin config.'),
+    }),
+    run: async (A, args) => waitFor(A, args),
+    out: {
+      schema: obj({
+        waitedMs: { type: 'integer', description: 'Actual time spent waiting.' },
+        matched: bool('True when the title appeared.'),
+        timedOut: bool('True when the title never appeared in time.'),
+      }),
+      render: (_args, v) => text(
+        v.matched ? `Window appeared after ${v.waitedMs} ms.`
+          : v.timedOut ? `Timed out after ${v.waitedMs} ms waiting for the window.`
+            : `Waited ${v.waitedMs} ms.`),
+    },
+    readOnly: true,
+    timeoutMs: 15_000,
+  },
+  {
+    name: 'cua_app_list',
+    description: 'List visible top-level windows with their process executable name, so you can tell apps apart and pick a launch target.',
+    parameters: obj({}),
+    run: (A) => ({ apps: listWindows(A).map((w) => ({ ...w, process: exeName(A, w.pid) })) }),
+    out: {
+      schema: obj({
+        apps: {
+          type: 'array',
+          items: {
+            type: 'object',
+            description: 'One window with its process executable.',
+            properties: {
+              handle: { type: 'integer', description: 'Window handle.' },
+              title: str('Window title.'),
+              pid: { type: 'integer', description: 'Owner process id.' },
+              process: str('Process executable name, e.g. notepad.exe.'),
+              active: bool('Is the foreground window.'),
+              minimized: bool('Is minimized.'),
+              bounds: rect('Window rect on the virtual screen.'),
+            },
+          },
+          description: 'Windows with process names.',
+        },
+      }),
+      render: (_args, v) => text(
+        `${v.apps.length} app window(s):\n` + v.apps.map((a) =>
+          `#${a.handle} ${a.process || '?'} (pid ${a.pid})${a.active ? ' [active]' : ''}${a.minimized ? ' [minimized]' : ''} "${a.title}"`).join('\n')),
+    },
+    readOnly: true,
+  },
+  {
+    name: 'cua_app_launch',
+    description:
+      'Launch an application by executable name (resolved on PATH) or absolute path. Spawns directly without a shell, so no quoting games.',
+    parameters: obj({
+      exe: str('Executable name such as "notepad" / "calc", or an absolute .exe path.'),
+      args: { type: 'array', items: { type: 'string' }, description: 'Command-line arguments.' },
+    }, ['exe']),
+    run: (A, args) => {
+      if (CFG.allowLaunch !== true) throw new Error('cua_app_launch is disabled by config (allowLaunch: false)');
+      const exe = resolveExe(args.exe);
+      const argv = Array.isArray(args.args) ? args.args.map(String) : [];
+      const child = spawn(exe, argv, { detached: true, stdio: 'ignore', windowsHide: false });
+      child.unref();
+      return { ok: true, exe, pid: child.pid ?? 0 };
+    },
+    out: {
+      schema: obj({
+        ok: bool('Always true.'),
+        exe: str('Resolved executable path.'),
+        pid: { type: 'integer', description: 'Process id of the launched app.' },
+      }),
+      render: (_args, v) => text(`Launched ${v.exe} (pid ${v.pid}).`),
+    },
   },
 ];
 
@@ -675,9 +1066,12 @@ export const inject = ['tools'];
  * Config knobs (all optional, from this bundle's cordis.patch.yml):
  * - `humanize` (default true): move the pointer along a smoothstep path and
  *   type/click at a human cadence instead of teleporting instantly.
- * - `keepScreenshots` (default 30): newest screenshots kept per directory.
+ * - `keepScreenshots` (default 30): newest captures kept per directory.
  * - `moveSteps` (default 16), `keyDelayMs` ([12, 34]), `clickSettleMs` ([60, 140]):
  *   fine-tuning for the humanized cadence.
+ * - `zoomFactor` (default 2), `zoomMaxPixels` (default 24e6): `cua_zoom` limits.
+ * - `maxWaitMs` (default 10000): ceiling for `cua_wait`.
+ * - `allowLaunch` (default true): set false to disable `cua_app_launch`.
  */
 export function apply(ctx, config = {}) {
   for (const key of Object.keys(DEFAULTS)) {
@@ -689,6 +1083,9 @@ export function apply(ctx, config = {}) {
       description: decl.description,
       parameters: decl.parameters,
       output: decl.out,
+      presentCall: (args) => ({ card: 'generic', title: decl.name, kind: 'other', rawInput: args ?? {} }),
+      ...decl.readOnly === true ? { isConcurrencySafe: () => true } : {},
+      ...decl.timeoutMs !== undefined ? { timeoutMs: decl.timeoutMs } : {},
       async execute(args = {}) {
         return decl.run(loadNative(), args ?? {});
       },

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "dsh-win-cua",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Windows computer-use for DSH: real mouse and keyboard input through Win32 SendInput, screen capture through GDI BitBlt, window control. No external driver.",
   "type": "module",
   "main": "index.js",
   "license": "MIT",
+  "author": "WJPGKZ",
+  "homepage": "https://github.com/WJPGKZ/dsh-win-cua#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WJPGKZ/dsh-win-cua.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WJPGKZ/dsh-win-cua/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -32,4 +44,4 @@
       "node": ">=20"
     }
   }
-}
+}