Add debug continue and auto-resume on attach

Author: cameroncooke

.smithery/index.cjs

@@ -1,5 +1,20 @@
 # Changelog
 
+## [Unreleased]
+### Added
+- Add Smithery support for packaging/distribution.
+- Add DAP-based debugger backend and simulator debugging toolset (attach, breakpoints, stack, variables, LLDB command).
+- Add session-status MCP resource with session identifiers.
+- Add UI automation guard that blocks UI tools when the debugger is paused.
+
+### Changed
+- Migrate to Zod v4.
+- Improve session default handling (reconcile mutual exclusivity and ignore explicit undefined clears).
+
+### Fixed
+- Update UI automation guard guidance to point at `debug_continue` when paused.
+- Fix tool loading bugs in static tool registration.
+
 ## [1.16.0] - 2025-12-30
 - Remove dynamic tool discovery (`discover_tools`) and `XCODEBUILDMCP_DYNAMIC_TOOLS`. Use `XCODEBUILDMCP_ENABLED_WORKFLOWS` to limit startup tool registration.
 - Add MCP tool annotations to all tools.

CHANGELOG.md

@@ -1,6 +1,6 @@
 # XcodeBuildMCP Tools Reference
 
-XcodeBuildMCP provides 70 tools organized into 13 workflow groups for comprehensive Apple development workflows.
+XcodeBuildMCP provides 71 tools organized into 13 workflow groups for comprehensive Apple development workflows.
 
 ## Workflow Groups
 
@@ -69,11 +69,12 @@ XcodeBuildMCP provides 70 tools organized into 13 workflow groups for comprehens
 - `session_set_defaults` - Set the session defaults needed by many tools. Most tools require one or more session defaults to be set before they can be used. Agents should set all relevant defaults up front in a single call (e.g., project/workspace, scheme, simulator or device ID, useLatestOS) to avoid iterative prompts; only set the keys your workflow needs.
 - `session_show_defaults` - Show current session defaults.
 ### Simulator Debugging (`debugging`)
-**Purpose**: Interactive iOS Simulator debugging tools: attach LLDB, manage breakpoints, inspect stack/variables, and run LLDB commands. (7 tools)
+**Purpose**: Interactive iOS Simulator debugging tools: attach LLDB, manage breakpoints, inspect stack/variables, and run LLDB commands. (8 tools)
 
 - `debug_attach_sim` - Attach LLDB to a running iOS simulator app. Provide bundleId or pid, plus simulator defaults.
 - `debug_breakpoint_add` - Add a breakpoint by file/line or function name for the active debug session.
 - `debug_breakpoint_remove` - Remove a breakpoint by id for the active debug session.
+- `debug_continue` - Resume execution in the active debug session or a specific debugSessionId.
 - `debug_detach` - Detach the current debugger session or a specific debugSessionId.
 - `debug_lldb_command` - Run an arbitrary LLDB command within the active debug session.
 - `debug_stack` - Return a thread backtrace from the active debug session.
@@ -116,9 +117,9 @@ XcodeBuildMCP provides 70 tools organized into 13 workflow groups for comprehens
 
 ## Summary Statistics
 
-- **Total Tools**: 70 canonical tools + 22 re-exports = 92 total
+- **Total Tools**: 71 canonical tools + 22 re-exports = 93 total
 - **Workflow Groups**: 13
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-03*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-04*

docs/TOOLS.md

@@ -0,0 +1,38 @@
+# Investigation: Debugger attaches in stopped state after launch
+
+## Summary
+Reproduced: attaching the debugger leaves the simulator app in a stopped state. UI automation is blocked by the guard because the debugger reports `state=stopped`. The attach flow does not issue any resume/continue, so the process remains paused after attach.
+
+## Symptoms
+- After attaching debugger to Calculator, UI automation taps fail because the app is paused.
+- UI guard blocks with `state=stopped` immediately after attach.
+
+## Investigation Log
+
+### 2025-02-14 - Repro (CalculatorApp on iPhone 17 simulator)
+**Hypothesis:** Attach leaves the process stopped, which triggers the UI automation guard.
+**Findings:** `debug_attach_sim` attached to a running CalculatorApp (DAP backend), then `tap` was blocked with `state=stopped`.
+**Evidence:** `tap` returned "UI automation blocked: app is paused in debugger" with `state=stopped` and the current debug session ID.
+**Conclusion:** Confirmed.
+
+### 2025-02-14 - Code Review (attach flow)
+**Hypothesis:** The attach implementation does not resume the process.
+**Findings:** The attach flow never calls any resume/continue primitive.
+- `debug_attach_sim` creates a session and returns without resuming.
+- DAP backend attach flow (`initialize -> attach -> configurationDone`) has no `continue`.
+- LLDB CLI backend uses `process attach --pid` and never `process continue`.
+- UI automation guard blocks when state is `stopped`.
+**Evidence:** `src/mcp/tools/debugging/debug_attach_sim.ts`, `src/utils/debugger/backends/dap-backend.ts`, `src/utils/debugger/backends/lldb-cli-backend.ts`, `src/utils/debugger/ui-automation-guard.ts`.
+**Conclusion:** Confirmed. Stopped state originates from debugger attach semantics, and the tool never resumes.
+
+## Root Cause
+The debugger attach path halts the target process (standard debugger behavior) and there is no subsequent resume/continue step. This leaves the process in `stopped` state, which causes `guardUiAutomationAgainstStoppedDebugger` to block UI tools like `tap`.
+
+## Recommendations
+1. Add a first-class `debug_continue` tool backed by a backend-level `continue()` API to resume without relying on LLDB command evaluation.
+2. Add an optional `continueOnAttach` (or `stopOnAttach`) parameter to `debug_attach_sim`, with a default suited for UI automation workflows.
+3. Update guard messaging to recommend `debug_continue` (not `debug_lldb_command continue`, which is unreliable on DAP).
+
+## Preventive Measures
+- Document that UI tools require the target process to be running, and that debugger attach may pause execution by default.
+- Add a state check or auto-resume option when attaching in automation contexts.

docs/investigations/issue-debugger-attach-stopped.md

@@ -14,22 +14,24 @@ export const WORKFLOW_LOADERS = {
     const tool_2 = await import('../mcp/tools/debugging/debug_breakpoint_remove.ts').then(
       (m) => m.default,
     );
-    const tool_3 = await import('../mcp/tools/debugging/debug_detach.ts').then((m) => m.default);
-    const tool_4 = await import('../mcp/tools/debugging/debug_lldb_command.ts').then(
+    const tool_3 = await import('../mcp/tools/debugging/debug_continue.ts').then((m) => m.default);
+    const tool_4 = await import('../mcp/tools/debugging/debug_detach.ts').then((m) => m.default);
+    const tool_5 = await import('../mcp/tools/debugging/debug_lldb_command.ts').then(
       (m) => m.default,
     );
-    const tool_5 = await import('../mcp/tools/debugging/debug_stack.ts').then((m) => m.default);
-    const tool_6 = await import('../mcp/tools/debugging/debug_variables.ts').then((m) => m.default);
+    const tool_6 = await import('../mcp/tools/debugging/debug_stack.ts').then((m) => m.default);
+    const tool_7 = await import('../mcp/tools/debugging/debug_variables.ts').then((m) => m.default);
 
     return {
       workflow,
       debug_attach_sim: tool_0,
       debug_breakpoint_add: tool_1,
       debug_breakpoint_remove: tool_2,
-      debug_detach: tool_3,
-      debug_lldb_command: tool_4,
-      debug_stack: tool_5,
-      debug_variables: tool_6,
+      debug_continue: tool_3,
+      debug_detach: tool_4,
+      debug_lldb_command: tool_5,
+      debug_stack: tool_6,
+      debug_variables: tool_7,
     };
   },
   device: async () => {

src/core/generated-plugins.ts

@@ -33,6 +33,11 @@ const baseSchemaObject = z.object({
     .describe("Bundle identifier of the app to attach (e.g., 'com.example.MyApp')"),
   pid: z.number().int().positive().optional().describe('Process ID to attach directly'),
   waitFor: z.boolean().optional().describe('Wait for the process to appear when attaching'),
+  continueOnAttach: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('Resume execution automatically after attaching (default: true)'),
   makeCurrent: z
     .boolean()
     .optional()
@@ -109,20 +114,39 @@ export async function debug_attach_simLogic(
       debuggerManager.setCurrentSession(session.id);
     }
 
+    const shouldContinue = params.continueOnAttach ?? true;
+    if (shouldContinue) {
+      try {
+        await debuggerManager.resumeSession(session.id);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+          await debuggerManager.detachSession(session.id);
+        } catch {
+          // Best-effort cleanup; keep original resume error.
+        }
+        return createErrorResponse('Failed to resume debugger after attach', message);
+      }
+    }
+
     const warningText = simResult.warning ? `⚠️ ${simResult.warning}\n\n` : '';
     const currentText = isCurrent
       ? 'This session is now the current debug session.'
       : 'This session is not set as the current session.';
+    const resumeText = shouldContinue
+      ? 'Execution resumed after attach.'
+      : 'Execution is paused. Use debug_continue to resume before UI automation.';
 
     const backendLabel = session.backend === 'dap' ? 'DAP debugger' : 'LLDB';
 
     return createTextResponse(
       `${warningText}✅ Attached ${backendLabel} to simulator process ${pid} (${simulatorId}).\n\n` +
         `Debug session ID: ${session.id}\n` +
-        `${currentText}\n\n` +
+        `${currentText}\n` +
+        `${resumeText}\n\n` +
         `Next steps:\n` +
         `1. debug_breakpoint_add({ debugSessionId: "${session.id}", file: "...", line: 123 })\n` +
-        `2. debug_lldb_command({ debugSessionId: "${session.id}", command: "continue" })\n` +
+        `2. debug_continue({ debugSessionId: "${session.id}" })\n` +
         `3. debug_stack({ debugSessionId: "${session.id}" })`,
     );
   } catch (error) {

src/mcp/tools/debugging/debug_attach_sim.ts

@@ -0,0 +1,43 @@
+import * as z from 'zod';
+import { ToolResponse } from '../../../types/common.ts';
+import { createErrorResponse, createTextResponse } from '../../../utils/responses/index.ts';
+import { createTypedToolWithContext } from '../../../utils/typed-tool-factory.ts';
+import {
+  getDefaultDebuggerToolContext,
+  type DebuggerToolContext,
+} from '../../../utils/debugger/index.ts';
+
+const debugContinueSchema = z.object({
+  debugSessionId: z
+    .string()
+    .optional()
+    .describe('Debug session ID to resume (defaults to current session)'),
+});
+
+export type DebugContinueParams = z.infer<typeof debugContinueSchema>;
+
+export async function debug_continueLogic(
+  params: DebugContinueParams,
+  ctx: DebuggerToolContext,
+): Promise<ToolResponse> {
+  try {
+    const targetId = params.debugSessionId ?? ctx.debugger.getCurrentSessionId();
+    await ctx.debugger.resumeSession(targetId ?? undefined);
+
+    return createTextResponse(`✅ Resumed debugger session${targetId ? ` ${targetId}` : ''}.`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return createErrorResponse('Failed to resume debugger', message);
+  }
+}
+
+export default {
+  name: 'debug_continue',
+  description: 'Resume execution in the active debug session or a specific debugSessionId.',
+  schema: debugContinueSchema.shape,
+  handler: createTypedToolWithContext<DebugContinueParams, DebuggerToolContext>(
+    debugContinueSchema,
+    debug_continueLogic,
+    getDefaultDebuggerToolContext,
+  ),
+};

src/mcp/tools/debugging/debug_continue.ts

@@ -10,6 +10,7 @@ function createBackend(overrides: Partial<DebuggerBackend> = {}): DebuggerBacken
     attach: async () => {},
     detach: async () => {},
     runCommand: async () => '',
+    resume: async () => {},
     addBreakpoint: async (spec: BreakpointSpec): Promise<BreakpointInfo> => ({
       id: 1,
       spec,

src/utils/debugger/__tests__/debugger-manager-dap.test.ts

@@ -7,6 +7,7 @@ export interface DebuggerBackend {
   detach(): Promise<void>;
 
   runCommand(command: string, opts?: { timeoutMs?: number }): Promise<string>;
+  resume(opts?: { threadId?: number }): Promise<void>;
 
   addBreakpoint(spec: BreakpointSpec, opts?: { condition?: string }): Promise<BreakpointInfo>;
   removeBreakpoint(id: number): Promise<string>;

src/utils/debugger/backends/DebuggerBackend.ts

@@ -152,6 +152,22 @@ class DapBackend implements DebuggerBackend {
     }
   }
 
+  async resume(opts?: { threadId?: number }): Promise<void> {
+    return this.enqueue(async () => {
+      this.ensureAttached();
+
+      let threadId = opts?.threadId;
+      if (!threadId) {
+        const thread = await this.resolveThread();
+        threadId = thread.id;
+      }
+
+      await this.request('continue', { threadId });
+      this.executionState = { status: 'running' };
+      this.lastStoppedThreadId = null;
+    });
+  }
+
   async addBreakpoint(
     spec: BreakpointSpec,
     opts?: { condition?: string },