refactor(10/12): rewire CLI, daemon, and MCP server boundaries

[cameroncooke]

Summary

This is PR 10 of 12 in a stacked PR series that decouples the rendering pipeline from MCP transport. Depends on PR 9 (all tool migrations complete). This PR connects the dots -- it rewires the three output boundaries (CLI, daemon, MCP server) to use the render session from PR 3 with the event-based handlers from PRs 5-9.

Architecture: three boundaries, one rendering engine

The rendering pipeline has three consumers, each using the same render session differently:

CLI direct (src/cli/register-tool-commands.ts): Creates a render session with the user's chosen strategy (text or JSON). Wraps emit to write incrementally to stdout as events arrive (streaming output during builds). After the handler completes, calls finalize() to flush any buffered content (grouped diagnostics). Sets exit code from session.isError().

MCP server (src/utils/tool-registry.ts): Creates a render session with text strategy. After the handler completes, calls finalize() to get the complete rendered string, wraps it in a ToolResponse (the MCP protocol type). ToolResponse construction happens here and only here -- it is not exported or used anywhere else in the codebase.

Daemon (src/daemon/daemon-server.ts): Creates a render session in record-only mode. Sends raw events over the wire to the CLI client. The CLI client re-renders locally using its own session, giving the same output as CLI direct mode.

CLI changes

• output.ts: Deleted printToolResponse(), extractRenderedNextSteps(), and all _meta coordination logic. These were the main sources of complexity in the old rendering pipeline. Kept formatToolList() for --list output.
• register-tool-commands.ts: Now creates and manages the render session directly. Streaming output is handled by a thin wrapper around session.emit().
• daemon-client.ts: Updated to receive events from daemon and render locally.

Daemon protocol

• Protocol version bumped to v2. Wire payload is now { events, attachments?, isError? } instead of pre-rendered content.
• Old CLI + new daemon (or vice versa) gets a clear version mismatch error with restart instructions.

MCP resources

All MCP resource handlers updated to use the simplified context pattern (10 files). These are simpler than tool handlers since resources don't emit pipeline events.

Other changes

• src/integrations/xcode-tools-bridge/: Updated to work with the new handler context. Added bridge-tool-result.ts for structured bridge tool results.
• src/visibility/exposure.ts: Updated exposure predicates for new handler signatures.
• src/smoke-tests/: Updated test harness for new tool invocation pattern.
• Various utility files updated for signature changes: CommandExecutor, FileSystemExecutor, execution/, xcode-state-reader, xcode-state-watcher, video-capture, log_capture.

Stack navigation

• PR 1-9/12: Foundation, utilities, contract, tool migrations
• PR 10/12 (this PR): CLI, daemon, MCP server boundaries
• PR 11/12: Manifests, config, docs, examples
• PR 12/12: Snapshot test fixtures and benchmarks

Test plan

• npx vitest run passes -- boundary tests updated
• CLI text output matches expected formatting (manual spot check)
• CLI JSON output produces valid JSONL
• MCP server returns correctly structured ToolResponse content
• Daemon protocol v2 correctly transmits events over wire
• Smoke tests pass with new tool invocation pattern

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Nullish coalescing changes Xcode availability detection logic
  • Changed nullish coalescing operator (??) back to logical OR (||) to properly handle empty strings in Xcode version field chain.
• ✅ Fixed: Unused outputStyle variable after refactoring
  • Removed the unused outputStyle variable extraction that was left behind after refactoring removed printToolResponse().

Or push these changes by commenting:

@cursor push 5001d2a65c

Preview (5001d2a65c)

diff --git a/src/cli/register-tool-commands.ts b/src/cli/register-tool-commands.ts
--- a/src/cli/register-tool-commands.ts
+++ b/src/cli/register-tool-commands.ts
@@ -221,7 +221,6 @@
       const jsonArg = argv.json as string | undefined;
       const profileOverride = argv.profile as string | undefined;
       const outputFormat = (argv.output as OutputFormat) ?? 'text';
-      const outputStyle = (argv.style as OutputStyle) ?? 'normal';
       const socketPath = argv.socket as string;
       const logLevel = argv['log-level'] as string | undefined;
 

diff --git a/src/daemon.ts b/src/daemon.ts
--- a/src/daemon.ts
+++ b/src/daemon.ts
@@ -208,9 +208,9 @@
       return { success: result.success, output: result.output };
     });
     const xcodeAvailable = Boolean(
-      xcodeVersion.version ??
-        xcodeVersion.buildVersion ??
-        xcodeVersion.developerDir ??
+      xcodeVersion.version ||
+        xcodeVersion.buildVersion ||
+        xcodeVersion.developerDir ||
         xcodeVersion.xcodebuildPath,
     );
     const axeVersion = await getAxeVersionMetadata(async (command) => {

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Nullish coalescing changes Xcode availability detection logic

Medium Severity

Replacing || with ?? changes the semantics for empty strings. If xcodeVersion.version is "" (common when a command fails), ?? considers it non-nullish and stops evaluation, making Boolean("") return false. With ||, the chain would continue to check buildVersion, developerDir, and xcodebuildPath. This can incorrectly report xcodeAvailable as false even when later fields have valid values.

 

^{Reviewed by Cursor Bugbot for commit b91063e. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e6d00fe. Configure here.}

[cameroncooke]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• refactor(12/12): add snapshot test fixtures and benchmarks #330
• refactor(11/12): update manifests, config, docs, and example projects #329
• refactor(10/12): rewire CLI, daemon, and MCP server boundaries #328 👈 (View in Graphite)
• refactor(9/12): migrate debugging, swift-package, and remaining tools #327
• refactor(8/12): migrate UI automation tools to event-based handlers #326
• refactor(7/12): migrate device and macOS tools to event-based handlers #325
• refactor(6/12): migrate simulator tools to event-based handlers #324
• refactor(5/12): change handler contract to event-based emission #323
• refactor(4/12): extract build/test utilities, platform steps, and xcodebuild pipeline #322
• refactor(3/12): add rendering engine and output formatting #321
• refactor(2/12): add pipeline event types, parsers, and event builders #320
• refactor(1/12): remove deprecated logging tools #319
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[sentry]

Bug: The handlerContext is not passed correctly to the tool invoker, causing nextStepParams set by tools to be lost and breaking dynamic client-side template expansion.
_{Severity: HIGH}

Suggested Fix

Ensure the handlerContext object from the daemon server is explicitly passed to invoker.invoke(). This will ensure the same object reference is used, allowing properties set by the tool handler to be correctly read after the invocation.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: src/utils/command.ts#L79-L82

Potential issue: In `daemon-server.ts` (lines 160-165), the `handlerContext` object is
not correctly propagated when calling `invoker.invoke()`. The invoker creates a new,
separate context object. As a result, when a tool handler sets properties like
`ctx.nextStepParams` on its context, these values are lost and remain `undefined` on the
original `handlerContext` object that the daemon server later inspects. This failure to
pass the context by reference breaks the mechanism for passing dynamic parameters for
subsequent steps, preventing template expansion on the client side.

[sentry]

Bug: When using --output raw, the render session's output is buffered but never printed because the return value of session.finalize() is discarded.
_{Severity: HIGH}

Suggested Fix

Capture the return value from session.finalize() and write it to process.stdout when the output format is 'raw' to ensure the buffered output is displayed to the user.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: src/cli/register-tool-commands.ts#L276-L285

Potential issue: When the `--output raw` flag is used, the system configures a `'text'`
render session. This session type buffers all output in memory rather than writing it
directly to standard output. The buffered content is meant to be returned by the
`session.finalize()` method. However, the implementation calls `session.finalize()` but
discards its return value. Consequently, all generated output is collected and then
thrown away, resulting in no output being displayed to the user, rendering the `--output
raw` feature non-functional.