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]

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
• 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 c7b7e13. Configure here.}

[cursor]

Next steps silently dropped for mixed content types

Medium Severity

processToolResponse appends the next-steps section only when the last content item is text. The fallback (if (!hasTextContent)) checks whether any item is text. When the last item is non-text (e.g., an image) but earlier items are text, hasTextContent is true so the fallback is skipped, and the next-steps section is silently dropped from the output.

 

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