feat(workflow-executor): add debug dashboard with SSE events

[Scra3]

Summary

• Add EventEmitter to Runner (optional) emitting poll:start/end, step:start/end/error, drain:start/end events
• Add GET /debug/events SSE endpoint (public, before JWT) with 20s heartbeat
• Add GET /debug serving a React dashboard (Vite + vite-plugin-singlefile build)
• Wire EventEmitter in factory, log dashboard URL on startup
• Add demo script (demo/debug-dashboard.ts) for local testing with simulated events

Dashboard features

• Paired event visualization (start → end as a single row)
• Duration bars color-coded by status (running/success/error/awaiting-input)
• Attempt history for steps with multiple cycles (awaiting-input → resume)
• Category filters (poll/step/drain) + status filters (running/success/error/awaiting)
• Copy-to-clipboard, auto-scroll, stuck detection (>30s), tooltips
• Dark theme, DM Sans + DM Mono fonts

Test plan

• yarn workspace @forestadmin/workflow-executor test — 417 tests pass
• yarn workspace @forestadmin/workflow-executor tsc --noEmit — compiles
• npx ts-node packages/workflow-executor/demo/debug-dashboard.ts → open http://localhost:3142/debug
• Verify events stream in real-time, filters work, expand shows attempt history
• Verify copy button copies full log with all attempts

🤖 Generated with Claude Code

Note

Add debug dashboard with SSE event streaming to workflow-executor

• Adds GET /debug (serves an HTML dashboard) and GET /debug/events (SSE stream) to ExecutorHttpServer; both routes are unauthenticated.
• Runner now emits poll:start, poll:end, step:start, step:end, step:error, drain:start, and drain:end events via an optional shared EventEmitter wired through buildInMemoryExecutor and buildDatabaseExecutor.
• The React dashboard (built via Vite and inlined as a single HTML file) displays a live event stream with timeline and grouped-by-run views, filtering, search, and per-step expanded details.
• A standalone demo script at demo/debug-dashboard.ts simulates poll cycles and step executions for local development.
• Logger interface now requires info (previously optional), and all test mocks and BaseStepExecutor are updated accordingly.
• Risk: /debug and /debug/events are publicly accessible without JWT authentication.

^{Macroscope summarized 57da0d7.}

[qltysh]

17 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 11): AttemptSummary	9
qlty	Structure	Function with many returns (count = 5): AttemptSummary	6
qlty	Structure	High total complexity (count = 65)	1
qlty	Structure	Function with many parameters (count = 4): createWorkflowExecutor	1

[macroscopeapp]

🟠 High components/EventRow.tsx:85

The syntaxHighlight function produces malformed HTML due to overlapping regex replacements. After line 87 inserts <span class="json-key">"foo"</span>, line 88's "([^"]*)" pattern matches the "json-key" attribute value inside that tag, wrapping it in another span and breaking the HTML structure. This causes visible rendering errors and potential React hydration mismatches. Consider using a single-pass parser or escaping the JSON before applying syntax highlighting.

function syntaxHighlight(json: string): string {
+  const escaped = json
+    .replace(/&/g, '&')
+    .replace(/</g, '<')
+    .replace(/>/g, '>');
+  return escaped
-    .replace(/"([^"]+)":/g, '<span class="json-key">"$1"</span>:')
-    .replace(/"([^"]*)"/g, '<span class="json-str">"$1"</span>')
+    .replace(/"([^&]+)":/g, '<span class="json-key">"$1"</span>:')
+    .replace(/"([^&]*)"/g, '<span class="json-str">"$1"</span>')
    .replace(/\b(\d+\.?\d*)\b/g, '<span class="json-num">$1</span>')
    .replace(/\b(true|false|null)\b/g, '<span class="json-bool">$1</span>');
}

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/dashboard/src/components/EventRow.tsx around lines 85-91:

The `syntaxHighlight` function produces malformed HTML due to overlapping regex replacements. After line 87 inserts `<span class="json-key">"foo"</span>`, line 88's `"([^"]*)"` pattern matches the `"json-key"` attribute value inside that tag, wrapping it in another span and breaking the HTML structure. This causes visible rendering errors and potential React hydration mismatches. Consider using a single-pass parser or escaping the JSON before applying syntax highlighting.

Evidence trail:
packages/workflow-executor/dashboard/src/components/EventRow.tsx lines 85-91 at REVIEWED_COMMIT. The syntaxHighlight function applies sequential regex replacements where line 87 inserts `<span class="json-key">`, and line 88's regex `"([^"]*)"` will match the `"json-key"` attribute value, causing malformed HTML output.

[macroscopeapp]

🟡 Medium hooks/use-event-stream.ts:87

When handling poll:end or drain:end events, the code uses pollCounter.current or drainCounter.current to construct the key. If multiple polls/drains overlap, the end event uses the counter's current value rather than the value from when that specific poll/drain started. For example: poll A starts (counter=1), poll B starts (counter=2), poll A ends — the code looks up poll-2 instead of poll-1, either corrupting poll B's data or creating an orphan for poll A.

Include the start counter value in the start event's data so the end event can reference the correct key.

-            pollCounter.current += 1;
-            key = `poll-${pollCounter.current}`;
+            const counter = pollCounter.current += 1;
+            key = `poll-${counter}`;
+            (data as Record<string, unknown>).pollCounter = counter;

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/dashboard/src/hooks/use-event-stream.ts around lines 87-90:

When handling `poll:end` or `drain:end` events, the code uses `pollCounter.current` or `drainCounter.current` to construct the key. If multiple polls/drains overlap, the end event uses the counter's *current* value rather than the value from when that specific poll/drain started. For example: poll A starts (counter=1), poll B starts (counter=2), poll A ends — the code looks up `poll-2` instead of `poll-1`, either corrupting poll B's data or creating an orphan for poll A.

Include the start counter value in the start event's `data` so the end event can reference the correct key.

Evidence trail:
packages/workflow-executor/dashboard/src/hooks/use-event-stream.ts lines 80-87 (start event handling increments counter and uses it for key) and lines 106-111 (end event handling uses current counter value for key lookup) at REVIEWED_COMMIT

[macroscopeapp]

🟢 Low components/RunGroup.tsx:89

When group.totalDurationMs is 0, the expression group.totalDurationMs || undefined coerces 0 to undefined, causing formatDuration to return "..." instead of "0ms" for runs that completed in 0 milliseconds. Consider using group.totalDurationMs ?? undefined or explicitly handling the zero case.

-        <span className="run-group-duration">{formatDuration(group.totalDurationMs || undefined)}</span>
+        <span className="run-group-duration">{formatDuration(group.totalDurationMs ?? undefined)}</span>

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/dashboard/src/components/RunGroup.tsx around line 89:

When `group.totalDurationMs` is `0`, the expression `group.totalDurationMs || undefined` coerces `0` to `undefined`, causing `formatDuration` to return `"..."` instead of `"0ms"` for runs that completed in 0 milliseconds. Consider using `group.totalDurationMs ?? undefined` or explicitly handling the zero case.

Evidence trail:
packages/workflow-executor/dashboard/src/components/RunGroup.tsx line 89 shows `formatDuration(group.totalDurationMs || undefined)`. packages/workflow-executor/dashboard/src/utils.ts lines 21-26 show formatDuration returns '...' for undefined and '${ms}ms' for values < 1000 (including 0). JavaScript's || operator treats 0 as falsy, so `0 || undefined` returns `undefined`.

[macroscopeapp]

🟢 Low src/utils.ts:3

currentAttempt returns pair.attempts[pair.attempts.length - 1], which is undefined when attempts is empty (index -1). The return type declares PairAttempt but callers like currentAttempt(p).status will crash with Cannot read properties of undefined (reading 'status') if any EventPair has an empty attempts array. Consider guarding against empty arrays or updating the return type to PairAttempt | undefined and handling that case in callers.

+export function currentAttempt(pair: EventPair): PairAttempt | undefined {
+  return pair.attempts[pair.attempts.length - 1];
+}

Also found in 1 other location(s)

packages/workflow-executor/dashboard/src/components/EventStream.tsx:34

Potential crash if pair.attempts is empty: currentAttempt(p).status on line 34 will throw when accessing .status on undefined (returned when attempts.length === 0). The code at line 36 uses optional chaining (p.attempts[0]?.startData.runId), suggesting the developer considers empty attempts arrays possible, but line 34 lacks the same protection. The call path is: pairs from useEventStream() → pairs.filter() → currentAttempt(p) returns undefined → .status throws.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/dashboard/src/utils.ts around lines 3-5:

`currentAttempt` returns `pair.attempts[pair.attempts.length - 1]`, which is `undefined` when `attempts` is empty (index -1). The return type declares `PairAttempt` but callers like `currentAttempt(p).status` will crash with `Cannot read properties of undefined (reading 'status')` if any `EventPair` has an empty `attempts` array. Consider guarding against empty arrays or updating the return type to `PairAttempt | undefined` and handling that case in callers.

Evidence trail:
packages/workflow-executor/dashboard/src/utils.ts lines 3-5 (REVIEWED_COMMIT) - function implementation with return type `PairAttempt`; packages/workflow-executor/dashboard/src/types.ts line 20 (REVIEWED_COMMIT) - `attempts: PairAttempt[]` allows empty arrays; packages/workflow-executor/dashboard/src/utils.ts line 35 (REVIEWED_COMMIT) - caller `currentAttempt(p).status` would crash if undefined; packages/workflow-executor/dashboard/src/hooks/use-event-stream.ts lines 113, 142 (REVIEWED_COMMIT) - current producers create non-empty arrays but this isn't type-enforced

Also found in 1 other location(s):
- packages/workflow-executor/dashboard/src/components/EventStream.tsx:34 -- Potential crash if `pair.attempts` is empty: `currentAttempt(p).status` on line 34 will throw when accessing `.status` on `undefined` (returned when `attempts.length === 0`). The code at line 36 uses optional chaining (`p.attempts[0]?.startData.runId`), suggesting the developer considers empty attempts arrays possible, but line 34 lacks the same protection. The call path is: `pairs` from `useEventStream()` → `pairs.filter()` → `currentAttempt(p)` returns `undefined` → `.status` throws.