feat(workflows)!: implement event bus streaming architecture and unified workflow SDK

[lavaman131]

Summary

This PR introduces a comprehensive streaming architecture overhaul with a new event bus system and unified workflow SDK. The changes enable robust cross-provider streaming, improved sub-agent correlation, and a declarative workflow execution engine for building complex agent workflows.

Key Changes

🎯 Event Bus Architecture (src/events/)

Introduces a type-safe event bus system for streaming coordination across all SDK adapters:

• Core event bus with pub/sub pattern, wildcard subscriptions, and error isolation
• SDK adapters for Claude, OpenCode, Copilot, and workflows to normalize streaming events
• Correlation service for tracking sub-agent relationships and tool attribution
• Echo suppression to prevent duplicate events in the UI
• Stream pipeline consumer for efficient event processing
• Debug subscriber with per-session logging and structured telemetry

🔧 Workflow SDK Refactor (src/workflows/)

Major reorganization from src/graph/ to src/workflows/graph/ with enhanced capabilities:

• Generic workflow executor replacing provider-specific implementations
• Template system for reusable workflow patterns
• State validator with Zod schema enforcement
• Provider registry for multi-agent orchestration
• Runtime contracts with feature flags and task identity tracking
• Ralph workflow refactor using the new graph SDK
• Checkpointing and resumption support

📡 SDK Improvements

Claude Client (src/sdk/clients/claude.ts):

• Sub-agent streaming improvements with proper lifecycle tracking
• Process exit error handling
• TaskOutput attribution across child sessions

OpenCode Client (src/sdk/clients/opencode.ts):

• SSE-only streaming migration (promptAsync() over prompt())
• Duplicate stream delta prevention
• Event loop timing fixes
• Resilience improvements and abort handling

Copilot Client (src/sdk/clients/copilot.ts):

• UI alignment parity
• Permission request forwarding
• Tool discovery integration

🎨 UI Enhancements (src/ui/)

• Major chat.tsx refactor (4,300+ line changes) with improved state management
• Parallel agents tree with better sub-agent grouping and deduplication
• New part displays: TaskResultPartDisplay, WorkflowStepPartDisplay
• Cross-provider streaming contracts for consistent behavior
• Background agent termination improvements
• Session idle flush for cleaner shutdown

🎭 Playwright CLI Integration

New skill added across all three agent configurations (.claude/, .opencode/, .github/):

• Browser automation for testing, form filling, screenshots
• Session management and storage state
• Request mocking and tracing
• Video recording and test generation

📦 Installation Scripts

• install.sh for macOS/Linux
• install.ps1 for Windows PowerShell
• Postinstall Playwright with verification tests
• Installer validation GitHub workflow

📚 Documentation

• Consolidated Claude Agent SDK docs (docs/claude-agent-sdk.md)
• Workflow authors getting started guide (docs/workflow-authors-getting-started.md)
• Stream debug logging (docs/stream-debug-logging.md)
• UI design patterns (docs/ui-design-patterns.md)
• E2E testing enhancements (docs/e2e-testing.md)
• Extensive research docs in research/docs/ (28 new files)
• Implementation specs in specs/ (15 new files)

✅ Testing

Massive increase in test coverage:

• Event system: 10+ test files covering adapters, bus, correlation, echo suppression
• Workflows: Graph builder, executor, compiled graphs, templates, nodes
• SDK clients: OpenCode events, resilience, streaming, Claude/Copilot contracts
• UI: Chat lifecycle, sub-agent grouping, task state, workflow commands
• E2E: Cross-provider contracts, Playwright CLI, compact UX parity
• Integration: Event bus integration, postinstall, parallel sub-agents

🐛 Bug Fixes

• Sub-agent tree rendering (deduplication, orphan fixes, ordering)
• OpenCode SSE duplicate deltas and race conditions
• Thinking trace rendering across all SDKs
• Background agent termination and footer display
• CRLF line ending handling in markdown
• Task list blinking and status transitions
• Stream lifecycle and run guards

Breaking Changes

⚠️ Graph reorganization: Workflows moved from src/graph/ to src/workflows/graph/

⚠️ Removed APIs: SubagentResult replaced with SubagentStreamResult

⚠️ Workflow SDK initialization: Now requires WorkflowSDK.init() with provider registry

⚠️ Runtime contracts: Workflows now use strict task contracts by default (can be disabled via feature flags)

Migration Notes

For workflow authors:

1. Update imports from @bastani/atomic/graph to use the new location
2. Replace SubagentResult with SubagentStreamResult in type signatures
3. Use WorkflowSDK.init() for provider setup (see docs/workflow-authors-getting-started.md)
4. Update node definitions to use the new createNode() helper

For contributors:

1. Event bus is now the canonical streaming layer - use adapters for SDK integration
2. All streaming events should be typed in src/events/bus-events.ts
3. Sub-agent correlation is handled automatically by the correlation service
4. Use pipelineLog() and pipelineError() for event pipeline logging

Stats

• 338 files changed
• 96,454 insertions, 11,886 deletions
• 151 commits across streaming, events, workflows, SDK, and UI improvements
• 28 research documents documenting architectural decisions
• 15 implementation specs for tracking feature development
• 116 test files added or modified

Testing

All tests passing:

bun test
bun lint
bun typecheck

E2E tests verified across all three coding agent providers (Claude, OpenCode, Copilot).

[claude]

PR Review: Lavaman131/feature/workflow sdk

Thanks for this comprehensive PR! This is a substantial contribution adding installer scripts, new skills (playwright-cli), agents (planner), documentation, and research materials. Here's my review:

---

🚨 Critical Issues

1. PowerShell 5.1 Compatibility (install.ps1:16-17)

$BinDir = if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } elseif ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" }

Problem: The if expression assignment syntax is only supported in PowerShell 7+. Windows PowerShell 5.1 (default on Windows 10/11) will throw a parse error, making the documented irm ... | iex command fail for most Windows users.

Fix: Wrap in a subexpression:

$BinDir = $(if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } elseif ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" })

Or use the ternary-like pattern:

$BinDir = if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } else { if ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" } }
# Actually, better to use switch/case or separate if blocks for PS5.1

2. CI Workflow Will Always Fail (installer-validation.yml:40, 71)

Problem: The workflow runs the actual installer scripts which call get_latest_version() to fetch from GitHub releases. If no releases exist, the scripts fail under set -euo pipefail. Even with releases, the workflow tests downloading released artifacts rather than validating the installer logic for the current commit.

Fix: Consider one of these approaches:

• Add a --dry-run or --skip-download flag for CI validation
• Mock the download phase in CI and only test the script logic
• Create a separate validation that only checks script syntax (shellcheck, PSScriptAnalyzer)

---

⚠️ Medium Priority Issues

3. grep Regex Pattern Issue (install.sh:186)

expected=$(grep "$filename" "$checksums_file" | awk '{print $1}')

Problem: $filename is treated as a regex. For atomic-config.tar.gz, the dots match any character, potentially matching unintended lines like atomic-configXtarXgz or producing multiple matches.

Fix: Use fixed-string matching:

expected=$(grep -F "$filename" "$checksums_file" | awk '{print $1}')

4. Trap Cleanup Quoting Issue (install.sh:276)

trap "rm -rf $tmp_dir" EXIT

Problem: $tmp_dir is expanded at trap-set time without quoting inside the command string. If TMPDIR contains whitespace, rm -rf could operate on unintended paths.

Fix: Use single quotes with proper escaping:

trap 'rm -rf "$tmp_dir"' EXIT

Note: This requires moving the trap after $tmp_dir is assigned, which it currently is - just update the quoting.

---

💡 Suggestions

5. Consider ShellCheck/PSScriptAnalyzer

For installer scripts that will be run by many users, consider adding:

• ShellCheck validation for install.sh in CI
• PSScriptAnalyzer validation for install.ps1 in CI

6. Package.json Looks Good

The dependency changes appear reasonable:

• Updated versions for existing deps
• No concerning new dependencies
• Proper devDependencies vs dependencies separation

7. Documentation & Research

The extensive documentation additions (specs, research docs) provide good context for the changes. The playwright-cli skill and planner agent are well-documented.

---

📊 Summary

Category	Status
Code Quality	⚠️ Needs fixes
Security	⚠️ Minor concerns in trap handling
Performance	✅ No concerns
Test Coverage	❌ CI workflow will fail
Documentation	✅ Comprehensive

Recommendation: Please address the critical issues (PowerShell compatibility and CI workflow) before merging. The medium-priority fixes would further improve robustness.

Overall this is a solid PR with good structure - just needs these installer script fixes to be production-ready.

[lavaman131]

Addressed all review feedback in commit 86f3b13:

Critical fixes:

1. PowerShell 5.1 compatibility (install.ps1:16-17) — Wrapped \if\ expression assignments in \\ subexpressions so they parse correctly on Windows PowerShell 5.1.
2. CI workflow (installer-validation.yml) — Replaced full installer execution (which requires GitHub releases to exist) with syntax validation: ShellCheck for \install.sh\ and PSScriptAnalyzer for \install.ps1.

Medium priority fixes:
3. grep regex pattern (install.sh:186) — Changed to \grep -F\ for fixed-string matching so dots in filenames like \�tomic-config.tar.gz\ aren't treated as regex wildcards.
4. Trap cleanup quoting (install.sh:276) — Changed to single-quoted trap command so \\ is expanded at trap-execution time, preventing issues with paths containing whitespace.

[claude]

PR Review: Streaming Architecture and Unified Workflow SDK

Thank you for this comprehensive PR! This is a significant architectural overhaul with 338 files changed and 96k+ insertions. After reviewing the key components, here's my feedback:

---

Code Quality and Best Practices

Strengths:

1. Excellent Type Safety: The event bus system (src/events/bus-events.ts) demonstrates excellent TypeScript patterns:

   • Comprehensive BusEventType union covering all event types
   • Well-typed BusEventDataMap interface for type-safe event payloads
   • Zod schema validation for runtime type safety
   • Clean separation of concerns between event definitions and bus implementation

2. Solid Architecture: The EventBus class (src/events/event-bus.ts) follows good patterns:

   • Error isolation (handler errors don't break publishers)
   • Configurable payload validation (can disable in hot paths for performance)
   • Clean unsubscribe pattern with returned cleanup functions
   • Internal error reporting mechanism for debugging

3. Well-Documented Code: Comprehensive JSDoc comments throughout, with clear explanations of:

   • Module purposes and responsibilities
   • Agent-specific logic explanations (e.g., why claude.ts exists)
   • Usage examples in comments

4. Good Test Coverage: 100+ test files covering:

   • Unit tests for core components (event bus, correlation service, adapters)
   • Integration tests for cross-provider streaming
   • E2E tests for workflows and UI components

Areas for Improvement:

1. Large File Sizes: Some files are quite large:

   • src/sdk/clients/claude.ts exceeds 25k tokens
   • src/sdk/clients/opencode.ts exceeds 32k tokens
   • Consider breaking these into smaller, more focused modules

2. Magic Numbers: Consider extracting constants for better maintainability:

   // In opencode.ts, consider moving these to a config object
   const DEFAULT_MAX_RETRIES = 3;
   const DEFAULT_RETRY_DELAY = 1000;
   const PRE_PROMPT_TERMINAL_SETTLE_MS = 500;
   const MAX_COMPACTION_WAIT_MS = 15_000;

---

Potential Bugs or Issues

1. Debounce Timer Cleanup (src/workflows/executor.ts:564-572): The debounce timer cleanup in the error path could miss edge cases. Consider wrapping in finally block or using a dedicated cleanup function.

2. Non-null Assertion Risk (src/workflows/executor.ts:153):

   const workflowRunId = crypto.getRandomValues(new Uint32Array(1))[0]\!;

   While this should never fail, the non-null assertion obscures the assumption. Consider using a utility function.

3. Error Type Narrowing (src/workflows/executor.ts:477):

   lastStepError = step.error?.error instanceof Error ? step.error.error.message : step.error?.error;

   This could produce unexpected types. Consider explicit string coercion.

---

Performance Considerations

Positive:

1. Configurable Validation: The validatePayloads option allows disabling Zod validation in production hot paths
2. Early Returns: Event bus skips processing when no handlers are registered
3. Debounced Task Saves: Prevents I/O contention during rapid workflow updates (100ms debounce)
4. Efficient Handler Management: Uses Map and Set for O(1) lookups

Suggestions:

1. Event Batching: For high-frequency events like stream.text.delta, consider batching to reduce handler invocations
2. Memory Cleanup: Ensure toolIdToRunMap and subagentRegistry in CorrelationService are cleaned up properly to prevent memory leaks in long-running sessions

---

Security Concerns

1. Install Scripts: The install scripts (install.sh, install.ps1) look secure:

   • Checksum verification for downloads
   • No hardcoded credentials
   • Proper error handling with set -euo pipefail

2. Good Practice: No obvious security vulnerabilities like:

   • Command injection risks
   • Credential exposure
   • Unsafe deserialization

---

Test Coverage

Coverage Appears Strong:

• Event system: 10+ test files covering adapters, bus, correlation, echo suppression
• Workflows: Graph builder, executor, compiled graphs, templates, nodes
• SDK clients: OpenCode events, resilience, streaming, Claude/Copilot contracts
• UI: Chat lifecycle, sub-agent grouping, task state, workflow commands
• Integration: Event bus integration, postinstall, parallel sub-agents

Recommendation: Consider adding stress tests for:

• High-frequency event publishing (memory/performance)
• Concurrent workflow executions
• Error recovery scenarios

---

Documentation

Well Documented:

• docs/claude-agent-sdk.md - 2,558 lines of SDK documentation
• docs/workflow-authors-getting-started.md - Guide for workflow authors
• docs/stream-debug-logging.md - Debug logging documentation
• docs/e2e-testing.md - Comprehensive testing guidelines
• 30+ research documents for architectural decisions

---

Breaking Changes

The PR clearly documents breaking changes:

• Graph reorganization from src/graph/ to src/workflows/graph/
• SubagentResult replaced with SubagentStreamResult
• Workflow SDK initialization requires WorkflowSDK.init()

Suggestion: Consider adding a migration script or codemod for users upgrading from previous versions.

---

Summary

This is a well-architected, thoroughly tested PR that significantly improves the streaming and workflow capabilities. The code quality is high with strong TypeScript typing and comprehensive documentation.

Recommended for merge with minor suggestions addressed above.

Category	Rating
Code Quality	⭐⭐⭐⭐⭐
Test Coverage	⭐⭐⭐⭐⭐
Documentation	⭐⭐⭐⭐⭐
Security	⭐⭐⭐⭐
Performance	⭐⭐⭐⭐

---

Reviewed by Claude

[claude]

PR Review: feat(workflows)!: Event Bus Streaming Architecture and Unified Workflow SDK

Thanks for this comprehensive overhaul! This is a substantial PR (~96k additions, 338 files). I've reviewed the key architectural changes and have feedback organized by category.

---

✅ Strengths

1. Event Bus Architecture (src/events/)

• Excellent type-safe design using Zod schemas for runtime validation
• Clean pub/sub pattern with proper error isolation (event-bus.ts:246-275)
• Well-documented with JSDoc and usage examples
• The EnrichedBusEvent interface for correlation metadata is well thought out

2. Correlation Service (src/events/consumers/correlation-service.ts)

• Good separation of concerns - handles tool-to-agent mappings cleanly
• Properly handles sub-agent registration and lifecycle tracking
• isOwnedEvent() method provides clean session ownership semantics

3. Runtime Contracts (src/workflows/runtime-contracts.ts)

• Robust Zod schemas with helpful status aliases (todo → pending, doing → in_progress)
• Good normalization functions for blockedBy, identity, and task results
• Proper observability hooks via incrementRuntimeParityCounter and observeRuntimeParityHistogram

4. Workflow Executor (src/workflows/executor.ts)

• Clean generic executor that replaces provider-specific implementations
• Good debounced persistence to avoid I/O contention
• Proper cleanup with unsubscribeStatusChange?.() patterns

5. Test Coverage

• Comprehensive unit tests for EventBus including schema validation edge cases
• Good executor tests covering graph compilation and state management
• Echo suppressor tests verify FIFO queue behavior

---

🔍 Areas for Improvement

1. Code Quality

• src/events/event-bus.ts:232-234: Debug logging in production code. Consider moving this behind a debug flag or removing:

  // DEBUG: Log the actual event data that failed validation
  if (event.type.startsWith("stream.tool.")) {
    console.error(`[EventBus] Rejected tool event data:`, JSON.stringify(event.data));
  }

• Echo Suppressor Algorithm (src/events/consumers/echo-suppressor.ts:50-75): The FIFO approach may have edge cases when tool results arrive out of order. Consider documenting this limitation or adding a TTL-based expiry for targets.

2. Potential Bugs

• src/workflows/executor.ts:172-177: The initWorkflowSession result is awaited inside a .then() chain but errors are only logged. This could lead to silent failures:

  void initWorkflowSession(definition.name, sessionId).then((session) => {
      registerActiveSession(session);
  }).catch((err) => {
      // Only logged, not surfaced
  });

  Consider making this await with proper error handling or at minimum returning the promise for the caller to handle.

• src/workflows/executor.ts:378-389: The debounced save timer could leak if the workflow executor exits abnormally before cleanup at line 563-573. Consider using AbortSignal for timer cleanup.

3. Performance Considerations

• Event Bus Validation (src/events/event-bus.ts:224): Schema validation on every publish could be expensive for high-frequency events like stream.text.delta. The validatePayloads option is good, but consider documenting performance implications.

• Correlation Service (src/events/consumers/correlation-service.ts): The enrich() method has a large switch statement with nested conditionals. This is fine for correctness but may benefit from early returns for common event types.

4. Security Considerations

• install.sh:43: Piping curl output to bash is a common pattern but consider adding --proto '=https' --tlsv1.2 flags for security hardening:

  curl -fsSL --proto '=https' --tlsv1.2 https://bun.sh/install | bash

• install.sh:286-287: Good use of --fail flag. The checksum verification at lines 300-301 is excellent security practice.

• install.sh:239-244: Installing global npm packages silently with 2>/dev/null || true could hide important security warnings. Consider at least logging when installation fails.

5. Documentation Gaps

• The breaking changes section in the PR description is excellent, but consider adding a MIGRATION.md file to the repo for long-term reference
• The WorkflowEventAdapter class is used but not fully documented in the new docs/workflow-authors-getting-started.md

---

📋 Suggested Changes

1. Remove or gate debug logging in production event bus code
2. Add proper error handling for initWorkflowSession in executor
3. Document echo suppressor limitations regarding out-of-order tool results
4. Add TLS flags to curl commands in install scripts
5. Consider adding timer cleanup via AbortSignal in debounced save logic

---

🧪 Test Coverage Assessment

The test coverage is strong:

• event-bus.test.ts: Comprehensive unit tests including schema validation
• executor.test.ts: Good coverage of graph compilation and state management
• correlation-service.test.ts: Tests correlation and enrichment logic
• echo-suppressor.test.ts: Covers FIFO queue behavior
• E2E testing guide (docs/e2e-testing.md): Thorough cross-provider testing approach

Recommendation: Consider adding integration tests for the full event flow from SDK adapters → EventBus → Correlation → Echo Suppression → UI.

---

Summary

This is a well-architected refactor that introduces a robust event bus system with proper type safety, runtime validation, and correlation tracking. The workflow SDK refactor provides a clean declarative API for building agent workflows.

Overall Assessment: Approve with minor suggestions. The architecture is solid and the test coverage is comprehensive. Address the noted items as time permits.

Great work! 🎉

[claude]

PR Review: Event Bus Streaming Architecture and Unified Workflow SDK

Thank you for this comprehensive architectural overhaul! I've reviewed the key components. Here's my detailed feedback:

---

📊 Summary

This is a large PR with 96,458 insertions across 338 files. The scope is significant, introducing:

• New event bus architecture for streaming coordination
• Unified workflow SDK with declarative graph execution
• SDK adapter improvements for Claude, OpenCode, and Copilot
• Cross-platform installation scripts
• Extensive documentation and test coverage

---

✅ Strengths

1. Well-Architected Event Bus (src/events/)

• Type-safe pub/sub pattern with Zod schema validation
• Error isolation ensures one broken handler doesn't affect others
• Clean separation between adapters, consumers, and the core bus
• Wildcard subscriptions enable observability without coupling
• validatePayloads flag allows disabling validation in hot paths

2. Correlation Service Design

• Clean separation of concerns for tracking tool-to-agent relationships
• EnrichedBusEvent pattern enriches events without mutating originals
• Sub-agent registry enables proper parent-child attribution
• Session ownership tracking prevents cross-session event leakage

3. Runtime Contracts with Strong Typing

• Zod schemas enforce data integrity at runtime boundaries
• Task status normalization handles vendor-specific aliases gracefully
• Feature flags allow gradual rollout of strict contracts
• Observability hooks (incrementRuntimeParityCounter, runtimeParityDebug) aid debugging

4. Installation Scripts

• Both install.sh and install.ps1 verify checksums before installation
• Clean temp directory handling with proper cleanup
• Multi-platform package manager detection (brew, apt, dnf, pacman, winget, choco)
• Rosetta 2 detection on macOS for arm64 binary selection

5. Test Coverage

• 169 test files provides solid coverage
• Integration tests for event bus, SDK resilience, and workflows
• E2E tests across all three providers

---

⚠️ Areas for Improvement

1. PR Size and Reviewability

• Issue: With 338 files and 96K+ lines, this PR is extremely difficult to review thoroughly
• Recommendation: Consider breaking large architectural changes into smaller, focused PRs in the future (e.g., event bus first, then adapters, then workflow SDK)

2. Console Debug Statements (src/events/event-bus.ts:232-234)

// DEBUG: Log the actual event data that failed validation
if (event.type.startsWith("stream.tool.")) {
  console.error(`[EventBus] Rejected tool event data:`, JSON.stringify(event.data));
}

• Issue: Debug console.error statements should be removed or gated behind a debug flag
• Risk: Could leak sensitive tool data (e.g., file contents, credentials) to console in production

3. Non-null Assertion Usage (src/workflows/executor.ts:153)

const workflowRunId = crypto.getRandomValues(new Uint32Array(1))[0]!;

• Issue: Non-null assertion on array access
• Recommendation: Use safer pattern: const workflowRunId = crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;

4. Debounce Timer Type (src/workflows/executor.ts:365)

let saveDebounceTimer: ReturnType<typeof setTimeout> | null = null;

• Issue: Timer reference could leak if workflow is aborted mid-debounce
• Recommendation: Add timer cleanup to the catch block and abort signal handler

5. Error Swallowing (src/events/event-bus.ts:116-118)

} catch {
  // Swallow to avoid infinite recursion
}

• Issue: Silent catch can hide bugs in internal error handlers
• Recommendation: At minimum, log to debug channel if available

6. Install Script Security (install.sh:43, install.ps1:29)

• Observation: Scripts curl/invoke remote URLs for bun installation
• Recommendation: Document the trust chain in comments; consider pinning versions for reproducibility

---

🔍 Potential Bugs

1. Race Condition in Debounced Save (src/workflows/executor.ts:373-391)

If saveTasksToSession is called rapidly, the debounce timer clears but pendingSaveTasks might reference stale data between the clear and the new assignment.

Suggestion: Move assignment before clearTimeout:

pendingSaveTasks = tasks;  // First
if (saveDebounceTimer) clearTimeout(saveDebounceTimer);  // Then

2. Missing Abort Cleanup in Workflow (src/workflows/executor.ts:230)

const workflowAbortSignal = options?.abortSignal ?? new AbortController().signal;

If no abort signal is provided, a new controller is created but never exposed for cancellation. The orphan controller should be stored if cleanup is needed.

---

🚀 Performance Considerations

1. Schema Validation Overhead

• The validatePayloads option in EventBus is well-designed
• Recommendation: Document when to disable (e.g., in production TUI rendering)

2. Map/Set Operations in Hot Path

• toolToAgent, subAgentTools maps in CorrelationService are accessed on every event
• Current implementation is fine, but consider LRU eviction if sessions grow unbounded

3. Zod Parsing on Every Task

• workflowRuntimeStrictTaskSchema.parse() is called for each task on status change
• For large task lists, consider batch validation or caching parsed results

---

🔐 Security Considerations

1. Checksum Verification ✅

Both install scripts properly verify SHA256 checksums - good practice!

2. Config File Handling

• Global config sync copies .mcp.json to ~/.atomic/
• Ensure MCP configs don't contain secrets that could be exposed

3. Tool Result Logging

• Be cautious about logging toolResult in events - may contain sensitive file contents
• Consider truncation or redaction for debug logs

---

📝 Documentation

• Comprehensive research docs in research/docs/ provide excellent architectural context
• New workflow authors guide is helpful for onboarding
• Consider adding inline JSDoc examples for key adapter methods

---

🎯 Verdict

This is a well-designed architectural change that introduces a proper event-driven streaming layer. The type safety, error isolation, and correlation tracking are solid foundations for multi-provider orchestration.

Recommendations before merge:

1. Remove or gate the debug console.error statement for tool events
2. Fix the potential race condition in debounced save
3. Clean up the debounce timer on abort/error paths
4. Consider extracting breaking changes to a MIGRATION.md file

Great work on the comprehensive test coverage and documentation!

---

Review generated by automated PR review agent