chore: effect rpc and layer based startup

[juliusmarminge]

What Changed

Why

UI Changes

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Refactors core server startup and WebSocket request handling to a new Effect RpcServer/HttpRouter composition, so regressions could break connectivity or endpoint behavior. Adds new path/attachment handling and command normalization that touches filesystem writes and validation logic.

Overview
Migrates the server’s WebSocket request/response handling from the legacy wsServer.ts switch/envelope path to Effect RPC routes in apps/server/src/ws.ts, wiring many existing WS_METHODS/orchestration procedures into a shared WsRpcGroup with typed errors and a new integration-heavy server.test.ts.

Restructures startup into a layer-based CLI entrypoint (src/bin.ts + src/cli.ts) and a new server.ts that composes HTTP routes (health, static/dev redirect, attachments) plus the WebSocket RPC route, and tightens filesystem safety via resolveWorkspaceWritePath and orchestration command normalization for attachment persistence.

Also centralizes several error types by re-exporting them from @t3tools/contracts, updates package bin/start scripts accordingly, and adds a .plans/ws-rpc-endpoint-port-plan.md plus formatter ignore for .reference.

^{Written by Cursor Bugbot for commit e3ac9ed. This will update automatically on new commits. Configure here.}

Note

Replace WebSocket request handling with Effect RPC layer and restructure server startup

• Introduces a typed WebSocket RPC API at /ws via WsRpcLayer in ws.ts, covering orchestration, git, terminal, project file ops, keybindings, and shell open. Contracts are defined in the new wsRpc.ts.
• Replaces the previous ServerLive service/layer pattern with ServerLayer (a Layer.effectDiscard) and adds a CLI entrypoint in bin.ts with flag/env-based config resolution in cli.ts.
• Moves HTTP routes (health, attachments, static/dev redirect) into dedicated layers in http.ts, assembled in server.ts.
• Adds structured error types across contracts (GitManagerServiceError, TerminalError, OrchestrationDispatchCommandError, OpenError, etc.) used as typed RPC error channels.
• Adds a reference server implementation under .reference/server/ as a working example of the Effect RPC + WebSocket pattern.
• Risk: WebSocket requests previously handled in-process now return a RouteRequestError; clients must migrate to the /ws RPC endpoint.

📊 Macroscope summarized e3ac9ed. 38 files reviewed, 5 issues evaluated, 2 issues filtered, 1 comment posted

🗂️ Filtered Issues

.reference/server/src/model-store.ts — 0 comments posted, 1 evaluated, 1 filtered

• line 218: Race condition in subscribe: Events published between catchup stream completion and live stream subscription start will be lost. Stream.concat(catchup, live) runs catchup first (line 210-212), and only after it completes does live (line 214-216) subscribe to eventsPubSub via Stream.fromPubSub. Any events published to eventsPubSub during this gap (e.g., by concurrent append calls on line 202) will not be delivered to the subscriber. [ Out of scope (triage) ]

packages/contracts/src/keybindings.test.ts — 0 comments posted, 2 evaluated, 1 filtered

• line 53: Schema.decodeUnknownExit returns an Exit value directly, not an Effect. Using yield* on an Exit inside Effect.gen will fail because Exit is not a yieldable Effect. The code should either use Schema.decodeUnknownEffect (which returns an Effect) or wrap the Exit with something like Effect.fromExit. [ Failed validation ]

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ad4ffdd9-8191-41b7-be4b-bfa933c1188a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch effect-http-router

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Dev URL redirect drops request path and query
  • Fixed the redirect to construct a new URL from the request's pathname and search params against the dev origin, and updated the test to assert the correct behavior.

Or push these changes by commenting:

@cursor push 089fb595df

Preview (089fb595df)

diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -90,7 +90,8 @@
 
     const config = yield* ServerConfig;
     if (config.devUrl) {
-      return HttpServerResponse.redirect(config.devUrl.href, { status: 302 });
+      const devTarget = new URL(`${url.pathname}${url.search}`, config.devUrl);
+      return HttpServerResponse.redirect(devTarget.href, { status: 302 });
     }
 
     if (!config.staticDir) {

diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -266,7 +266,7 @@
       const response = yield* Effect.promise(() => fetch(url, { redirect: "manual" }));
 
       assert.equal(response.status, 302);
-      assert.equal(response.headers.get("location"), "http://127.0.0.1:5173/");
+      assert.equal(response.headers.get("location"), "http://127.0.0.1:5173/foo/bar");
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );

[cursor]

Dev URL redirect drops request path and query

High Severity

The dev URL redirect uses config.devUrl.href without appending the incoming request's pathname or search params. Every GET request (e.g. /settings?tab=general) redirects to the dev server root (http://127.0.0.1:5173/) instead of the matching route (http://127.0.0.1:5173/settings?tab=general). The reference implementation correctly constructs new URL(url.pathname + url.search, origin). The test at line 269 asserts the broken behavior, masking the regression.

Additional Locations (1)

• apps/server/src/server.test.ts#L268-L269

 

[macroscopeapp]

🟡 Medium src/wsTransport.ts:132

When handler is not a function, WsTransportStreamMethodError is caught at line 132 and retried forever via Effect.forever. A non-existent method name will never become valid, so this creates an infinite loop that spams warnings every retryDelayMs. Consider checking whether the error is a permanent failure (like an unknown method) before retrying, or restructure so that method validation happens once outside the retry loop.

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

In file apps/web/src/wsTransport.ts around line 132:

When `handler` is not a function, `WsTransportStreamMethodError` is caught at line 132 and retried forever via `Effect.forever`. A non-existent method name will never become valid, so this creates an infinite loop that spams warnings every `retryDelayMs`. Consider checking whether the error is a permanent failure (like an unknown method) before retrying, or restructure so that method validation happens once outside the retry loop.

Evidence trail:
apps/web/src/wsTransport.ts lines 115-143 at REVIEWED_COMMIT: Line 115 gets handler from client methods, lines 116-118 return `Effect.fail(new WsTransportStreamMethodError({ method }))` if handler is not a function, lines 131-142 catch ALL errors (no filtering) and log warning + sleep, line 143 applies `Effect.forever` causing infinite retries.