Agent debug NDJSON tools + swift-agent-debug-log skill

[maatheusgois-dd]

Summary

• Adds four MCP tools for Cursor DEBUG MODE: bazel_ios_agent_debug_log_clear, read, pull, and repro (clear → build_and_run with AGENT_DEBUG_* env → optional log capture).
• Adds MCP resource xcodebazel://agent-debug-log?path=... for structured NDJSON reads.
• Ships skills/swift-agent-debug-log/SKILL.md in the npm package; xcodebazelmcp init copies bundled skills to ~/.cursor/skills/ and .agents/skills/.
• Extends log_capture_start with messageContains / jsonLinesOnly filters on stop.
• New agent_debug workflow (included in default MCP workflows); tool count 112 → 116.

Scope

• MCP server/tools
• CLI commands or parsers
• Bazel build/test/discovery
• Simulator workflows
• Physical device workflows
• UI automation, screenshots, video, logs, or deep links
• LLDB debugging
• macOS, tvOS, watchOS, or visionOS workflows
• Swift Package Manager
• Daemon, session defaults, config, doctor, or setup
• Project scaffolding
• Docs, examples, or agent skills
• CI, release, packaging, or dependencies

Validation

• npm run lint
• npm run typecheck
• npm test
• npm run build
• npx vitest --run --coverage
• Manual MCP validation with Cursor or another MCP client
• Manual CLI validation with xcodebazelmcp ...
• Bazel workspace validation against a real Apple target
• Simulator validation
• Physical device validation

Compatibility

• Adds, removes, or renames MCP tools
• Changes CLI flags, command output, exit codes, or streaming behavior
• Changes config files, environment variables, defaults, or profiles
• Changes generated project scaffolding
• Changes package contents, dependencies, Node support, or release behavior
• Requires updates to docs, README, manifests, schemas, or skills
• No compatibility impact

Notes For Reviewers

MCP tools (runtime) — agents use these instead of Read/delete_file on .cursor/debug-*.log from sim code:

Tool	Role
bazel_ios_agent_debug_log_clear	Delete host NDJSON log before repro
bazel_ios_agent_debug_log_read	Parse/filter; hypothesisStatusHints for CONFIRMED/REJECTED
bazel_ios_agent_debug_log_pull	simctl get_app_container → Documents/agent-debug.ndjson
bazel_ios_agent_debug_repro	clear + build_and_run with AGENT_DEBUG_LOG_PATH / AGENT_DEBUG_SESSION_ID

Skill (protocol) — not exposed over MCP; installed via xcodebazelmcp init. Documents env-based host path vs simulator Documents fallback.

Example repro args:

{
  "target": "//app:app",
  "logPath": "/abs/path/.cursor/debug-522bed.log",
  "sessionId": "522bed"
}

Follow-up (optional): README tool count 112 → 116, version bump for npm publish.

Made with Cursor

[codecov]

Codecov Report

❌ Patch coverage is 53.01724% with 218 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/tools/handlers/agent-debug.ts	60.75%	73 Missing ⚠️
src/core/agent-debug-log.ts	66.45%	52 Missing and 1 partial ⚠️
src/cli/commands.ts	8.69%	42 Missing ⚠️
src/tools/handlers/simulator.ts	22.85%	27 Missing ⚠️
src/mcp/server.ts	0.00%	23 Missing ⚠️

📢 Thoughts on this report? Let us know!