Skip to content

Harden server Effect error handling and normalize service/runtime wiring#95

Merged
juliusmarminge merged 8 commits intomainfrom
codething/a38b78be
Feb 27, 2026
Merged

Harden server Effect error handling and normalize service/runtime wiring#95
juliusmarminge merged 8 commits intomainfrom
codething/a38b78be

Conversation

@juliusmarminge
Copy link
Copy Markdown
Member

@juliusmarminge juliusmarminge commented Feb 27, 2026

Summary

  • Hardened async flows across server/integration code by replacing untyped promise failures with typed Schema.TaggedError Effect errors.
  • Improved orchestration/runtime lifecycle handling (startup, wait/timeout, shutdown/dispose) with explicit error mapping and safer scope management.
  • Updated Effect imports/usages for current APIs (for example NodeServices import style and instanceof invariant checks).
  • Normalized many service tag identifiers from t3/... names to concise domain-scoped names (for example server/*, git/*, checkpointing/*).
  • Refined Git/keybindings/orchestration/terminal tests and formatting, and adjusted open/module loading error handling.
  • Included CLI ergonomics work to use Cursor --goto file targets with line/column.

Testing

  • Backend test coverage was updated in affected areas (integration and layer tests for orchestration, provider, git, terminal, and keybindings).
  • Not run (PR content authored from provided commit/diff context only).

Note

Medium Risk
Touches server startup/WebSocket routing and orchestration integration harness runtime wiring; behavior should be unchanged but error mapping and failure propagation paths are modified and could surface new failures or alter shutdown/start semantics.

Overview
Hardens async/server flows by replacing untyped promise failures with typed Schema.TaggedErrorClass errors and explicit Effect error mapping. Integration harness waiting now times out with WaitForTimeoutError, runtime service loading/starting is wrapped via tryRuntimePromise (OrchestrationHarnessRuntimeError), and sleeps switch to Effect.sleep.

Makes server lifecycle failures explicit and safer to handle. createServer now fails with ServerLifecycleError, maps auto-bootstrap and HTTP listen errors into it, tightens stopSignal typing, and wraps projects.searchEntries failures into a RouteRequestError instead of leaking raw promise rejections.

Normalizes error checks and test typing across git/keybindings/orchestration. Uses Schema.is(...) instead of instanceof for tagged errors, tightens effect error types in git layers/tests (including fake gh failures), switches orchestration projector decoding to sync Schema.decodeUnknownSync wrapped in Effect.try, and disables Turbo test caching.

Written by Cursor Bugbot for commit be2bb4f. This will update automatically on new commits. Configure here.

Note

Harden server error handling by introducing structured tagged errors and wiring runtime/service flows to Effect-based failures across server startup, orchestration harness, and test utilities

Introduce tagged errors for timeouts and runtime failures, normalize schema-tag checks, and convert server lifecycle and route handling to ServerLifecycleError/RouteRequestError; refactor waits and sleeps to Effect.sleep/Schedule and wrap dynamic imports and promises with Effect.tryPromise in apps/server/integration/OrchestrationEngineHarness.integration.ts, apps/server/src/wsServer.ts, and related helpers.

📍Where to Start

Start with createServer in apps/server/src/wsServer.ts, then review makeOrchestrationIntegrationHarness and waitFor in apps/server/integration/OrchestrationEngineHarness.integration.ts.

Macroscope summarized be2bb4f.

Summary by CodeRabbit

  • Refactor

    • Standardized error handling throughout server infrastructure with improved type safety and consistent error reporting.
    • Migrated promise-based operations to structured effect-based error handling for better reliability.
  • Tests

    • Updated test infrastructure and error validation patterns to align with improved error handling system.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Feb 27, 2026

Warning

Rate limit exceeded

@juliusmarminge has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between dbff078 and be2bb4f.

📒 Files selected for processing (13)
  • apps/server/integration/OrchestrationEngineHarness.integration.ts
  • apps/server/integration/orchestrationEngine.integration.test.ts
  • apps/server/src/git/Layers/CodexTextGeneration.ts
  • apps/server/src/git/Layers/GitManager.test.ts
  • apps/server/src/git/Layers/GitService.test.ts
  • apps/server/src/git/Layers/GitService.ts
  • apps/server/src/keybindings.test.ts
  • apps/server/src/open.ts
  • apps/server/src/orchestration/projector.ts
  • apps/server/src/serverLayers.ts
  • apps/server/src/wsServer.test.ts
  • apps/server/src/wsServer.ts
  • turbo.json

Walkthrough

Centralizes runtime Promise error handling via new Schema-tagged runtime errors and tryRuntimePromise wrappers, updates wait/sleep behavior, adds conditional --goto handling for editor launches, widens error typing in Git tests, introduces a Pty initialization error, normalizes WS error responses, and tweaks chat code font sizes.

Changes

Cohort / File(s) Summary
Orchestration runtime & integration harness
apps/server/integration/OrchestrationEngineHarness.integration.ts
Adds OrchestrationHarnessRuntimeError, WaitForTimeoutError, and tryRuntimePromise; converts startup/shutdown Promise uses to tryRuntimePromise(...).pipe(Effect.orDie), standardizes waitFor timeout mapping, and replaces ad-hoc sleeps with Effect.sleep.
Integration test timeout handling
apps/server/integration/orchestrationEngine.integration.test.ts
Adds IntegrationWaitTimeoutError Schema-tagged error; replaces Promise sleep with Effect.sleep; on wait timeout dies with the tagged error.
Git test scaffolding
apps/server/src/git/Layers/GitManager.test.ts
Widens error typings to GitCommandError/GitHubCliError and TextGenerationError; removes normalizeGhError; tests now construct and assert specific error instances/messages directly.
Keybindings test
apps/server/src/keybindings.test.ts
Makes runtime validity assertion robust by comparing String(entry.command) instead of direct equality to a string.
Editor launch & open utility + tests
apps/server/src/open.ts, apps/server/src/open.test.ts
Adds LINE_COLUMN_SUFFIX_PATTERN and shouldUseGotoFlag to conditionally append --goto for cursor targets; wraps dynamic open import with Effect.tryPromise mapping failures to OpenError; adds tests for --goto behavior.
Terminal PTY adapter & service
apps/server/src/terminal/Layers/NodePTY.ts, apps/server/src/terminal/Services/PTY.ts
Introduces PtyAdapterInitializationError (Schema-tagged) and maps dynamic node-pty load failures to this error; exports the new error type from PTY service.
WebSocket handler error normalization
apps/server/src/wsServer.ts
Changes projectsSearchEntries handling to use Effect.tryPromise; on failure returns a RouteRequestError that includes the original cause message instead of propagating raw errors.
UI — chat code typography
apps/web/src/index.css
Sets inline code font-size to 0.75rem for .chat-markdown :not(pre) > code and 0.875rem for .chat-markdown pre code.

Sequence Diagram(s)

mermaid
sequenceDiagram
autonumber
participant Harness as OrchestrationHarness
participant Scope as Scope
participant Engine as Engine
participant Reactor as Reactor
participant Services as Services
participant Store as CheckpointStore
Note over Harness: Startup using tryRuntimePromise + orDie
Harness->>Scope: Scope.make()
Harness->>Engine: tryRuntimePromise(start engine)
Engine-->>Harness: started / error
Harness->>Reactor: tryRuntimePromise(start reactor)
Reactor-->>Harness: started / error
Harness->>Services: tryRuntimePromise(init services...)
Services-->>Harness: ready / error
Harness->>Store: tryRuntimePromise(open checkpoint store)
Store-->>Harness: opened / error
alt any error
Harness->>Harness: orDie(error) -> abort
end
Note over Harness: Shutdown mirrors startup with tryRuntimePromise disposals

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The PR title accurately summarizes the main objectives: hardening Effect error handling and normalizing service/runtime wiring across the codebase, which aligns with the extensive changes to error types, service definitions, and runtime lifecycle management documented in the changeset.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch codething/a38b78be

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

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/server/integration/OrchestrationEngineHarness.integration.ts`:
- Around line 345-356: The current teardown uses sequential tryRuntimePromise
calls (invoking providerService.stopAll, Scope.close, and runtime.dispose) and
then runs fs.rmSync(rootDir...), but if any of those throws the cleanup line
never runs; wrap the whole shutdown sequence in an Effect that guarantees
filesystem cleanup by using Effect.ensuring (or a finally-style combinator) so
fs.rmSync(rootDir, { recursive: true, force: true }) always runs regardless of
failures; specifically, create an Effect that executes the existing
tryRuntimePromise(...) calls (references: tryRuntimePromise,
providerService.stopAll, runtime.runPromise, Scope.close, runtime.dispose) and
attach .ensuring(Effect.sync(() => fs.rmSync(rootDir, { recursive: true, force:
true }))) to it so the temp dir is removed even if
stopAll/Scope.close/runtime.dispose fails.

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5748a99 and 1bba0b3.

📒 Files selected for processing (9)
  • apps/server/integration/OrchestrationEngineHarness.integration.ts
  • apps/server/integration/orchestrationEngine.integration.test.ts
  • apps/server/src/git/Layers/GitManager.test.ts
  • apps/server/src/keybindings.test.ts
  • apps/server/src/open.test.ts
  • apps/server/src/open.ts
  • apps/server/src/terminal/Layers/NodePTY.ts
  • apps/server/src/wsServer.ts
  • apps/web/src/index.css

Comment thread apps/server/integration/OrchestrationEngineHarness.integration.ts Outdated
Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/server/integration/OrchestrationEngineHarness.integration.ts`:
- Line 259: Scope.make is being called with a string; update the call to pass
the proper ExecutionStrategy enum/value instead of "sequential". Locate the
Scope.make(...) call (symbol: Scope.make) and replace the string argument with
the ExecutionStrategy token from the Effect API (e.g.,
ExecutionStrategy.sequential) or remove the argument entirely to use the
default; ensure you import or reference ExecutionStrategy so the value resolves
correctly.

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1bba0b3 and 5a542e8.

📒 Files selected for processing (2)
  • apps/server/integration/OrchestrationEngineHarness.integration.ts
  • apps/server/integration/orchestrationEngine.integration.test.ts

Comment thread apps/server/integration/OrchestrationEngineHarness.integration.ts
- Replace raw `Effect.promise`/generic errors with `Effect.tryPromise` and tagged schema errors
- Improve orchestration harness/test reliability with explicit timeout/runtime error types
- Tighten related tests and error assertions to match typed error flows
- replace custom Promise-based sleep helpers with `Effect.sleep`
- remove now-unused integration sleep error class and harness error mapping
- Use domain errors directly in GitManager tests (`GitHubCliError`, `TextGenerationError`)
- Remove fixture-only GH error normalization in test scaffolding
- Introduce shared `PtyAdapterInitializationError` and use it in NodePTY adapter init
juliusmarminge and others added 5 commits February 26, 2026 19:07
- Use generic type parameter for stream errors instead of unknown
- Type ServerShape errors as ServerLifecycleError instead of unknown
- Add error mapping for autoBootstrapProject and httpServerListen
- Type makeServerProviderLayer with ProviderUnsupportedError
- Use Effect.try with decodeUnknownSync in projector to avoid unknown requirements
- Fix test layer types from any/unknown to never

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@juliusmarminge juliusmarminge merged commit 0cfaf73 into main Feb 27, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant