helmor-debug-operate

# Helmor Debug Operate Use this skill to operate and debug a running Helmor dev build through Tauri MCP with the least possible exploration. It is the visual/runtime counterpart to `helmor-cli`: prefer Tauri MCP for webview UI, screenshots, CSS, accessibility, and IPC tracing; prefer `helmor-cli` for terminal-first data inspection or workspace orchestration. Examples below use bare tool names such as `driver_session`; call the same tool through whatever namespace the runtime exposes. ## References Read these only when needed: - `references/verified-recipes.md` for action-specific recipes that have passed three consecutive Tauri MCP verification attempts. - `references/ui-map.md` for selectors, Settings panels, Inspector/Editor preconditions, and destructive-action boundaries. ## Ground Rules - Treat every action as real user input against the active app. Do not send prompts, close sessions, archive/delete workspaces, stop streams, or mutate settings unless the user asked for that outcome or it is necessary for the verification. - Use the Tauri MCP bridge only for Helmor desktop debugging. Do not switch to Chrome DevTools, Browser, Playwright, or `/agent-browser` unless the user explicitly asks for another surface. - Require a debug Tauri build. The bridge is absent in release builds. If connection fails, ask the user to run `bun run dev` or call `get_setup_instructions` only when bridge setup itself is suspect. - Default to `port: 9223` and `windowId: "main"`. - Re-run `webview_dom_snapshot` after every meaningful UI change. `ref=eN` handles are per-snapshot and expire after DOM changes. - Prefer accessibility snapshots for finding controls, but fall back to structure snapshots and read-only DOM rect inspection when accessibility support is unavailable. - Prefer UI operations for end-to-end validation. Do not use the Tauri MCP tool `ipc_execute_command` for Helmor app commands such as `list_workspace_groups`, `reveal_workspace_in_main_window`, or `debug_list_terminal_buffers`: the current bridge returns `Unsupported Tauri command` because dynamic app-command execution is not implemented there. Use the verified app-command helper in **Call App Commands** instead. - Do not use `webview_execute_js` to dispatch synthetic user events. Use it only for read-only, JSON-serializable inspection when MCP tools cannot answer the question. - Exception: Helmor's composer is a Lexical `contenteditable`, not a native input. If `webview_keyboard type` fails with the current bridge, `document.execCommand("insertText", false, text)` after real MCP focus/click is the last-resort smoke-test input path. Label it as a fallback and verify visible state afterward. - If you start `ipc_monitor`, always stop it before finishing, even if the task fails. - Save screenshots or scratch logs under `.agent-contexts/<task-slug>/` when working inside this repository. - If a Settings dialog appears stuck visible with `data-state="closed"`, press `Cmd+,` to reopen it, then `Escape` to close. Verify `document.querySelectorAll('[role="dialog"]').length === 0` and `main[aria-hidden]` is absent. - If `webview_execute_js` or console log reads start timing out while screenshots and `driver_session status` still work, restart only the MCP driver session (`driver_session stop appIdentifier=9223`, then `driver_session start port=9223`). Do not restart the Helmor dev build unless the bridge cannot reconnect. - If you launch a disposable app with `HELMOR_DATA_DIR` for validation, create both the data dir and its `run/` subdir first. Missing `run/` can make the UI sync socket fail to bind, leaving backend mutations invisible until you force a reveal or restart. - Treat this skill as an operation hint, not an authoritative source of truth. The local UI can drift ahead of these recipes. If a recipe fails three times, stop repeating it mechanically: take a fresh screenshot/snapshot, reason from the visible UI, and inspect the relevant code if needed. - Keep this skill self-improving by proposal, not silent mutation. When you discover a better path, missing pitfall, stale selector, or unverified workaround, record a candidate update under `.agent-contexts/<task-slug>/skill-update-candidates.md` with the scenario, failing attempts, evidence, proposed recipe, and verification status. Ask the user before editing this skill unless the current user request explicitly asks you to update it. ## Connect 1. Check the bridge: ```json driver_session { "action": "status", "port": 9223 } ``` 2. Start only when not connected: ```json driver_session { "action": "start", "port": 9223 } ``` 3. Sanity-check the target: ```json ipc_get_backend_state {} manage_window { "action": "list" } ``` Expect `app.identifier` to be `ai.helmor.desktop`, `app.name` to be `Helmor`, `environment.debug` to be `true`, and a visible `main` window. If multiple apps are connected, pass the returned port or bundle id as `appIdentifier` on later calls. ## Baseline Snapshot Start every UI task with both a visual and semantic read: ```json webview_screenshot { "windowId": "main", "format": "png" } webview_dom_snapshot { "windowId": "main", "type": "accessibility" } ``` If accessibility fails with `aria-api library not loaded`, immediately use: ```json webview_dom_snapshot { "windowId": "main", "type": "structure" } ``` Avoid taking screenshots with `maxWidth` when you need click coordinates. A scaled screenshot changes the coordinate space; direct `webview_interact { "x": ..., "y": ... }` expects the webview's real coordinates from `getBoundingClientRect()` or `manage_window info`. Use this stable mental map: - Shell: `Application shell`, `Workspace sidebar`, `Workspace panel`, `Workspace viewport`. - Sidebar buttons: `Workspace location`, `Filter and sort sidebar`, `Add repository`, `New workspace`, `Collapse left sidebar`. - Workspace rows: role `button` with the displayed workspace title. Nested actions include `Archive workspace`, `Confirm archive workspace`, and `Delete permanently`. - Session header: tablist `Sessions`; tabs are named by session title, often `Untitled`; buttons include `New session` and `Session history`. - Session tab actions: `Rename session` and `Close session` appear in the accessibility tree when visible. If not targetable, use the keyboard or the **Call App Commands** helper recipes below. - Hidden session history: `Session history` opens rows with `Restore session` and `Delete session permanently`. - Composer: `Workspace composer`, textbox `Workspace input`, placeholder `Ask to make changes, @mention files, run /commands`. - Composer controls: model selector, `Fast mode`, `Carry room context`, effort dropdown such as `High`, `Plan mode`, `Terminal mode`, `Add context`, `Context usage`, and trailing `Send`, `Stop`, `Steer`, `Request Changes`, or `Implement`. ## Selector Repair And Coordinate Targeting Some bridge versions inject `window.__MCP__` but omit helper functions used by selector-based tools. If `webview_dom_snapshot`, `webview_find_element`, `webview_interact selector=...`, or `webview_keyboard type selector=...` fails with `window.__MCP__.resolveAll is not a function` or `window.__MCP__.resolveRef is not a function`, install this compatibility shim once per page load: ```json webview_execute_js { "windowId": "main", "script": "(() => {\n if (!window.__MCP__) window.__MCP__ = {};\n if (!window.__MCP__.refs) window.__MCP__.refs = new Map();\n if (!window.__MCP__.reverseRefs) window.__MCP__.reverseRefs = new Map();\n const all = (selector, strategy = 'css') => {\n if (!selector) return [];\n if (String(selector).startsWith('ref=')) {\n const el = window.__MCP__.refs.get(String(selector).slice(4));\n return el ? [el] : [];\n }\n if (strategy === 'xpath') {\n const result = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);\n return Array.from({ length: result.snapshotLength }, (_, i) => result.snapshotItem(i)).filter(Boolean);\n }\n if (strategy === 'text') {\n const needle = String(selector).trim();\n return Array.from(document.querySelectorAll('button,[role=\"button\"],[role=\"tab\"],input,textarea,[contenteditable=\"true\"],[role=\"textbox\"],a,[aria-label],[title]')).filter((el) => {\n const text = (el.textContent || '').trim();\n return text === needle || text.includes(needle) || el.getAttribute('aria-label') === needle || el.getAttribute('title') === needle || el.getAttribute('placeholder') === needle;\n });\n }\n return Array.from(document.querySelectorAll(selector));\n };\n window.__MCP__.resolveAll = (selector, strategy = 'css') => all(selector, strategy);\n window.__MCP__.resolveRef = (selector, strategy = 'css') => all(selector, strategy)[0] || null;\n window.__MCP__.countAll = (selector, strategy = 'css') => all(selector, strategy).length;\n return { installed: true, hasResolveAll: typeof window.__MCP__.resolveAll };\n})()" } ``` Even with selector repair, coordinate targeting is often the fastest reliable path: ```json webview_execute_js { "windowId": "main", "script": "(() => Array.from(document.querySelectorAll('button,[role=\"button\"],[role=\"tab\"],[role=\"textbox\"]')).map((el) => { const r = el.getBoundingClientRect(); return { text: (el.textContent || '').trim(), ariaLabel: el.getAttribute('aria-label'), role: el.getAttribute('role'), selected: el.getAttribute('aria-selected'), x: r.x, y: r.y, width: r.width, height: r.height, disabled: !!el.disabled }; }))()" } ``` Click the center of the returned rect: ```json webview_interact { "action": "click", "windowId": "main", "x": 1254, "y": 52 } ``` For Radix dropdown/menu triggers, direct click is sometimes ignored even when the selector resolves. Prefer: ```json webview_interact { "action": "focus", "selector": "BUTTON_OR_TEXT", "strategy": "text", "windowId": "main" } webview_keyboard { "action": "press", "key": "Enter", "windowId": "main" } ``` For model/effort menu triggers, `ArrowDown` was more reliable than `Enter`: ```json webview_keyboard { "action": "press", "key": "ArrowDown", "windowId": "main" } ``` ## Call App Commands The MCP bridge's `ipc_execute_command` tool currently cannot invoke Helmor's ordinary Tauri commands. Use this click-triggered low-level IPC helper whenever you need a deterministic backend command. It was verified against a fresh debug build on port `9224` for repository/workspace setup, `debug_list_terminal_buffers`, `debug_read_terminal_buffer`, and terminal stdin writes. Install the helper once per page load: ```json webview_execute_js { "windowId": "main", "script": "(() => {\n window.__helmorDebugResults = window.__helmorDebugResults || {};\n let btn = document.getElementById('__helmor_debug_ipc_runner');\n if (!btn) {\n btn = document.createElement('button');\n btn.id = '__helmor_debug_ipc_runner';\n btn.textContent = 'ipc runner';\n btn.style.position = 'fixed';\n btn.style.left = '4px';\n btn.style.top = '244px';\n btn.style.zIndex = '2147483647';\n btn.style.width = '120px';\n btn.style.height = '32px';\n document.body.appendChild(btn);\n }\n btn.onclick = () => {\n const request = window.__helmorDebugRequest;\n if (!request) return;\n const id = request.id || `${Date.now()}-${Math.random()}`;\n window.__helmorDebugResults[id] = { pending: true, command: request.command };\n const callback = window.__TAURI_INTERNALS__.transformCallback((value) => {\n window.__helmorDebugResults[id] = { ok: true, command: request.command, value };\n }, true);\n const error = window.__TAURI_INTERNALS__.transformCallback((err) => {\n window.__helmorDebugResults[id] = { ok: false, command: request.command, error: String(err) };\n }, true);\n window.__TAURI_INTERNALS__.ipc({ cmd: request.command, callback, error, payload: request.payload || {} });\n };\n const r = btn.getBoundingClientRect();\n return { installed: true, x: r.x + r.width / 2, y: r.y + r.height / 2 };\n})()" } ``` Run a command by setting `window.__helmorDebugRequest`, clicking the helper button center returned above, then polling the result: ```json webview_execute_js { "windowId": "main", "script": "(() => { window.__helmorDebugRequest = { id: 'list-buffers', command: 'debug_list_terminal_buffers', payload: {} }; return window.__helmorDebugRequest; })()" } webview_interact { "action": "click", "windowId": "main", "x": 64, "y": 260 } webview_execute_js { "windowId": "main", "script": "(() => window.__helmorDebugResults?.['list-buffers'] || null)()" } ``` Important constraints: