agent_wires_mcp

agent_wires_mcp 0.1.7 — Windows startup fix (#15); pairs with probe 0…

Adds the action overlay narration layer (pairs with agent_wires_probe 0.1.7). Tool count grows 24 → 25.

• New set_action_overlay(enabled) tool toggles the probe's on-screen overlay — the ripples/highlights/flashes drawn where the agent taps, types, points, and looks. It is for a human watching the device and never appears in screenshot/snapshot. On by default.
• label_element now flashes a point-at highlight on the named element (via the probe) so a watcher sees what was labelled.
• recommendedProbeVersion tracks agent_wires_probe 0.1.7.

Boot reliability fix.

Fail fast when flutter run dies during boot

• boot_app no longer hangs for the full timeout when the build fails. FlutterRunner.start awaited the VM-service URI (up to 10 min) but never watched the flutter process itself. If flutter run --machine spawned, printed progress ("Running Xcode build..."), then exited without emitting a recognised failure event — a codesign/build failure, no matching device, or flutter resolving to the wrong SDK (e.g. an fvm-managed Flutter not on the spawned PATH) — the boot wedged on the timeout while app_status showed a frozen progress line and no flutter/xcodebuild process was even alive. start now also watches exitCode and fails the boot immediately when flutter exits early, attaching a tail of flutter's stderr and the likely causes so the agent gets an actionable error in seconds instead of a multi-minute hang.

Docs-only release. No code changes — refreshes the README to match the 0.1.3 tool surface and behaviour so the pub.dev page is accurate.

• Removes the -d device pin from the MCP config examples (it contradicted the "don't pin at registration" guidance and is the phone-vs-simulator stall trap); the agent picks a device at session time via list_devices + boot_app.
• Corrects the tool count to 24.
• Documents that screenshot returns {path, …} by default (base64 via return_base64: true).
• recommendedProbeVersion tracks agent_wires_probe 0.1.6.

Connection- and lifecycle-hardening from a real LLM-agent driving session (physical iPhone, then simulator) where a dropped VM-service connection cascaded into multi-minute hangs and leaked processes. No tool additions; app_status gains probe_version / probe_version_warning / paused_at_start fields, and hot_reload / hot_restart failures gain recoverable + hint.

Fail-fast instead of hanging on a dead connection

• Per-call timeout + connection-lost latch. When the device VM-service connection dropped (Service connection disposed, JSON-RPC -32603), every ext.qa.* call used to block on the dead socket until cancelled — boot_app ran 601s, get_logs 633s, even stop_app 219s. VmClient now bounds each call and latches a lost-connection state the instant the socket closes, a call returns disposed, or a call times out; subsequent calls and isProbeAlive fail immediately with a clear "reattach or reboot" error. A dead connection is distinguished from a stale isolate, so it no longer triggers a rebind that would re-hang.
• Teardown never blocks on the VM-service. stop_app bounds VM-service disposal so it always tears down the OS process, even when the connection is already dead.

Reap the whole flutter process tree

• No more orphaned flutter run / DDS / devicectl / iproxy. stop_app (and server exit on SIGINT/SIGTERM) now snapshots the descendant process tree before killing flutter — children reparent to launchd the moment flutter dies — then SIGTERM→SIGKILL the lot. Stops the per-cycle leak that left multiple servers/runs contending for the same device and VM-service.

Resume a paused-at-start launch

• Frozen --start-stopped apps now run. A physical iPhone launched via devicectl … --start-stopped boots with main() paused; nothing resumed it, so the app sat frozen while app_status read ready. Attach now resumes any paused-at-start isolate before locating the QA isolate (a paused isolate hasn't registered the probe yet). When a resume can't be confirmed, app_status reports paused_at_start: true instead of a misleading healthy status.

Hot reload/restart — recover from DevFS wedges

• Retry-then-explain on DevFS synchronization failed. hot_reload / hot_restart retry once (the failure is often transient); if it still fails, the result carries recoverable: false and a hint to run stop_app + boot_app, instead of a bare success: false.

Smaller robustness wins

• boot_app(device_id) switches devices without a deadlock. A device switch on a running session force-stops it (process-level) instead of rejecting with "call stop_app first" — which used to deadlock when the VM-service was already dead.
• Probe/server version-skew warning. The probe reports its version over ext.qa.ping; app_status surfaces probe_version and warns when it differs from the version this server pairs with (0.1.5).
• get_logs can't blow the client token budget. Oversized message / error / stack fields are truncated (default 4000 chars each, with a dropped-char marker) so a single ~110k-char Flutter stack no longer overruns the MCP client limit. Pagination is preserved.

Hot-restart robustness from real LLM-agent driving sessions. No tool additions; app_status gains a probe_attached field.

Self-healing isolate binding

• Recovers from hot restart automatically. A hot restart collects the QA isolate and starts a new one. The client used to keep calling the dead isolate id, so every ext.qa.* call failed with [Sentinel kind: Collected] for the rest of the session and never recovered. callExtension now re-resolves the live ext.qa.* isolate and retries once on a stale-isolate error, so a single tool call recovers transparently.
• app_status reports probe_attached. Distinct from state, which only tracks the flutter run process: after a hot restart the process stays up (state stays ready) but the probe moves to a fresh isolate. state:"ready" with probe_attached:false now tells the agent the probe is reattaching, instead of looking healthy while every call fails. The check re-resolves and rebinds when the bound isolate has been collected.
• Clearer error when the probe is truly gone. If re-resolution fails (the app exited, or hot-restarted without AgentWiresProbe.install()), the agent gets an actionable message instead of the raw VM-service sentinel string.

Post-launch iteration. Tool count grows 18 → 23 (5 new lifecycle tools). No breaking changes.

New: lifecycle tools

• list_devices — discover what flutter can target (phones, sims, macOS, Chrome). Agent picks per-session
• boot_app — explicit boot with device_id and wait: false (fire-and-forget so the agent can poll progress)
• app_status — query state + latest_progress ("Running Xcode build…", "Installing Pods…") during long boots
• stop_app — tear down to retarget device
• hot_reload — re-inject sources, preserve state + route
• hot_restart — cold restart in lazy mode (attached mode returns a clear error)

Boot: visible instead of black box

• Lazy boot — MCP handshake answers in ms; flutter only starts on first tool call. Fixes Claude Code's 30s connection timeout
• Progress streaming to stderr + app_status.latest_progress
• Fail-fast on app.stop errors and error-level daemon logs (no more 10-min hangs)
• Recovery: lazy sessions can re-boot from exited without restarting the MCP server
• Default boot timeout 5 → 10 min

Perception tools — smaller, more accurate

• snapshot defaults to compact mode (include_unresolved: false)
• screenshot writes PNG to tmpfile, returns {path, width, height, size_bytes} (was 329k chars of inline base64)
• inspect returns descendants + CustomPaint metadata

Sync — diagnose what's keeping the app awake

• wait_for_idle returns structured blocked_by on timeout
• ignore_animations flag

Tool descriptions

• All 23 tools rewritten to disambiguate and teach the canonical agent loop. Most user-visible fix: agents now reach for snapshot first by default.

Full notes: CHANGELOG
pub.dev: https://pub.dev/packages/agent_wires_mcp/versions/0.1.1
Requires: agent_wires_probe ^0.1.3

Initial public release.

• 18 MCP tools across five categories: perception (snapshot, inspect, screenshot), action (tap, long_press, swipe, enter_text, clear_text, scroll, press_back), sync (wait_for_idle, wait_for_route, wait_for_element), observability (get_logs, get_network), and memory (label_element, get_labels, recall).
• agent_wires_mcp run — boots flutter run --machine, auto-discovers the VM service URI, and serves MCP over stdio in one process. Forwards --flavor, -t/--target, --dart-define.
• agent_wires_mcp serve --attach <ws-uri> — attaches to an already- running app.
• agent_wires_mcp review — local human-curation dashboard at localhost:7345 for labelling unresolved widgets. Per-project persistence in .flutter_qa/map.json.
• Snapshot enrichment — merges human labels and source-location proposals (via the analyzer package) before returning to the agent.
• Set-of-Mark mode — screenshot(annotated: true) overlays numbered boxes for vision-augmented agents.
• Requires the target app to have agent_wires_probe installed.