dsh-win-cua 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 Wesley Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party notices
+
+koffi (https://www.npmjs.com/package/koffi) is loaded at runtime from the host
+DSH profile; it is not bundled with this package. koffi is distributed under
+the MIT license by its own authors.
+
+The Win32 and GDI function signatures and the per-monitor DPI awareness setup
+follow the publicly documented Windows API. The approach of driving those APIs
+through koffi was learned from Coopanion's Cortico desktop-pet extension
+(https://github.com/Pal-AI-Lab/Coopanion), which is not copied here; this file
+is an independent implementation of the same public API surface.

package/NOTICE.md

@@ -0,0 +1,42 @@
+# Third-party notices
+
+`dsh-win32-cua` loads and drives Windows system libraries. It ships no
+third-party code of its own beyond what is listed here.
+
+## koffi
+
+- Package: [`koffi`](https://www.npmjs.com/package/koffi)
+- License: MIT
+- Use: resolved at runtime from the DSH profile's `node_modules`, never bundled.
+- Why: koffi is the FFI layer that calls `user32.dll` and `gdi32.dll` from Node.
+
+## Windows API
+
+`SendInput`, `SetCursorPos`, `GetCursorPos`, `GetSystemMetrics`, `EnumWindows`,
+`GetWindowTextW`, `GetWindowRect`, `GetWindowThreadProcessId`,
+`GetForegroundWindow`, `SetForegroundWindow`, `ShowWindow`, `BringWindowToTop`,
+`GetDC`, `ReleaseDC`, `SetProcessDpiAwarenessContext` (user32) and `BitBlt`,
+`CreateCompatibleDC`, `CreateCompatibleBitmap`, `SelectObject`, `DeleteObject`,
+`DeleteDC`, `GetDIBits` (gdi32) are documented public Windows APIs. The
+signatures in `index.js` follow the Microsoft documentation; no proprietary
+header or binary is redistributed.
+
+## Coopanion (inspiration, not code)
+
+- Project: [Pal-AI-Lab/Coopanion](https://github.com/Pal-AI-Lab/Coopanion)
+- Relationship: the **approach** of driving Win32 through koffi, capturing the
+  screen with `BitBlt | CAPTUREBLT`, and declaring per-monitor DPI awareness was
+  learned by reading Coopanion's Cortico `desktop-pet` extension
+  (`src/cua/engine/win32.ts`).
+- What was **not** taken: no source file, no type declaration, no string, no
+  struct layout and no code path is copied from that project. `index.js` here is
+  an independent implementation written against the public Win32 documentation,
+  with its own PNG encoder, its own key table and its own tool surface.
+- Coopanion is used as a reference for what is possible, not as a dependency.
+
+## DSH
+
+- Project: [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+- The `dsh.bundle` / `cordis.patch.yml` bundle format and the `ctx.tools`
+  registration contract follow the DSH plugin documentation shipped with the
+  DSH agent preset skills.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# dsh-win32-cua
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Windows computer-use for DeepSeek Harness: **real** mouse and keyboard input plus screen
+capture, with no external driver.
+
+## How it works
+
+| Capability | Win32 API |
+|---|---|
+| Mouse move, click, wheel | `user32!SendInput` (INPUT_MOUSE) |
+| Keyboard taps and shortcuts | `user32!SendInput` (INPUT_KEYBOARD) |
+| Type literal text (incl. CJK) | `SendInput` with `KEYEVENTF_UNICODE` |
+| Screen capture | `gdi32!BitBlt` + `CAPTUREBLT` (layered windows included) |
+| Window list / focus | `user32!EnumWindows`, `ShowWindow`, `SetForegroundWindow` |
+| DPI | `SetProcessDpiAwarenessContext(-4)` — per-monitor v2 |
+
+FFI is [koffi](https://www.npmjs.com/package/koffi). Coordinates are physical pixels of
+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
+- `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
+
+Every tool declares `output { schema, render }` — the DSH tool registry rejects raw
+definitions without it, so keep that shape when adding tools.
+
+## Config
+
+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 |
+| `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 |
+
+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.
+
+## Install
+
+```powershell
+dsh plugin --profile <profile> add <this directory>
+```
+
+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.

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+- insert:
+    - id: win32-cua
+      name: 'dsh-win-cua'
+      config:
+        humanize: true
+        keepScreenshots: 30
+

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="4" y="8" width="56" height="40" rx="5" fill="#1f2a3a" stroke="#4da3ff" stroke-width="2.5"/>
+  <path d="M10 18h14M10 26h22M10 34h10" stroke="#4da3ff" stroke-width="2.5" stroke-linecap="round"/>
+  <path d="M38 22l12 7-5 1.5 3.2 6.2-3.4 1.6-3-6.1-3.6 3.4z" fill="#7ee0a1" stroke="#e8f4ff" stroke-width="1.4" stroke-linejoin="round"/>
+  <rect x="22" y="50" width="20" height="5" rx="2.5" fill="#4da3ff"/>
+</svg>

package/index.js

@@ -0,0 +1,698 @@
+/**
+ * @local/dsh-win32-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
+ * list through `EnumWindows`. The FFI layer is koffi, the same approach Coopanion's
+ * desktop-pet uses; no external driver process is involved.
+ *
+ * Coordinates are physical pixels of the virtual screen (primary top-left is 0,0),
+ * because the process declares itself per-monitor DPI aware before anything else.
+ */
+import { deflateSync } from 'node:zlib';
+import { createRequire } from 'node:module';
+import { mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const SCREEN_DIR = join(tmpdir(), 'dsh-cua-screens');
+
+/**
+ * Resolve koffi from wherever this profile keeps its packages. A bundle installed by
+ * link lives outside the profile, so a plain `import 'koffi'` cannot see it; the host
+ * exposes DSH_PROFILE_DIR for exactly that case. The fallbacks cover running from the
+ * profile itself and a checkout next to it.
+ */
+function loadKoffi() {
+  const candidates = [
+    process.env.DSH_PROFILE_DIR && join(process.env.DSH_PROFILE_DIR, 'node_modules', 'koffi'),
+    join(process.cwd(), 'node_modules', 'koffi'),
+    join(import.meta.dirname, 'node_modules', 'koffi'),
+  ].filter(Boolean);
+  const errors = [];
+  for (const candidate of candidates) {
+    try {
+      return createRequire(join(candidate, 'noop.cjs'))(candidate);
+    } catch (error) {
+      errors.push(`${candidate}: ${error.message}`);
+    }
+  }
+  throw new Error(`cannot load koffi (tried ${candidates.length} locations): ${errors.join(' | ')}`);
+}
+
+let native = null;
+
+/** Load Win32 through koffi once. */
+function loadNative() {
+  if (native) return native;
+  if (process.platform !== 'win32') throw new Error('dsh-win32-cua only works on Windows');
+  const koffi = loadKoffi();
+
+  const user32 = koffi.load('user32.dll');
+  const gdi32 = koffi.load('gdi32.dll');
+
+  koffi.alias('HANDLE', 'void *');
+  koffi.alias('HWND', 'HANDLE');
+
+  const POINT = koffi.struct('POINT', { x: 'long', y: 'long' });
+  const RECT = koffi.struct('RECT', { left: 'long', top: 'long', right: 'long', bottom: 'long' });
+  const MOUSEINPUT = koffi.struct('MOUSEINPUT', {
+    dx: 'long', dy: 'long', mouseData: 'uint32_t', dwFlags: 'uint32_t',
+    time: 'uint32_t', dwExtraInfo: 'uintptr_t',
+  });
+  const KEYBDINPUT = koffi.struct('KEYBDINPUT', {
+    wVk: 'uint16_t', wScan: 'uint16_t', dwFlags: 'uint32_t',
+    time: 'uint32_t', dwExtraInfo: 'uintptr_t',
+  });
+  const HARDWAREINPUT = koffi.struct('HARDWAREINPUT', {
+    uMsg: 'uint32_t', wParamL: 'uint16_t', wParamH: 'uint16_t',
+  });
+  const INPUT = koffi.struct('INPUT', {
+    type: 'uint32_t',
+    u: koffi.union({ mi: MOUSEINPUT, ki: KEYBDINPUT, hi: HARDWAREINPUT }),
+  });
+  const BITMAPINFOHEADER = koffi.struct('BITMAPINFOHEADER', {
+    biSize: 'uint32_t', biWidth: 'int32_t', biHeight: 'int32_t',
+    biPlanes: 'uint16_t', biBitCount: 'uint16_t', biCompression: 'uint32_t',
+    biSizeImage: 'uint32_t', biXPelsPerMeter: 'int32_t', biYPelsPerMeter: 'int32_t',
+    biClrUsed: 'uint32_t', biClrImportant: 'uint32_t',
+  });
+  const EnumWindowsProc = koffi.proto('bool __stdcall EnumWindowsProc(HWND hwnd, intptr_t lParam)');
+
+  const api = {
+    koffi,
+    SetProcessDpiAwarenessContext: user32.func('bool __stdcall SetProcessDpiAwarenessContext(intptr_t value)'),
+    GetSystemMetrics: user32.func('int __stdcall GetSystemMetrics(int index)'),
+    SetCursorPos: user32.func('bool __stdcall SetCursorPos(int x, int y)'),
+    GetCursorPos: user32.func('bool __stdcall GetCursorPos(_Out_ POINT *p)'),
+    SendInput: user32.func('uint32_t __stdcall SendInput(uint32_t count, INPUT *inputs, int size)'),
+    GetDC: user32.func('HANDLE __stdcall GetDC(HWND hwnd)'),
+    ReleaseDC: user32.func('int __stdcall ReleaseDC(HWND hwnd, HANDLE dc)'),
+    EnumWindows: user32.func('bool __stdcall EnumWindows(EnumWindowsProc *cb, intptr_t lParam)'),
+    IsWindowVisible: user32.func('bool __stdcall IsWindowVisible(HWND hwnd)'),
+    IsIconic: user32.func('bool __stdcall IsIconic(HWND hwnd)'),
+    GetWindowTextW: user32.func('int __stdcall GetWindowTextW(HWND hwnd, _Out_ uint16_t *buf, int max)'),
+    GetWindowRect: user32.func('bool __stdcall GetWindowRect(HWND hwnd, _Out_ RECT *rect)'),
+    GetWindowThreadProcessId: user32.func('uint32_t __stdcall GetWindowThreadProcessId(HWND hwnd, _Out_ uint32_t *pid)'),
+    GetForegroundWindow: user32.func('HWND __stdcall GetForegroundWindow()'),
+    SetForegroundWindow: user32.func('bool __stdcall SetForegroundWindow(HWND hwnd)'),
+    ShowWindow: user32.func('bool __stdcall ShowWindow(HWND hwnd, int cmd)'),
+    BringWindowToTop: user32.func('bool __stdcall BringWindowToTop(HWND hwnd)'),
+    CreateCompatibleDC: gdi32.func('HANDLE __stdcall CreateCompatibleDC(HANDLE dc)'),
+    CreateCompatibleBitmap: gdi32.func('HANDLE __stdcall CreateCompatibleBitmap(HANDLE dc, int w, int h)'),
+    SelectObject: gdi32.func('HANDLE __stdcall SelectObject(HANDLE dc, HANDLE obj)'),
+    DeleteObject: gdi32.func('bool __stdcall DeleteObject(HANDLE obj)'),
+    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)'),
+    structs: { POINT, RECT, INPUT, BITMAPINFOHEADER },
+  };
+  try {
+    // -4 = DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2
+    api.SetProcessDpiAwarenessContext(-4);
+  } catch {
+    /* older Windows: best effort */
+  }
+  native = api;
+  return api;
+}
+
+const SRCCOPY = 0x00cc0020;
+const CAPTUREBLT = 0x40000000;
+const INPUT_MOUSE = 0;
+const INPUT_KEYBOARD = 1;
+const MOUSEEVENTF_MOVE = 0x0001;
+const MOUSEEVENTF_LEFTDOWN = 0x0002;
+const MOUSEEVENTF_LEFTUP = 0x0004;
+const MOUSEEVENTF_RIGHTDOWN = 0x0008;
+const MOUSEEVENTF_RIGHTUP = 0x0010;
+const MOUSEEVENTF_MIDDLEDOWN = 0x0020;
+const MOUSEEVENTF_MIDDLEUP = 0x0040;
+const MOUSEEVENTF_WHEEL = 0x0800;
+const MOUSEEVENTF_ABSOLUTE = 0x8000;
+const KEYEVENTF_KEYUP = 0x0002;
+const KEYEVENTF_UNICODE = 0x0004;
+const MAX_COORD = 65535;
+const SW_RESTORE = 9;
+
+/** Behaviour defaults; the host may override them through cordis.patch.yml config. */
+const DEFAULTS = {
+  humanize: true,
+  keepScreenshots: 30,
+  moveSteps: 16,
+  keyDelayMs: [12, 34],
+  clickSettleMs: [60, 140],
+};
+const CFG = { ...DEFAULTS };
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const between = ([min, max]) => min + Math.random() * Math.max(0, max - min);
+
+/** Clamp a pointer target into the virtual screen so a bad coordinate cannot fly off. */
+function clampPoint(A, x, y) {
+  const screen = virtualScreen(A);
+  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)),
+  };
+}
+
+/**
+ * UTF-16 code units one KEYEVENTF_UNICODE scan needs. Astral code points
+ * (emoji, CJK extensions) travel as a surrogate pair; sending the raw code
+ * point would truncate to 16 bits and type the wrong glyph.
+ */
+function unicodeUnits(code) {
+  if (code <= 0xffff) return [code];
+  const rest = code - 0x10000;
+  return [0xd800 + ((rest >> 10) & 0x3ff), 0xdc00 + (rest & 0x3ff)];
+}
+
+/** Build a mouse INPUT record. */
+function mouseInput({ dx = 0, dy = 0, data = 0, flags = 0 }) {
+  return {
+    type: INPUT_MOUSE,
+    u: { mi: { dx, dy, mouseData: data, dwFlags: flags, time: 0, dwExtraInfo: 0 } },
+  };
+}
+
+/** Build a keyboard INPUT record. */
+function keyInput(vk, flags, scan = 0) {
+  return {
+    type: INPUT_KEYBOARD,
+    u: { ki: { wVk: vk, wScan: scan, dwFlags: flags, time: 0, dwExtraInfo: 0 } },
+  };
+}
+
+/** Send INPUT records; koffi converts a plain array of structs in place. */
+function sendInputs(A, records) {
+  const sent = A.SendInput(records.length, records, A.koffi.sizeof(A.structs.INPUT));
+  if (sent !== records.length) throw new Error(`SendInput accepted ${sent}/${records.length} records`);
+}
+
+function sendInput(A, record) {
+  sendInputs(A, [record]);
+}
+
+/** Virtual-screen origin and size in physical pixels. */
+function virtualScreen(A) {
+  return {
+    x: A.GetSystemMetrics(76),
+    y: A.GetSystemMetrics(77),
+    width: A.GetSystemMetrics(78),
+    height: A.GetSystemMetrics(79),
+  };
+}
+
+/** Screen pixels to the 0..65535 absolute space. */
+function toAbsolute(A, x, y) {
+  const screen = virtualScreen(A);
+  return {
+    ax: Math.round(((x - screen.x) * MAX_COORD) / Math.max(1, screen.width - 1)),
+    ay: Math.round(((y - screen.y) * MAX_COORD) / Math.max(1, screen.height - 1)),
+  };
+}
+
+/** 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);
+  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 old = A.SelectObject(memDc, bmp);
+  try {
+    if (!A.BitBlt(memDc, 0, 0, width, height, srcDc, screen.x, screen.y, 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 };
+  } finally {
+    A.SelectObject(memDc, old);
+    A.DeleteObject(bmp);
+    A.DeleteDC(memDc);
+    A.ReleaseDC(null, srcDc);
+  }
+}
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1) c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, payload) {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(payload.length, 0);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), payload]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([length, body, crc]);
+}
+
+/** Encode BGRA rows as an RGBA PNG without an image library. */
+function encodePng({ width, height, data }) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    const target = y * (stride + 1);
+    raw[target] = 0;
+    const source = y * stride;
+    for (let x = 0; x < width; x += 1) {
+      const s = source + x * 4;
+      const t = target + 1 + x * 4;
+      raw[t] = data[s + 2];
+      raw[t + 1] = data[s + 1];
+      raw[t + 2] = data[s];
+      raw[t + 3] = 255;
+    }
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', header),
+    pngChunk('IDAT', deflateSync(raw, { level: 6 })),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** Read a wide window title. */
+function windowTitle(A, hwnd) {
+  const buffer = Buffer.alloc(512 * 2);
+  const length = A.GetWindowTextW(hwnd, buffer, 512);
+  return length > 0 ? buffer.toString('utf16le', 0, length * 2) : '';
+}
+
+/** Every visible top-level window with a title. */
+function listWindows(A) {
+  const windows = [];
+  const foreground = Number(A.koffi.address(A.GetForegroundWindow()));
+  const proc = A.koffi.register((hwnd) => {
+    if (!A.IsWindowVisible(hwnd)) return true;
+    const title = windowTitle(A, hwnd);
+    if (!title) return true;
+    const rect = { left: 0, top: 0, right: 0, bottom: 0 };
+    A.GetWindowRect(hwnd, rect);
+    const pid = [0];
+    A.GetWindowThreadProcessId(hwnd, pid);
+    const handle = Number(A.koffi.address(hwnd));
+    windows.push({
+      handle,
+      title,
+      pid: pid[0],
+      minimized: Boolean(A.IsIconic(hwnd)),
+      active: handle === foreground,
+      bounds: {
+        x: rect.left,
+        y: rect.top,
+        width: rect.right - rect.left,
+        height: rect.bottom - rect.top,
+      },
+    });
+    return true;
+  }, A.koffi.pointer('EnumWindowsProc'));
+  try {
+    A.EnumWindows(proc, 0);
+  } finally {
+    A.koffi.unregister(proc);
+  }
+  return windows;
+}
+
+/** Virtual-key names a model is likely to use. */
+const VIRTUAL_KEYS = {
+  enter: 0x0d, return: 0x0d, esc: 0x1b, escape: 0x1b, tab: 0x09, space: 0x20,
+  backspace: 0x08, delete: 0x2e, del: 0x2e, insert: 0x2d, home: 0x24, end: 0x23,
+  pageup: 0x21, pagedown: 0x22, up: 0x26, down: 0x28, left: 0x25, right: 0x27,
+  shift: 0x10, ctrl: 0x11, control: 0x11, alt: 0x12, win: 0x5b, meta: 0x5b,
+  capslock: 0x14, numlock: 0x90, scrolllock: 0x91, printscreen: 0x2c, pause: 0x13,
+  f1: 0x70, f2: 0x71, f3: 0x72, f4: 0x73, f5: 0x74, f6: 0x75,
+  f7: 0x76, f8: 0x77, f9: 0x78, f10: 0x79, f11: 0x7a, f12: 0x7b,
+};
+for (let i = 0; i < 26; i += 1) VIRTUAL_KEYS[String.fromCharCode(97 + i)] = 0x41 + i;
+for (let i = 0; i <= 9; i += 1) VIRTUAL_KEYS[String(i)] = 0x30 + i;
+
+function resolveKey(name) {
+  const key = String(name || '').trim().toLowerCase();
+  if (!key) throw new Error('empty key name');
+  const code = VIRTUAL_KEYS[key];
+  if (code !== undefined) return code;
+  throw new Error(`unknown key: ${name}`);
+}
+
+/** Tap one key, optionally with modifiers held. */
+function tapKey(A, key, modifiers = []) {
+  const mods = modifiers.map(resolveKey);
+  for (const code of mods) sendInput(A, keyInput(code, 0));
+  const code = resolveKey(key);
+  sendInput(A, keyInput(code, 0));
+  sendInput(A, keyInput(code, KEYEVENTF_KEYUP));
+  for (const mod of mods.reverse()) sendInput(A, keyInput(mod, KEYEVENTF_KEYUP));
+}
+
+/** Type literal text through unicode keyboard events at a human cadence. */
+async function typeText(A, text, humanize) {
+  for (const char of String(text)) {
+    const code = char.codePointAt(0);
+    if (code === undefined) continue;
+    if (code === 10 || code === 13) {
+      sendInput(A, keyInput(0x0d, 0));
+      sendInput(A, keyInput(0x0d, KEYEVENTF_KEYUP));
+      if (humanize) await sleep(between(CFG.keyDelayMs));
+      continue;
+    }
+    if (code < 0x20) continue;
+    for (const unit of unicodeUnits(code)) {
+      sendInput(A, keyInput(0, KEYEVENTF_UNICODE, unit));
+      sendInput(A, keyInput(0, KEYEVENTF_UNICODE | KEYEVENTF_KEYUP, unit));
+    }
+    if (humanize) await sleep(between(CFG.keyDelayMs));
+  }
+}
+
+/** Move the pointer to a screen pixel. */
+function moveMouse(A, x, y) {
+  const { ax, ay } = toAbsolute(A, Math.round(x), Math.round(y));
+  sendInput(A, mouseInput({ dx: ax, dy: ay, flags: MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE }));
+}
+
+/**
+ * Move the pointer like a hand does: a smoothstep path in a few steps instead of
+ * one teleport, so hover states, tooltips and drag targets behave realistically.
+ * @returns the clamped destination actually used.
+ */
+async function moveMouseHuman(A, x, y, humanize) {
+  const target = clampPoint(A, x, y);
+  if (!humanize) {
+    moveMouse(A, target.x, target.y);
+    return target;
+  }
+  const from = cursorPosition(A);
+  const distance = Math.hypot(target.x - from.x, target.y - from.y);
+  const steps = Math.max(4, Math.min(CFG.moveSteps, Math.round(distance / 55)));
+  for (let i = 1; i <= steps; i += 1) {
+    const t = i / steps;
+    const eased = t * t * (3 - 2 * t);
+    moveMouse(A, from.x + (target.x - from.x) * eased, from.y + (target.y - from.y) * eased);
+    await sleep(6 + Math.random() * 9);
+  }
+  moveMouse(A, target.x, target.y);
+  return target;
+}
+
+/** Press and release a mouse button. */
+function clickMouse(A, button = 'left', double = false) {
+  const table = {
+    left: [MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP],
+    right: [MOUSEEVENTF_RIGHTDOWN, MOUSEEVENTF_RIGHTUP],
+    middle: [MOUSEEVENTF_MIDDLEDOWN, MOUSEEVENTF_MIDDLEUP],
+  };
+  const pair = table[String(button).toLowerCase()];
+  if (!pair) throw new Error(`unknown mouse button: ${button}`);
+  for (let i = 0; i < (double ? 2 : 1); i += 1) {
+    sendInput(A, mouseInput({ flags: pair[0] }));
+    sendInput(A, mouseInput({ flags: pair[1] }));
+  }
+}
+
+/** Scroll the wheel; positive is up. */
+function scrollWheel(A, amount) {
+  const delta = Math.round(Number(amount) || 0);
+  if (!delta) return;
+  sendInput(A, mouseInput({ data: delta, flags: MOUSEEVENTF_WHEEL }));
+}
+
+/** Screen capture to a PNG on disk, keeping only the newest screenshots. */
+function screenshot(A, directory) {
+  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`);
+  writeFileSync(path, png);
+  pruneScreens(target);
+  return { path, width: frame.width, height: frame.height, bytes: png.length };
+}
+
+/** Retention is best effort: a locked or unreadable file must not fail the capture. */
+function pruneScreens(directory) {
+  const keep = Number(CFG.keepScreenshots);
+  if (!Number.isFinite(keep) || keep <= 0) return;
+  try {
+    const names = readdirSync(directory)
+      .filter((name) => name.startsWith('screen-') && name.endsWith('.png'))
+      .sort();
+    for (const name of names.slice(0, Math.max(0, names.length - keep))) {
+      try {
+        unlinkSync(join(directory, name));
+      } catch {
+        /* keep going */
+      }
+    }
+  } catch {
+    /* retention is best effort */
+  }
+}
+
+/** Read the pointer position. */
+function cursorPosition(A) {
+  const point = { x: 0, y: 0 };
+  A.GetCursorPos(point);
+  return { x: point.x, y: point.y };
+}
+
+/**
+ * JSON-Schema helpers for raw `tools.register()` definitions. The host registry
+ * requires every tool to carry `output { schema, render }` and a lossless-JSON
+ * object-root `parameters` schema; annotations (`description`, `title`) are the
+ * only extra keywords allowed on a node.
+ */
+const obj = (properties = {}, required = []) => ({
+  type: 'object',
+  properties,
+  ...(required.length ? { required } : {}),
+});
+const str = (description) => ({ type: 'string', description });
+const num = (description) => ({ type: 'number', description });
+const bool = (description) => ({ type: 'boolean', description });
+const text = (value) => [{ type: 'text', text: String(value) }];
+
+const TOOL_DECLS = [
+  {
+    name: 'cua_screenshot',
+    description:
+      'Capture the whole virtual screen to a PNG file and return its path and pixel size. Look before clicking so you act on what is really on screen.',
+    parameters: obj({
+      directory: str('Optional absolute directory for the PNG; defaults to a temp folder.'),
+    }),
+    run: (A, args) => screenshot(A, args.directory),
+    out: {
+      schema: obj({
+        path: str('Absolute path of the written PNG.'),
+        width: { type: 'integer', description: 'Capture width in pixels.' },
+        height: { type: 'integer', description: 'Capture height in pixels.' },
+        bytes: { type: 'integer', description: 'PNG size in bytes.' },
+      }),
+      render: (_args, v) => text(`Screenshot saved: ${v.path} (${v.width}x${v.height}, ${v.bytes} bytes). Read this file to view it.`),
+    },
+  },
+  {
+    name: 'cua_mouse_move',
+    description: 'Move the real mouse pointer to a screen pixel (virtual-screen coordinates).',
+    parameters: obj({
+      x: num('Screen X in pixels.'),
+      y: num('Screen Y in pixels.'),
+    }, ['x', 'y']),
+    run: async (A, args) => {
+      const point = await moveMouseHuman(A, args.x, args.y, CFG.humanize);
+      return { ok: true, ...point };
+    },
+    out: {
+      schema: obj({ ok: bool('Always true.'), x: num('Pointer X.'), y: num('Pointer Y.') }),
+      render: (_args, v) => text(`Pointer moved to (${v.x}, ${v.y}).`),
+    },
+  },
+  {
+    name: 'cua_mouse_click',
+    description:
+      'Click a real mouse button, optionally moving to x/y first. Double clicks repeat the press-release pair.',
+    parameters: obj({
+      x: num('Optional screen X; omit to click where the pointer is.'),
+      y: num('Optional screen Y; omit to click where the pointer is.'),
+      button: { type: 'string', enum: ['left', 'right', 'middle'], description: 'Mouse button; defaults to left.' },
+      double: bool('Double click when true.'),
+    }),
+    run: async (A, args) => {
+      if (typeof args.x === 'number' && typeof args.y === 'number') await moveMouseHuman(A, args.x, args.y, CFG.humanize);
+      if (CFG.humanize) await sleep(between(CFG.clickSettleMs));
+      const double = Boolean(args.double);
+      clickMouse(A, args.button, false);
+      if (double) {
+        // A real double click needs a visible gap; two immediate pairs collapse into one.
+        await sleep(between([50, 90]));
+        clickMouse(A, args.button, false);
+      }
+      return { ok: true, ...cursorPosition(A), button: args.button || 'left', double };
+    },
+    out: {
+      schema: obj({
+        ok: bool('Always true.'),
+        button: str('Button used.'),
+        x: num('Pointer X.'),
+        y: num('Pointer Y.'),
+        double: bool('Whether the click was doubled.'),
+      }),
+      render: (_args, v) => text(`${v.double ? 'Double-clicked' : 'Clicked'} ${v.button} button at (${v.x}, ${v.y}).`),
+    },
+  },
+  {
+    name: 'cua_scroll',
+    description: 'Turn the real mouse wheel at the pointer position; positive scrolls up.',
+    parameters: obj({
+      amount: num('Wheel delta (120 per notch).'),
+    }, ['amount']),
+    run: (A, args) => {
+      scrollWheel(A, args.amount);
+      return { ok: true };
+    },
+    out: {
+      schema: obj({ ok: bool('Always true.') }),
+      render: (_args, v) => text(`Wheel scrolled (${v.ok ? 'sent' : 'failed'}).`),
+    },
+  },
+  {
+    name: 'cua_key',
+    description:
+      'Press a real key with optional modifiers. Key names: enter, esc, tab, space, backspace, delete, arrows, f1-f12, letters, digits. Modifiers: ctrl, shift, alt, win.',
+    parameters: obj({
+      key: str('Key to press, e.g. "enter", "a", "f5".'),
+      modifiers: { type: 'array', items: { type: 'string' }, description: 'Modifiers to hold, e.g. ["ctrl"].' },
+    }, ['key']),
+    run: (A, args) => {
+      tapKey(A, args.key, args.modifiers || []);
+      return { ok: true };
+    },
+    out: {
+      schema: obj({ ok: bool('Always true.') }),
+      render: (_args, v) => text(`Key press sent (${v.ok ? 'ok' : 'failed'}).`),
+    },
+  },
+  {
+    name: 'cua_type',
+    description: 'Type literal text into the focused window through real unicode key events.',
+    parameters: obj({
+      text: str('Text to type.'),
+    }, ['text']),
+    run: async (A, args) => {
+      await typeText(A, args.text, CFG.humanize);
+      return { ok: true, chars: [...String(args.text)].length };
+    },
+    out: {
+      schema: obj({ ok: bool('Always true.'), chars: { type: 'integer', description: 'Characters typed.' } }),
+      render: (_args, v) => text(`Typed ${v.chars} characters.`),
+    },
+  },
+  {
+    name: 'cua_windows',
+    description: 'List visible top-level windows: handle, title, process id, bounds, active and minimized flags.',
+    parameters: obj({}),
+    run: (A) => ({ windows: listWindows(A) }),
+    out: {
+      schema: obj({
+        windows: { type: 'array', items: { type: 'object' }, 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')),
+    },
+  },
+  {
+    name: 'cua_focus_window',
+    description: 'Restore a minimized window and bring it to the foreground by its handle from cua_windows.',
+    parameters: obj({
+      handle: num('Window handle from cua_windows.'),
+    }, ['handle']),
+    run: (A, args) => {
+      const hwnd = A.koffi.address(args.handle);
+      A.ShowWindow(hwnd, SW_RESTORE);
+      A.SetForegroundWindow(hwnd);
+      A.BringWindowToTop(hwnd);
+      return { ok: true, handle: args.handle };
+    },
+    out: {
+      schema: obj({ ok: bool('Always true.'), handle: num('Focused window handle.') }),
+      render: (_args, v) => text(`Window ${v.handle} brought to the foreground.`),
+    },
+  },
+  {
+    name: 'cua_cursor',
+    description: 'Report the current pointer position and the virtual-screen geometry.',
+    parameters: obj({}),
+    run: (A) => ({ ...cursorPosition(A), screen: virtualScreen(A) }),
+    out: {
+      schema: obj({
+        x: num('Pointer X.'),
+        y: num('Pointer Y.'),
+        screen: { type: 'object', description: 'Virtual-screen geometry.' },
+      }),
+      render: (_args, v) => text(`Cursor at (${v.x}, ${v.y}); virtual screen: ${JSON.stringify(v.screen)}.`),
+    },
+  },
+];
+
+export const name = 'dsh-win-cua';
+
+export const inject = ['tools'];
+
+/**
+ * Register the CUA tools on the host.
+ *
+ * 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.
+ * - `moveSteps` (default 16), `keyDelayMs` ([12, 34]), `clickSettleMs` ([60, 140]):
+ *   fine-tuning for the humanized cadence.
+ */
+export function apply(ctx, config = {}) {
+  for (const key of Object.keys(DEFAULTS)) {
+    if (config[key] !== undefined) CFG[key] = config[key];
+  }
+  for (const decl of TOOL_DECLS) {
+    const tool = {
+      name: decl.name,
+      description: decl.description,
+      parameters: decl.parameters,
+      output: decl.out,
+      async execute(args = {}) {
+        return decl.run(loadNative(), args ?? {});
+      },
+    };
+    ctx.effect(() => ctx.tools.register(tool));
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Win32 Computer Use",
+    "description": "Real mouse and keyboard control plus screen capture on Windows, through Win32 SendInput and GDI BitBlt. No external driver."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Win32 电脑操作",
+    "description": "用 Win32 的 SendInput 和 GDI BitBlt 在 Windows 上真实移动鼠标、点击、敲键盘和截屏，不需要任何外部驱动。"
+  }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "dsh-win-cua",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "computer-use",
+    "win32",
+    "sendinput",
+    "bitblt",
+    "automation",
+    "windows"
+  ],
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    },
+    "compatibility": {
+      "node": ">=20"
+    }
+  }
+}