refactor: extract session event stream

[ColeMurray]

Summary

• Extract session replay/history behavior from SessionDO into SessionEventStream
• Centralize EventRow projection for WebSocket replay/history and HTTP event listing
• Re-export event list response types from shared instead of maintaining local duplicates

Why

SessionDO was carrying Session Event Stream replay and paginated history projection inline. Moving this into a focused class reduces Durable Object surface area and gives the event stream behavior its own testable interface without adding callback-heavy dependencies.

Validation

• npm test -w @open-inspect/control-plane -- src/session/event-stream.test.ts src/session/services/message.service.test.ts src/session/http/handlers/messages.handler.test.ts
• npm run build -w @open-inspect/shared
• npm run test:integration -w @open-inspect/control-plane -- test/integration/websocket-client.test.ts
• npm run typecheck -w @open-inspect/control-plane
• npx prettier --check packages/control-plane/src/session/durable-object.ts packages/control-plane/src/session/event-stream.ts packages/control-plane/src/session/event-stream.test.ts packages/control-plane/src/session/http/handlers/messages.handler.ts packages/control-plane/src/session/http/handlers/messages.handler.test.ts packages/control-plane/src/session/services/message.service.ts packages/control-plane/src/session/services/message.service.test.ts packages/control-plane/src/types.ts
• npx eslint packages/control-plane/src/session/durable-object.ts packages/control-plane/src/session/event-stream.ts packages/control-plane/src/session/event-stream.test.ts packages/control-plane/src/session/http/handlers/messages.handler.ts packages/control-plane/src/session/http/handlers/messages.handler.test.ts packages/control-plane/src/session/services/message.service.ts packages/control-plane/src/session/services/message.service.test.ts packages/control-plane/src/types.ts
• git diff --check

Summary by CodeRabbit

• Refactor

  • Refactored session event handling and replay data sourcing to improve modularity and code organization.
  • Consolidated event response types to the shared package for better reusability.

• Tests

  • Added comprehensive test suite for session event stream functionality.

[github-actions]

Terraform Validation Results

Step	Status
Format	✅
Init	✅
Validate	✅

Note: Terraform plan was skipped because secrets are not configured. This is expected for external contributors. See docs/GETTING_STARTED.md for setup instructions.

Pushed by: @ColeMurray, Action: pull_request

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces a new SessionEventStream class that centralizes event replay, history paging, and event listing over SessionRepository. SessionDO now uses it for WebSocket replay and fetch_history responses. MessageService delegates listEvents to it. EventResponse and ListEventsResponse are moved from local declarations to re-exports from @open-inspect/shared.

Changes

SessionEventStream abstraction

Layer / File(s)	Summary
Shared type reorganization and EventStream contracts packages/control-plane/src/types.ts, packages/control-plane/src/session/event-stream.ts	Removes locally declared EventResponse and ListEventsResponse interfaces and re-exports them from @open-inspect/shared. Declares EventStreamCursor, SessionReplay, SessionHistoryPage, SessionEventStreamRepository, and SessionEventListRequest in the new module.
SessionEventStream implementation packages/control-plane/src/session/event-stream.ts	Implements SessionEventStream with getReplay, getHistoryPage (heartbeat exclusion, clamped limit, cursor mapping), and listEvents (EventRow→EventResponse with encoded cursor). Adds helpers parseSandboxEvents, cursorFromRow, toEventResponse, and clampHistoryLimit.
SessionEventStream tests packages/control-plane/src/session/event-stream.test.ts	Adds full Vitest coverage for all three public methods, including default limits, cursor forwarding, limit clamping, malformed-JSON resilience, and HTTP response projection.
SessionDO wired to SessionEventStream packages/control-plane/src/session/durable-object.ts	Adds lazy eventStream getter on SessionDO, replaces getReplayData() with this.eventStream.getReplay() during WebSocket subscribe, removes the deleted method, and routes fetch_history through this.eventStream.getHistoryPage.
MessageService and HTTP handler delegation packages/control-plane/src/session/services/message.service.ts, packages/control-plane/src/session/http/handlers/messages.handler.ts, packages/control-plane/src/session/services/message.service.test.ts, packages/control-plane/src/session/http/handlers/messages.handler.test.ts	MessageService constructs a SessionEventStream and delegates listEvents to it; ListEventsRequest becomes a type alias for SessionEventListRequest. HTTP handler returns the service result directly. Tests updated to reflect camelCased event shapes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ColeMurray/background-agents#695: Refactors the same fetch_history/history paging path in durable-object.ts to use getEventTimelinePage with heartbeat filtering — the direct predecessor to routing that logic through SessionEventStream.

Poem

🐇 A stream was born to carry events along,
No more inline parsing where logic didn't belong.
Replay and history, neatly packed away,
The durable object hops through code with grace today.
Cursors are clamped, bad JSON softly skipped,
And camelCase fields ensure nothing is tripped! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: extract session event stream' accurately summarizes the main change: extracting session event stream behavior into a dedicated class, reducing SessionDO complexity.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/control-plane-event-stream

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/control-plane/src/session/event-stream.ts`:
- Around line 101-109: The toEventResponse function lacks error handling for the
JSON.parse call on line 105, which will crash the listEvents request if
event.data contains invalid JSON. Add a try-catch block around the JSON.parse
statement in toEventResponse to handle parse failures, matching the error
handling pattern used in parseSandboxEvents. Either catch the error and return
null (filtering nulls in listEvents), or catch and provide a fallback value for
the data field to prevent the entire request from crashing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 08cc99f7-39e6-45e4-9a45-17c48f852caf

📥 Commits

Reviewing files that changed from the base of the PR and between a2ef0be and eead20b.

📒 Files selected for processing (8)

• packages/control-plane/src/session/durable-object.ts
• packages/control-plane/src/session/event-stream.test.ts
• packages/control-plane/src/session/event-stream.ts
• packages/control-plane/src/session/http/handlers/messages.handler.test.ts
• packages/control-plane/src/session/http/handlers/messages.handler.ts
• packages/control-plane/src/session/services/message.service.test.ts
• packages/control-plane/src/session/services/message.service.ts
• packages/control-plane/src/types.ts