refactor(5/12): change handler contract to event-based emission

[cameroncooke]

Summary

This is PR 5 of 12 in a stacked PR series that decouples the rendering pipeline from MCP transport. Depends on PR 4 (utility extraction). This is the most architecturally significant PR in the stack -- it changes the fundamental contract between tool handlers and the runtime.

The contract change

Before: Tool handlers returned a ToolResponse object containing pre-rendered MCP content:
```typescript
handler: (params) => Promise
```

After: Tool handlers receive a context object and emit events through it, returning nothing:
```typescript
handler: (params, ctx: ToolHandlerContext) => Promise
```

The ToolHandlerContext provides:

• emit(event: PipelineEvent): Push a structured event into the render session
• attach(image: ImageAttachment): Attach binary content (screenshots)

This decouples tools from rendering entirely. A tool says "the build succeeded" via ctx.emit(statusLine('success', 'Build succeeded')) without knowing whether the output will be rendered as colored terminal text, JSON, or MCP protocol content.

Tool invoker refactor

The invoker (tool-invoker.ts) is significantly simplified:

• Deleted postProcessToolResponse, emitNextStepsEvent, renderNextStepsIntoContent, finalizeResult
• The invoker creates a ToolHandlerContext, passes it to the handler, then emits next-steps into the same render session after the handler completes
• No more PendingBuildResult pattern -- the handler just awaits the pipeline and the render session accumulates events progressively

Typed tool factory

typed-tool-factory.ts updated to produce handlers matching the new signature. Session-aware wrappers now thread the context through.

Core manifest and schema

• import-resource-module.ts added for resource manifest loading (split from tool module loading)
• Schema and load-manifest updated for the simplified handler contract
• plugin-types.ts updated to reflect new handler signatures

Deleted

• typed-tool-factory-consolidation.test.ts (tested removed consolidation logic)
• load-manifest.test.ts (moved to schema test coverage)

Stack navigation

• PR 1-4/12: Foundation and utility extraction
• PR 5/12 (this PR): Runtime handler contract and tool invoker
• PR 6-9/12: Tool migrations (mechanical -- update handlers to use ctx.emit)
• PR 10-12/12: Boundaries, config, tests

Note for reviewers

PRs 6-9 (tool migrations) depend on this contract change. Each tool handler is updated from return toolResponse([...]) to ctx.emit(...) calls. Those are mechanical transformations but they cannot compile without this PR landing first. If reviewing the stack incrementally, this PR is the critical design decision point.

Test plan

• npx vitest run passes -- invoker tests updated for new contract
• Handler context correctly propagates emit/attach to render session
• Next-steps are emitted into the render session after handler completion
• Typed tool factory produces handlers with correct signatures

[cameroncooke]

• 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
• 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 👈 (View in Graphite)
• 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.

[cursor]

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

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

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

[cursor]

Duplicate packageCachePath property in PlatformBuildOptions

Medium Severity

The PlatformBuildOptions interface now declares packageCachePath?: string twice — once on line 141 and again on line 144. This was introduced in the diff (the original only had one). While TypeScript allows duplicate optional properties of the same type, this is clearly unintentional and will cause confusion for future developers.

Additional Locations (1)

• src/types/common.ts#L140-L141

 

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

[cameroncooke]

Merge activity

• Apr 10, 12:18 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 10, 12:21 PM UTC: Graphite rebased this pull request as part of a merge.
• Apr 10, 12:21 PM UTC: @cameroncooke merged this pull request with Graphite.

[sentry]

Bug: The imported type DaemonToolResult is not defined or exported from src/daemon/protocol.ts, which will cause a compilation failure.
_{Severity: HIGH}

Suggested Fix

Define and export the DaemonToolResult interface in src/daemon/protocol.ts. Based on its usage, the interface should be: export interface DaemonToolResult { events: PipelineEvent[]; isError?: boolean; nextSteps?: NextStep[]; nextStepParams?: NextStepParamsMap; }.

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/types/common.ts#L141-L145

Potential issue: The type `DaemonToolResult` is imported and used in
`src/runtime/tool-invoker.ts` but is not defined or exported from its source file,
`src/daemon/protocol.ts`. This will cause a TypeScript compilation error, "Cannot find
name 'DaemonToolResult'", which will prevent the application from building. The type is
used in the `consumeResult` function to handle results from the daemon.