@harusame64/desktop-touch-mcp 1.7.1 → 1.8.0

package/README.ja.md

@@ -197,6 +197,7 @@ DOM を触る `browser_*` ツールは `includeContext:false` で末尾の `acti
 ### ターミナル (2)
 | ツール | 概要 |
 |---|---|
+| `terminal(action='run')` | コマンド送信 → 完了待ち → 出力取得を 1 コールで実行。完了判定は `until`: `quiet` / `pattern` / `exit`（コマンドの**終了**を待ち exit code を返す → [ターミナルの完了判定](#ターミナルの完了判定-until)） |
 | `terminal(action='read')` | Windows Terminal / PowerShell / cmd / WSL のテキストをUIA/OCRで取得。`sinceMarker`差分対応 |
 | `terminal(action='send')` | ターミナルへコマンド送信。clipboard paste既定でIME安全 |
 
@@ -263,6 +264,39 @@ Lease ライフサイクル:
 
 Reactive Perception Graph は desktop-touch の低コストな状況把握レイヤーです。対象の同一性・フォーカス・矩形・準備状態・guard 結果を操作間で維持し、Claude が小さな操作のたびにスクリーンショットで確認し直さなくて済むようにします。
 
+---
+## ターミナルの完了判定 (`until`)
+
+`terminal(action='run')` はコマンド送信 → 完了待ち → 出力取得を 1 コールで行います。「完了」の判定方法は `until` で選びます:
+
+| モード | 待つ対象 | 用途 |
+|---|---|---|
+| `quiet`（既定） | 出力が `quietMs` 静かになるまで | 短い対話コマンド |
+| `pattern` | 出力に現れる文字列/正規表現 | 最終マーカーが分かる長時間コマンド |
+| `exit` | コマンドの**終了そのもの** | 完了や exit code が必要なとき |
+
+> **アンカーの注意 (#384):** 最終行が改行で終わらない出力は、マーカーが次プロンプトに密着して行境界が無くなります（`printf X` → `Xuser@host:~$`）。よって行末アンカー付き `pattern`（`X\s*\n` / `X$`）は**バインド不能**です。**完了検出は `mode:'exit'`**、content マッチは**裸マーカー**（`\n`/`$` を付けない）を使ってください。`mode:'pattern'` には opt-in の `quietMs` settle fallback もあります: `until:{mode:'pattern', pattern, quietMs:1000}` は、pattern 未一致でも出力が指定 ms 安定したら `reason:'quiet'`（`matchedPattern` なし）で完了し、`timeoutMs` までのハングを防ぎます。opt-in（未指定なら pattern を待ち続ける＝silent gap のある長時間コマンドは無影響）。
+
+### `until:{mode:'exit'}` — 本当の完了 + exit code
+
+ヒューリスティックなモードは「センチネルを末尾に付ける」定番（`some-task; echo DONE` を `DONE` で待つ）で誤判定しがちです。センチネルは**エコーされたコマンド行**にも現れ、複数行コマンドではそのエコーと実出力をバッファだけから区別できません。`mode:'exit'` はこれを構造的に解決します — サーバが**表示形と入力形が異なる**完了マーカーをコマンド末尾に注入するため、エコーには決して一致せず（複数行入力でも）、実際のプロセス exit code を返します:
+
+```js
+terminal({
+  action: 'run',
+  windowTitle: 'pwsh',
+  input: 'npm run build',
+  until: { mode: 'exit', shell: 'powershell' },
+})
+// → completion: { reason: 'exited', exitCode: 0, elapsedMs: … }
+//   output: 注入マーカーは除去され、コマンドの実出力のみ
+```
+
+- **`shell` は明示指定推奨**（`'bash'` / `'powershell'`）。`shell:'auto'` はターミナル窓のプロセスから判定しますが、SSH / WSL の**中で**動く shell は見えません（窓はローカルホストのまま）。リモート/ネストしたセッションではリモート側の shell を渡してください（`auto` は警告を出し外側の shell を選ぶ場合があります）。プロセスを真に特定できない窓（Windows Terminal 等）は `ExitModeShellAmbiguous` を返します。
+- **first-class shell:** `bash` と `powershell`。`cmd.exe` は未対応（`ExitModeShellUnsupported`）。
+- **未完の構文で終わる入力は即座に reject**（`ExitModeUnsafeInput`）。閉じていない引用符 / here-doc / `$(…)` / 末尾の `\` または PowerShell バッククォートなどはハングせず弾きます。
+- exit mode は配送を自前制御するため、配送系の `sendOptions`（`method` / `preferClipboard` / `pressEnter` / `chunkSize` / `pasteKey`）は `InvalidArgs` で reject します（focus 系オプションは利用可）。
+
 ---
 ## ブラウザ CDP 自動化
 

package/README.md

@@ -159,7 +159,7 @@ For a local checkout, register the built server directly:
 ### 🛠️ Utilities & Workflow
 | Tool | Description |
 |---|---|
-| `terminal` | Unified command execution: `run` (send + wait + read), `read` (OCR/UIA), and `send`. |
+| `terminal` | Unified command execution: `run` (send + wait + read), `read` (OCR/UIA), and `send`. `run` completion modes: `quiet`, `pattern`, and `exit` (waits for the command to finish + returns its exit code — see [Terminal command completion](#terminal-command-completion-until)). |
 | `wait_until` | Efficient server-side polling for window, focus, text, or URL state changes. |
 | `window_dock` / `focus_window` | Window management: `pin` (always-on-top), `unpin`, `dock` (corner snap), and `focus`. |
 | `workspace_launch` | Launch apps and auto-detect new HWNDs (supports localized titles). |
@@ -203,6 +203,66 @@ Lease lifecycle:
 
 ---
 
+## Terminal command completion (`until`)
+
+`terminal(action='run')` sends a command, waits for it to complete, and reads the
+output in one call. How it decides "complete" is controlled by `until`:
+
+| Mode | Waits for | Best for |
+|---|---|---|
+| `quiet` (default) | output to fall silent for `quietMs` | short interactive commands |
+| `pattern` | a string/regex you expect in the output | long commands with a known final marker |
+| `exit` | the command to actually **finish** | when you need completion or the exit code |
+
+> **Anchoring caveat (#384):** a command whose final line has no trailing newline
+> glues the marker to the next prompt with no line boundary (`printf X` →
+> `Xuser@host:~$`), so an end-anchored `pattern` (`X\s*\n` / `X$`) can never bind.
+> For *completion* use `mode:'exit'`; for *content* matching use a bare marker
+> (no `\n`/`$`). `mode:'pattern'` also accepts an optional `quietMs` settle
+> fallback: `until:{mode:'pattern', pattern, quietMs:1000}` completes with
+> `reason:'quiet'` (no `matchedPattern`) once output is stable for that long
+> without a match — instead of hanging until `timeoutMs`. It is opt-in (omit
+> `quietMs` to keep waiting for the pattern; long commands with mid-run silent
+> gaps are unaffected).
+
+### `until:{mode:'exit'}` — real completion + exit code
+
+The heuristic modes can misfire on the common "append a sentinel" idiom
+(`some-task; echo DONE` matched by `DONE`): the sentinel also shows up in the
+**echoed command line**, and for multi-line commands there is no reliable way to
+tell that echo apart from real output. `mode:'exit'` removes the guesswork — the
+server appends its own completion marker whose *printed* form differs from its
+*typed* form, so it never matches the echoed command (even for multi-line input),
+and it returns the real process exit code:
+
+```js
+terminal({
+  action: 'run',
+  windowTitle: 'pwsh',
+  input: 'npm run build',
+  until: { mode: 'exit', shell: 'powershell' },
+})
+// → completion: { reason: 'exited', exitCode: 0, elapsedMs: … }
+//   output: just the command's real output (the injected marker is stripped)
+```
+
+- **Pass `shell` explicitly** (`'bash'` or `'powershell'`). `shell:'auto'` detects
+  the shell from the terminal window, but it cannot see a shell running *inside*
+  SSH or WSL — the window still looks like its local host — so for remote/nested
+  sessions pass the remote side's shell (`auto` otherwise warns and may pick the
+  outer shell). A window whose process is genuinely unidentifiable (e.g. Windows
+  Terminal) returns `ExitModeShellAmbiguous`.
+- **First-class shells:** `bash` and `powershell`. `cmd.exe` is not supported yet
+  (`ExitModeShellUnsupported`).
+- **Unsafe input is rejected up front** (`ExitModeUnsafeInput`) rather than
+  hanging: a command ending mid-construct (unterminated quote, here-doc, `$(…)`,
+  a trailing `\` or PowerShell backtick).
+- Exit mode controls its own delivery, so delivery-shaping `sendOptions`
+  (`method` / `preferClipboard` / `pressEnter` / `chunkSize` / `pasteKey`) are
+  rejected with `InvalidArgs`; focus options remain accepted.
+
+---
+
 ## Browser CDP automation
 
 For web automation, connect Chrome or Edge with the remote debugging port enabled — no Selenium or Playwright needed.

package/bin/launcher.js

@@ -18,15 +18,15 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
-const PACKAGE_VERSION = "1.7.1";
+const PACKAGE_VERSION = "1.8.0";
 const RELEASE_TAG = `v${PACKAGE_VERSION}`;
 const REPO_API_URL = `https://api.github.com/repos/Harusame64/desktop-touch-mcp/releases/tags/${RELEASE_TAG}`;
 const ASSET_NAME = "desktop-touch-mcp-windows.zip";
 const RELEASE_METADATA_FILE = ".desktop-touch-release.json";
 const RELEASE_MANIFEST = {
-  tagName: "v1.7.1",
+  tagName: "v1.8.0",
   assetName: ASSET_NAME,
-  sha256: "180d047bfe5b4e7014721b782ac30db1512cc18c440d276909e39cd27e56e07c",
+  sha256: "a4b330dba135e74707d082cbe1859ae9176b497373610165037f8ab59de35f8e",
 };
 const CACHE_ROOT = process.env.DESKTOP_TOUCH_MCP_HOME
   ? path.resolve(process.env.DESKTOP_TOUCH_MCP_HOME)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harusame64/desktop-touch-mcp",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "mcpName": "io.github.Harusame64/desktop-touch-mcp",
   "description": "Let Claude, Cursor, or any MCP client see and operate your Windows 10/11 desktop. 28 tools for screenshots, UI Automation, Chrome CDP, keyboard/mouse, terminal, with semantic discover-then-act targeting and per-action perception guards that avoid wrong-window typing and stale-coordinate clicks.",
   "keywords": [
@@ -89,6 +89,7 @@
     "test:watch": "vitest",
     "generate:stub-catalog": "node scripts/generate-stub-tool-catalog.mjs",
     "check:stub-catalog": "node scripts/generate-stub-tool-catalog.mjs && git diff --exit-code src/stub-tool-catalog.ts",
+    "check:failwith-fixtures": "node scripts/extract-failwith-shape-fixtures.mjs && git diff --exit-code tests/fixtures/failwith-callsite-shapes.json",
     "check:napi-safe": "node scripts/check-napi-safe.mjs",
     "check:native-types": "node scripts/check-native-types.mjs",
     "check:no-koffi": "node scripts/check-no-koffi.mjs",