Connecting WebRPC to Wrangler Dev

Typed Design Spec

Title
Cap’n Web RPC integration for OpenCode share service over Wrangler dev

Context
I reviewed:

• Your current share client API in packages/opencode/src/share/share-next.ts
• The cloudsession Worker RPC entry in packages/cloudsession/src/index.tsx
• The RPC contract and implementation in both packages
• cloudsession tests
• capnweb README and repo research, including visible issues/PRs/tests/docs

The intended design appears to be:

• packages/opencode creates a share RPC stub once, then reuses it
• The client talks to cloudsession over Cap’n Web
• The server should accept RPC over Worker transport, ideally including WebSocket-capable sessions
• You want this to work against local wrangler dev

Goals

• Make the existing share RPC API connect correctly to a local Wrangler Worker
• Preserve a type-safe shared contract
• Support Cap’n Web semantics correctly on Workers
• Keep the transport choice explicit and testable

Non-Goals

• I am not implementing the fix here
• I am not performing git operations
• I am not asserting production deployment behavior beyond what is implied by the code and capnweb docs

Architecture Summary

Modules and boundaries

• Client:
  • packages/opencode/src/share/share-next.ts
  • Creates a single cached Cap’n Web session and calls createShare, syncShare, deleteShare
• Shared contract:
  • packages/opencode/src/share/rpc-contract.ts
  • packages/cloudsession/src/rpc-contract.ts
• Server:
  • packages/cloudsession/src/rpc.ts implements ShareRpcImpl extends RpcTarget
  • packages/cloudsession/src/index.tsx exposes HTTP/API/UI routes and the RPC route
• Local runtime:
  • packages/cloudsession/wrangler.jsonc

Current transport design in code

• Client currently uses newHttpBatchRpcSession<ShareRpc>(new Request(${url}/rpc/share, ...))
• Server currently mounts rpc.all("/rpc", ...) and calls newWorkersWebSocketRpcResponse(req, shareSession)

This is the main contract mismatch.

Types and Data Models

Shared RPC interface

export interface ShareRpc extends RpcTarget {
  createShare: (sessionID: string, initialData?: SyncData[]) => Promise<SyncInfo>
  syncShare: (shareID: string, secret: string, data: SyncData[]) => Promise<{ success: boolean; syncCount: number }>
  deleteShare: (shareID: string, secret: string) => Promise<{ success: boolean }>
  probeValue: (input: ProbeValueInput) => ProbeValueOutput
  probeCallback: (cb: ProbeCallback) => Promise<string>
}

Transport model invariants

1. If client uses newHttpBatchRpcSession(), server must accept HTTP batch RPC on the same route.
2. If client uses newWebSocketRpcSession(), server must expose a WebSocket upgrade endpoint.
3. Route path must match exactly.
4. Worker handler must not eagerly consume or corrupt the request body before Cap’n Web handles it.
5. Authentication for browser WebSockets cannot rely on custom headers; auth should be in-band or via URL/token strategy. For CLI/non-browser HTTP, headers are fine.

Relevant Cap’n Web invariants from research

• RpcTarget methods are remotely callable; instance fields are not
• WebSocket mode is long-lived and supports bidirectional callbacks naturally
• HTTP batch mode supports pipelining within a batch, but is request/response-scoped
• Workers integration is intended to “just work” with newWorkersRpcResponse()
• Disposal matters for long-lived WebSocket sessions
• Browser WebSocket auth should generally be in-band, not header-based

Public Interfaces and Contracts

Current client entry
ShareNext.getRpcSession(): Promise<ReturnType<typeof newHttpBatchRpcSession<ShareRpc>>>

Current server entry
rpc.all("/rpc", handler) where handler returns newWorkersWebSocketRpcResponse(req, shareSession)

Contract violations

1. Path mismatch
   • Client calls /rpc/share
   • Server exposes /rpc
2. Transport mismatch
   • Client uses HTTP batch session
   • Server returns WebSocket RPC response helper
3. Suspicious request/response misuse in handler
   • console.log(req.json())
   • console.log(response.json())
     These are not valid diagnostic operations for this flow and risk incorrect async/body handling assumptions.
4. Interface implementation mismatch
   • ShareRpc declares createShare
   • ShareRpcImpl currently defines create
     So the method name does not satisfy the exported contract.

Evidence

• Client path: packages/opencode/src/share/share-next.ts:45
• Client transport: packages/opencode/src/share/share-next.ts:44
• Server route: packages/cloudsession/src/index.tsx:50
• Server helper: packages/cloudsession/src/index.tsx:87
• Impl method name: packages/cloudsession/src/rpc.ts:27
• Contract method name: packages/cloudsession/src/rpc-contract.ts:46

Error Model

Structured error taxonomy

type RpcIntegrationError =
  | { type: "RouteMismatch"; clientPath: string; serverPath: string }
  | { type: "TransportMismatch"; client: "http-batch" | "websocket"; server: "http-batch" | "websocket" | "mixed" }
  | { type: "MethodContractMismatch"; interfaceMethod: string; implementationMethod: string }
  | { type: "Unauthorized"; mechanism: "header" | "in-band" | "none" }
  | { type: "WorkerRuntimeFailure"; stage: "startup" | "upgrade" | "request" | "rpc-call"; message: string }

Observed/likely failures

• HTTP request to /rpc/share -> 404 or route miss
• HTTP batch client against WebSocket-only handler -> protocol failure / unexpected response shape
• Successful session creation followed by missing method call -> remote property/method resolution failure on createShare
• Local dev confusion due to invalid logging / request handling around Cap’n Web response construction

Example Usage

Happy path: HTTP batch transport

const rpc = newHttpBatchRpcSession<ShareRpc>(
  new Request(`${url}/rpc`, { headers })
)

const info = await rpc.createShare(sessionID, initialData)
await rpc.syncShare(info.id, info.secret, items)
await rpc.deleteShare(info.id, info.secret)

Happy path: WebSocket transport

using rpc = newWebSocketRpcSession<ShareRpc>(`${wsUrl}/rpc`)
const info = await rpc.createShare(sessionID, initialData)

If you want “create websocket based RPC stub on first connect”

• Then the client should explicitly use newWebSocketRpcSession
• The server should expose a WebSocket-capable RPC endpoint on the same path
• You should define lifecycle/disposal/reconnect behavior explicitly

Deep Findings from capnweb Research

Relevant capnweb behavior

• On Workers, preferred generic server helper is newWorkersRpcResponse(request, api) when you want one route to accept both HTTP batch and WebSocket
• For browser WebSocket clients, capnweb explicitly recommends in-band authentication, since browsers cannot set arbitrary headers on WebSocket upgrade
• Workers interop is best with compatible compat date / flags; your Worker already uses compatibility_date: "2026-02-08", which is favorable

Important capnweb limitations relevant here

• Runtime type validation is not built in
• Disposal/resource ownership matters for long-lived WebSocket sessions
• Some open issues exist around type sharpness and reference counting, but none of those are the primary blocker here
• The current blocker is your repo-side integration mismatch, not an inherent capnweb limitation

Wrangler Dev Runtime Assessment

What can be concluded safely

• The Worker config is plausible for local Wrangler dev:
  • packages/cloudsession/wrangler.jsonc
  • compat date: 2026-02-08
  • local port: 8787
• capnweb is designed to run on Workers
• The current code is not internally consistent enough to expect a successful local RPC connection

Most probable runtime result
Even before nuanced runtime issues, the connection fails for deterministic design reasons:

1. wrong route
2. wrong transport
3. wrong method name

So “successfully connect to wrangler dev runtime” is blocked at the API contract level first.

Correctness-First Review

Summary
The current Cap’n Web integration is blocked by interface and transport mismatches. I would block merge/use of the RPC path in its current state.

Approval Status
Block

Findings

Blockers

1. Route mismatch

• Client calls /rpc/share
• Server exposes /rpc
• This prevents reaching the intended handler.

2. Transport mismatch

• Client creates newHttpBatchRpcSession()
• Server responds using newWorkersWebSocketRpcResponse()
• These are not symmetric endpoints.

3. RPC interface mismatch

• Shared interface requires createShare
• Server implementation exports create
• Client call session.createShare(...) cannot be satisfied by this implementation.

Required Changes
4. Replace ad hoc RPC route design with a single explicit transport contract.
5. Remove invalid console.log(req.json()) / console.log(response.json()) diagnostics from the Cap’n Web handler path.
6. Decide auth model per transport:

• CLI HTTP batch can use header auth
• Browser WebSocket cannot rely on custom headers

Suggestions
7. Prefer newWorkersRpcResponse(req, shareSession) on Workers if you want one endpoint supporting both HTTP batch and WebSocket.
8. Unify on a single shared rpc-contract.ts source or generate one shared package export to prevent drift.
9. Add a manual Wrangler dev smoke test that exercises one probe method and one real share operation.

Suggested Interface/Type Adjustments

Preferred minimal API

export interface ShareRpc extends RpcTarget {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
}

Preferred server handler signature

function handleShareRpc(request: Request, env: Env): Response | Promise<Response>

Preferred transport choice
Option A: single mixed route, simplest

• Client:
  • HTTP batch: newHttpBatchRpcSession<ShareRpc>(new Request(${url}/rpc, ...))
• Server:
  • return newWorkersRpcResponse(req, new ShareRpcImpl(env))

Option B: explicit WebSocket-first route

• Client:
  • newWebSocketRpcSession<ShareRpc>(${wsBase}/rpc)
• Server:
  • route supports WebSocket upgrade properly, or still use newWorkersRpcResponse() if capnweb handles both on one route

I recommend Option A first for correctness and local dev simplicity, unless you specifically need persistent bidirectional callbacks immediately.

Acceptance Criteria

Observable, testable

1. The client and server use the same RPC route path.
2. The transport helper used by the client is compatible with the server helper.
3. ShareRpcImpl exposes all methods declared by ShareRpc, with matching names.
4. A local Wrangler dev smoke test can:
   • call probeValue()
   • call createShare()
   • call syncShare()
   • call deleteShare()
5. If WebSocket transport is chosen:
   • a probeCallback() round-trip succeeds over the persistent session
   • session disposal behavior is defined and manually verified
6. Unauthorized requests fail deterministically with the chosen auth model.
7. No route handler logs or consumes request bodies in a way that interferes with Cap’n Web processing.

Delegation Plan

Implementation task

1. Normalize RPC route + helper choice

• Choose one route path, ideally /rpc
• Choose one server helper, preferably newWorkersRpcResponse()
• Align client session constructor to the same route/transport
  Acceptance:
• one route string shared by client/server config
• one transport contract documented in code comments
• successful local call to probeValue

2. Fix implementation/interface mismatch

• Rename or add method so ShareRpcImpl satisfies createShare
  Acceptance:
• typecheck passes with ShareRpcImpl structurally matching ShareRpc
• client createShare() succeeds end-to-end

3. Remove unsafe/incorrect diagnostics

• Remove req.json() / response.json() logging from RPC route
  Acceptance:
• no request/response body misuse in RPC handler
• handler remains side-effect minimal

4. Decide auth contract

• For CLI-only HTTP batch: retain header auth
• For browser WebSocket support: define in-band auth RPC or token query strategy
  Acceptance:
• auth behavior documented
• unauthorized/manual authorized cases verified

Tests task

1. Add manual/smoke tests in packages/cloudsession

• HTTP batch probe
• create/sync/delete round-trip
• if WebSocket chosen, callback probe
  Acceptance:
• test instructions runnable from package dir
• failures clearly identify route/transport/method mismatch

2. Add contract drift test

• assert server implementation method names match ShareRpc
  Acceptance:
• changing contract without impl causes failing test or typecheck

3. Add Wrangler dev manual script/instructions
   Acceptance:

• exact command sequence documented
• includes expected status/result for success

Docs task

1. Document share RPC transport

• chosen route
• chosen transport
• auth model
• local Wrangler dev workflow
  Acceptance:
• one concise developer-facing doc section or package README update
• includes curl/fetch/WebSocket example as appropriate

Git task

1. Branch name

• fix/cloudsession-capnweb-rpc-alignment

2. Commit scopes

• cloudsession: align capnweb rpc route and transport
• opencode: align share client rpc endpoint
• docs: document local wrangler rpc smoke test
  Acceptance:
• commits separated by concern
• no unrelated formatting churn

Risks & Open Questions

Risks

• If you truly need persistent WebSocket semantics now, auth and disposal need explicit design
• packages/opencode uses capnweb@0.4.0 while packages/cloudsession uses capnweb@0.6.1; version skew may introduce subtle behavior differences
• Duplicated contract files increase drift risk

Open questions

1. Do you want the share RPC client to be HTTP batch or persistent WebSocket?
2. Is this client only CLI/server-side, or will a browser consume the same RPC endpoint?
3. Do you need bidirectional callbacks beyond probe testing?
4. Can the repo unify on one capnweb version across both packages?

QA Self-Check Results

• Exhaustiveness: covered route, transport, contract, auth, worker runtime, version skew
• Contracts: explicit mismatches identified
• Effects: noted request-body handling and session lifecycle concerns
• Types: method-name mismatch and duplicated contract drift identified
• Compatibility: capnweb Workers guidance aligned with suggested fix
• Security: browser WebSocket auth caveat documented
• Observability: recommended smoke tests and explicit auth/result checks
• Standards: stayed correctness-first and avoided full implementation code
• Delegation: tasks are explicit and testable

Bottom line
The primary reason this does not connect successfully is not Wrangler itself; it is that your current RPC integration is internally inconsistent:

• client path /rpc/share vs server /rpc
• client HTTP batch vs server WebSocket helper
• interface createShare vs implementation create

Fix those first. After that, Wrangler dev should be a meaningful runtime test rather than a guaranteed contract failure.

Yes — and that is the right next move.

Typed Design Spec

Title
Local in-process RPC test for cloudsession, modeled after capnweb-style transport tests

Context
You asked for a local test, similar in spirit to capnweb’s own test cases, especially the Hono/WebSocket-style shape.

From the repo and test-pattern review, the best fit here is not a full external Wrangler socket integration test first. The best correctness-first step is:

• real app/router
• fake Worker bindings
• direct in-process request execution
• protocol-level assertions
• optionally a Worker-native WebSocket upgrade test if the route is truly WebSocket-based

That is very close to the useful part of capnweb’s test style: test the session/transport contract locally and deterministically.

Goals

• Verify the local share RPC route behaves correctly without requiring deployed infra
• Mirror capnweb-style “local transport/session” testing as much as practical
• Keep tests deterministic and package-local
• Prove the route/transport/method contract before trying end-to-end Wrangler dev again

Non-Goals

• Not a browser conformance test
• Not a production networking test
• Not a git/CI change proposal by itself

Recommended Test Strategy

Recommendation
Add a new local test in packages/cloudsession/src/ that exercises the RPC endpoint in-process, using:

• the real Hono/Worker app
• fake R2 binding
• fake Durable Object namespace
• a real Cap’n Web session constructor on the client side only if the server-side route semantics are aligned first

There are two viable patterns.

Pattern A — Preferred first step: in-process Worker RPC route test
This is the safest and most capnweb-aligned local test shape for your repo.

Structure:

1. Create env with in-memory R2 + fake DO namespace
2. Invoke app.fetch(new Request(...), env) directly
3. Hit the exact RPC route you intend to support
4. Assert:
   • route matches
   • response shape/upgrade shape is correct
   • method names on the server are callable
   • probe method works
   • create/sync/delete semantics work once the route is aligned

Pseudo-structure

describe("share rpc local", () => {
  test("probe rpc round-trip", async () => {
    const env = createEnv()
    // exact route under test
    // exact transport under test
    // assert probeValue/probeCallback behavior
  })

  test("create -> sync -> delete over rpc", async () => {
    const env = createEnv()
    // createShare(sessionID, initialData)
    // syncShare(...)
    // deleteShare(...)
    // verify backing store state
  })
})

Pattern B — Optional second step: Worker WebSocket-upgrade-local test
Only do this if you explicitly want a WebSocket RPC route, not HTTP batch.

Structure:

1. Build a Request with upgrade headers
2. Call app.fetch()
3. Assert response is an upgrade response
4. If your test runtime supports Response.webSocket, accept the socket and drive the exchange
5. Verify one actual RPC method call round-trip

This is closer to Cloudflare Worker WebSocket adapter tests, but it is more runtime-sensitive.

Why Pattern A first

• It tests the contract that is currently broken
• It avoids false confidence from “101 upgrade returned”
• It catches the real blockers:
  • route mismatch
  • transport mismatch
  • method mismatch

Correctness Review of Current Test Situation

Summary
Your existing packages/cloudsession/src/rpc.test.ts is not sufficient as proof of local RPC correctness.

Approval Status
Block as a meaningful integration test

Findings

Blockers

1. It does not establish a real verified client/server RPC exchange

• newWebSocketRpcSession("ws://localhost/rpc") is created, but there is no demonstrated in-process binding to the app fetch path.

2. It does not assert the actual share contract

• createShare, syncShare, deleteShare are not exercised.

3. It does not catch the current implementation mismatch

• interface says createShare
• implementation defines create

4. It risks proving only “upgrade-ish response exists”

• that is not the same as “RPC works”

Required Changes

1. Replace the current thin probe test with a protocol-level local RPC test.
2. Test the intended route path exactly.
3. Test the intended transport exactly.
4. Assert the shared interface methods, not just a probe stub.

Public Interfaces and Contracts

Minimal contract to verify locally

interface ShareRpc extends RpcTarget {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
  probeValue(input: ProbeValueInput): ProbeValueOutput
  probeCallback(cb: ProbeCallback): Promise<string>
}

Local test invariants

1. The test must use the same route the client uses.
2. The test must use the same transport the client uses.
3. The implementation must satisfy the shared interface method names exactly.
4. The backing store must reflect create/sync/delete effects.

Best-Fit Concrete Test Plan

Test file
Suggested new file:

• packages/cloudsession/src/rpc.local.test.ts

Test cases

1. probeValue round-trip works over the chosen RPC transport
   Acceptance:

• dates/bytes/nested object are returned in expected transformed shape

2. probeCallback round-trip works
   Acceptance:

• callback passed by reference can be invoked by server and returns expected value

3. createShare stores initial session/index state
   Acceptance:

• returned id/url/secret valid
• R2 fake store contains expected share/ and index/ entries

4. syncShare merges/updates correctly
   Acceptance:

• sync count increments
• message/part/model replacement by ID works
• session diffs append

5. deleteShare removes persisted records
   Acceptance:

• both share/ and index/ keys removed
• further reads fail as expected

6. unauthorized request path, if auth is enabled for RPC
   Acceptance:

• deterministic unauthorized response

Best transport choice for this test
Given current repo state, the simplest useful local test is:

• align server to accept HTTP batch RPC with newWorkersRpcResponse()
• use newHttpBatchRpcSession() in the test client

If you specifically want WebSocket-first parity with capnweb’s persistent session examples, then:

• align route to WebSocket-capable endpoint
• use newWebSocketRpcSession() in the test client
• but this should be step two, not step one

Pitfalls to Avoid

1. Don’t use a “101 response exists” assertion as the main proof
   That only proves upgrade handling, not RPC correctness.

2. Don’t test a different route than the real client uses
   Current mismatch:

• client: /rpc/share
• server: /rpc

3. Don’t mix transports in the test
   If the test client is HTTP batch, the server route must be HTTP batch-compatible.
   If the test client is WebSocket, the server must expose WebSocket RPC semantics.

4. Don’t stop at probe-only tests
   Probe tests are useful but insufficient. You need one real createShare flow.

5. Don’t over-mock the app
   Mock only platform bindings, not the route handler.

Acceptance Criteria

Observable, testable

1. A package-local test can run without external deployment.
2. The test exercises the real cloudsession app/router.
3. The test validates at least one probe RPC and one real share RPC lifecycle.
4. The test would fail on:
   • wrong route
   • wrong transport
   • wrong method name
5. The test is deterministic and isolated per test case.

Delegation Plan

Implementation task
Create a new local RPC test file using the existing createMockR2Bucket() / fake DO style from api.test.ts and index.test.ts.
Acceptance:

• uses package-local fake bindings
• exercises real route handler
• validates real RPC method calls

Implementation task
Before writing the test, decide and normalize one transport contract for the test:

• HTTP batch + newWorkersRpcResponse(), or
• WebSocket + newWorkersWebSocketRpcResponse() / equivalent route handling
  Acceptance:
• one route
• one transport
• one matching client constructor

Tests task
Add the six tests listed above, starting with:

• probeValue
• createShare
  Acceptance:
• failures clearly identify contract mismatch category

Docs task
Add a short developer note describing:

• how to run the local RPC test
• what transport it covers
• what it intentionally does not cover
  Acceptance:
• one concise note in package-local docs or test comments

Git task
Branch:

• test/cloudsession-local-rpc
  Commits:
• cloudsession: add local rpc transport test
• cloudsession: align rpc route and contract for testability
  Acceptance:
• test commit separate from route/contract fix commit

QA Self-Check Results

• Exhaustiveness: covered route, transport, contract, storage effects
• Contracts: explicit
• Effects: isolated fake bindings
• Types: shared interface mismatch called out
• Compatibility: aligned with capnweb/Workers testing approach
• Security: auth path included as optional case
• Observability: failures should pinpoint mismatch source
• Delegation: complete and testable

Bottom line
Yes, we should do that.

But the most correct version is: create a local in-process RPC test modeled after capnweb’s transport/session style, using the real Worker app and fake bindings, and make it prove a real createShare flow — not just an upgrade response.

If you want, next I can write the exact test design as a file-by-file implementation brief for a coding agent.

Correctness-First Review

Summary
Yes — that is a plausible explanation for the current shape of the code, but it exposes an important architectural distinction:

• /ws/:id in index.tsx is the browser live-update channel, proxied to the Durable Object
• /rpc appears intended to be a Cap’n Web RPC endpoint
• those are not automatically the same thing

So if your thought is:

perhaps the stub should connect to the Worker, and then the Worker upgrades/proxies through to the Durable Object

that can be valid, but only if you explicitly design the RPC boundary that way.

Approval Status
Block on assumptions; proceed only with an explicit transport design

Findings

Blockers

1. /ws/:id is not currently an RPC endpoint

• packages/cloudsession/src/index.tsx:435
• It proxies the raw upgraded request to SESSIONS_BROADCAST
• That DO is described as a broadcast/live-update channel, not a ShareRpc implementation

2. The current RPC contract is implemented in ShareRpcImpl, not in the Durable Object

• packages/cloudsession/src/rpc.ts:15
• So even if you tunnel WebSocket upgrade to the DO, that does not by itself expose createShare/syncShare/deleteShare

3. Cap’n Web WebSocket RPC requires the endpoint on the far side of the WebSocket to actually host a Cap’n Web session
   Meaning:

• either the Worker itself hosts the RPC session
• or the DO hosts the RPC session
• but the current /ws/:id DO route looks like ordinary app WebSocket broadcasting, not Cap’n Web RPC session hosting

Required Changes
4. You need to choose one of these architectures explicitly.

Architecture Options

Option A — Keep RPC at the Worker boundary
This is the simplest and most correct first step.

Design

• Client stub connects to Worker RPC route
• Worker hosts ShareRpcImpl
• Worker may internally call Durable Objects as needed
• The DO remains an implementation detail for broadcast/state fanout

Transport choices

• HTTP batch client ↔ newWorkersRpcResponse()
• or WebSocket client ↔ a Worker route that hosts Cap’n Web RPC

Implications

• ShareRpc stays implemented in ShareRpcImpl
• /ws/:id remains unrelated to share RPC
• DO is not the remote main interface; it is just a dependency of ShareRpcImpl

Best when

• you want createShare/syncShare/deleteShare as your main API
• you do not need the DO itself to be the RPC peer

Option B — Move/share RPC session to the Durable Object
This is possible, but a bigger design change.

Design

• Client stub connects to Worker route
• Worker upgrades/proxies to DO
• DO itself hosts the Cap’n Web RPC session
• DO must implement the ShareRpc surface or expose an equivalent main RPC target

Implications

• the DO becomes your RPC server
• you must define how session IDs / share IDs map to DO instances
• createShare becomes awkward unless there is a “root” DO or a Worker bootstrap API
• auth and lifecycle become more complex

Best when

• the DO is the true long-lived authority for the objects you want to call remotely
• you need persistent bidirectional object identity tied to a DO instance

Option C — Split responsibilities cleanly
Likely the best long-term model if you need both RPC and live viewer sockets.

Design

• /rpc = Cap’n Web RPC at Worker boundary
• /ws/:id = app-specific live updates to DO
• Worker ShareRpcImpl may return data or IDs that clients later use with /ws/:id
• No attempt to make /ws/:id also be the Cap’n Web RPC route

This avoids conflating two protocols.

Why your hypothesis matters

What you are noticing is real:

• a Cap’n Web WebSocket stub needs a WebSocket endpoint
• the app already has a WebSocket upgrade route
• so it is tempting to reuse it

But that reuse is only correct if the endpoint actually speaks Cap’n Web on that socket.

Right now, nothing in the visible code indicates that /ws/:id speaks Cap’n Web. It appears to speak your own session-broadcast protocol.

Typed Design Spec

Title
Clarify whether Share RPC should terminate at Worker or Durable Object

Context
You observed the DO proxying WebSocket route and proposed that the RPC stub might need to connect through the Worker to the DO over upgraded WebSocket.

That is a valid design possibility, but it must match where the ShareRpc target actually lives.

Goals

• Determine the proper owner of the Cap’n Web session
• Avoid mixing broadcast WebSockets and Cap’n Web RPC unintentionally
• Preserve a minimal, type-safe API

Non-Goals

• Not implementing the routing change here
• Not collapsing all WebSocket use into one route unless justified

Types and Data Models

Worker-level main RPC target

interface ShareRpc extends RpcTarget {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
}

DO-level broadcast target, conceptually separate

interface ShareBroadcastChannel {
  connect(shareID: string): WebSocket
  broadcast(data: SyncData[]): Promise<void>
}

These are different abstractions and should not be merged accidentally.

Contracts and Invariants

If Worker owns the RPC session

• The client connects to Worker RPC endpoint
• Worker must host Cap’n Web session directly
• Worker can call DO internally

If DO owns the RPC session

• Worker upgrade path must hand the socket to a DO that hosts a Cap’n Web session
• The DO must expose the intended remote methods
• Share creation/bootstrap must have a clear root-entry strategy

If /ws/:id remains a custom live-update socket

• It must not be used by newWebSocketRpcSession() unless it actually speaks Cap’n Web framing/protocol

Recommended Direction

Recommendation
Use Option C now:

• /rpc should be the Cap’n Web route
• /ws/:id should remain the DO-backed live update route
• ShareRpcImpl should remain at the Worker layer
• if ShareRpcImpl needs DO services, call them internally

Why

• smallest change
• aligns with existing implementation ownership
• avoids confusing two unrelated WebSocket protocols
• easiest to test locally

Local Test Implication

If you want to test the hypothesis, add two separate tests:

1. RPC route test

• proves createShare/probeValue/probeCallback over the chosen transport

2. DO live WebSocket test

• proves /ws/:id upgrades and broadcasts session updates

Do not use the success of one as evidence for the other.

Questions for You

1. Do you want the Cap’n Web stub to expose ShareRpcImpl, or do you want the Durable Object itself to be the remote API?
2. Is /ws/:id currently meant only for browser session viewers, or was it intended to become the RPC transport too?
3. Do you need persistent bidirectional RPC identity, or is HTTP batch sufficient for share create/sync/delete?

Delegated Tasks

Implementation task

• Decide RPC termination point: Worker or DO
  Acceptance:
• one sentence design decision documented in code comments near the route

Implementation task

• If Worker-owned RPC:
  • keep /rpc separate
  • use the correct Cap’n Web Worker helper
  • ensure client route/transport match
    Acceptance:
• local test proves one real RPC call

Implementation task

• If DO-owned RPC:
  • define a DO class that hosts the Cap’n Web session
  • define how Worker hands off upgraded sockets
  • define root object/bootstrap semantics
    Acceptance:
• local test proves one real RPC call against DO-hosted target

Tests task

• Add separate tests for /rpc and /ws/:id
  Acceptance:
• each route tested for its own protocol semantics
• no shared ambiguous “WebSocket works” assertion

Docs task

• Document route roles:
  • /rpc
  • /ws/:id
    Acceptance:
• transport ownership and purpose explicit

QA Self-Check Results

• Exhaustiveness: covered both architectural branches
• Contracts: route/protocol ownership made explicit
• Effects: DO vs Worker boundary clarified
• Types: RPC target ownership separated from broadcast socket
• Compatibility: aligns with Cap’n Web transport semantics
• Security: noted bootstrap/auth implications
• Observability: recommended separate tests
• Delegation: tasks are specific and testable

Bottom line
Your idea is reasonable only if the Durable Object is actually the Cap’n Web RPC peer.

From the current code, the safer interpretation is:

• /ws/:id is a custom live-update WebSocket
• /rpc should be the Cap’n Web endpoint
• the Worker should call the DO internally, not tunnel the Cap’n Web stub through the existing broadcast socket

If you want, I can next produce a precise decision matrix comparing:

• Worker-hosted Cap’n Web RPC
• DO-hosted Cap’n Web RPC
• mixed Worker RPC + DO broadcast

for this codebase specifically.

Typed Design Spec

Title
Durable Object–hosted Cap’n Web RPC for share sessions

Context
You chose Option B: make the Durable Object the Cap’n Web RPC peer.

That means the design goal changes from:

• “Worker hosts ShareRpcImpl and may call DO internally”

to:

• “Client Cap’n Web stub connects through the Worker to a Durable Object that hosts the Cap’n Web session”

This is viable, but it is a real architectural change, not just a routing tweak.

Goals

• Host the Cap’n Web RPC session inside a Durable Object
• Allow the client to establish a WebSocket RPC session via the Worker
• Preserve a type-safe ShareRpc contract
• Support local testing in a capnweb-style, in-process manner before relying on Wrangler dev

Non-Goals

• I am not implementing the change
• I am not collapsing the existing viewer /ws/:id protocol into RPC unless explicitly chosen
• I am not performing git operations

Architecture Summary

Chosen architecture

Client newWebSocketRpcSession()
  -> Worker route /rpc/share/:scope (upgrade)
    -> Durable Object fetch()
      -> DO upgrades WebSocket
      -> DO hosts Cap’n Web session
      -> DO exposes ShareRpc target

Key boundary decision
The Durable Object becomes the authoritative remote ShareRpc server.

Implication
The current ShareRpcImpl in packages/cloudsession/src/rpc.ts should either:

• move conceptually into the DO implementation, or
• be split into pure storage/business logic plus a DO-hosted RPC adapter

I strongly recommend the second.

Modules and boundaries

1. Worker router

• Responsibility:
  • authenticate/route initial request
  • resolve which DO instance should receive the upgraded request
  • proxy fetch() to that DO
• Should not contain share business logic once Option B is complete

2. Durable Object RPC host

• Responsibility:
  • receive upgraded request
  • host Cap’n Web WebSocket session
  • expose ShareRpc methods
  • coordinate persistence/broadcasts

3. Storage logic

• Responsibility:
  • create/update/delete session and index records in R2
  • pure domain logic where possible
• Keep separate from transport host for testability

4. Optional viewer/broadcast socket

• If /ws/:id remains for browser live updates, that is a separate protocol and should stay separate unless intentionally replaced

Goals / Non-Goals

Goals

• WebSocket RPC session terminates in DO
• ShareRpc implemented at DO boundary
• deterministic local test can prove one real RPC call works
• clear mapping from request route to DO identity

Non-Goals

• no mixed transport ambiguity
• no duplicate ownership between Worker and DO for the same RPC interface
• no accidental reuse of non-RPC broadcast socket as Cap’n Web transport

Types and Data Models

Shared RPC contract

export interface ShareRpc extends RpcTarget {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
  probeValue(input: ProbeValueInput): ProbeValueOutput
  probeCallback(cb: ProbeCallback): Promise<string>
}

Durable Object routing identity

You now need a routing key for the DO session host.

Recommended choices:

1. global-share-rpc

• one DO instance acts as the root RPC host for share creation/update/delete
• simplest bootstrap model

2. shareID

• one DO per share
• good for per-share long-lived ownership
• awkward for createShare(sessionID) because the shareID does not exist until after create

3. sessionID

• one DO per original session
• possible, but less aligned with current external API

Recommendation
Use a single root RPC DO first:

type ShareRpcScope = "root"

Reason:

• createShare() needs a stable entry point before a share exists
• simpler client bootstrapping
• easiest local testing
• avoids needing a pre-create routing indirection

Then, if needed later, the root RPC can return references/IDs for per-share DOs.

Recommended internal decomposition

Split transport from domain logic:

interface ShareStore {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
}

DO RPC target:

class ShareRpcTarget extends RpcTarget implements ShareRpc {
  constructor(private store: ShareStore) { super() }
}

This avoids putting all persistence logic directly into the transport class.

Public Interfaces and Contracts

Worker route contract

GET/POST /rpc/share
Upgrade: websocket
-> forwarded to root ShareRpc Durable Object

Preconditions

• Request path matches configured RPC route
• If auth is configured, auth is validated before proxying
• Request is a valid Cap’n Web session initiation request

Postconditions

• On success, response is a valid WebSocket upgrade handled by the DO
• The DO hosts the Cap’n Web session main interface

Durable Object RPC contract

• The DO must expose ShareRpc as the Cap’n Web main target
• The DO must be able to access:
  • R2 bucket binding
  • shared secret config
  • API domain
  • any broadcast facilities needed

Important invariant
If the client uses:

newWebSocketRpcSession<ShareRpc>(...)

then the DO must actually host:

newWebSocketRpcSession(webSocket, shareRpcTarget)

or equivalent Cap’n Web server-side session initialization against the already-open socket.

Error Model

Structured errors

type ShareRpcError =
  | { type: "Unauthorized" }
  | { type: "NotFound"; shareID: string }
  | { type: "InvalidSecret"; shareID: string }
  | { type: "RouteMismatch"; route: string }
  | { type: "ProtocolMismatch"; expected: "capnweb-websocket" }
  | { type: "StorageFailure"; operation: "create" | "sync" | "delete"; cause: string }
  | { type: "UpgradeFailed"; reason: string }

Behavioral guidance

• auth failure should happen at Worker boundary before DO handoff when possible
• share existence/secret failures belong in the RPC target
• transport/protocol mismatch should fail early and clearly

Design Decisions

Decision 1 — Root RPC DO
Use one root DO as the Cap’n Web session entry point.

Why

• createShare() requires a stable main interface
• avoids pre-creation routing paradox
• reduces complexity

Decision 2 — Separate viewer socket from RPC socket
Do not reuse /ws/:id for Cap’n Web RPC unless you fully replace that protocol.

Why

• existing /ws/:id appears to be app-specific broadcast/live update semantics
• Cap’n Web framing/protocol is distinct
• conflating them increases correctness risk

Decision 3 — WebSocket-only RPC for Option B
If DO is the RPC host, prefer:

• client: newWebSocketRpcSession
• server: DO-hosted WebSocket Cap’n Web session

Do not mix this with newHttpBatchRpcSession for the same path unless explicitly designed.

Example Usage

Client

using rpc = newWebSocketRpcSession<ShareRpc>(`${baseUrl}/rpc/share`)
const info = await rpc.createShare(sessionID, initialData)
await rpc.syncShare(info.id, info.secret, items)
await rpc.deleteShare(info.id, info.secret)

Worker

if (url.pathname === "/rpc/share") {
  const id = env.SHARE_RPC.idFromName("root")
  const stub = env.SHARE_RPC.get(id)
  return stub.fetch(request)
}

DO host

class ShareRpcHost extends DurableObject {
  fetch(request: Request) {
    // validate upgrade
    // accept WebSocket
    // host Cap’n Web session with ShareRpc target
  }
}

Acceptance Criteria

Observable, testable

1. A WebSocket request to /rpc/share is proxied by the Worker to the root DO.
2. The root DO hosts a Cap’n Web RPC session implementing ShareRpc.
3. probeValue() succeeds over a real local WebSocket RPC session.
4. probeCallback() succeeds, proving bidirectional reference passing works.
5. createShare() persists expected share/ and index/ entries.
6. syncShare() updates persisted state and increments syncCount.
7. deleteShare() removes persisted records.
8. If unauthorized, the request fails before or at the DO boundary deterministically.
9. Local tests distinguish:
   • RPC route semantics
   • viewer/broadcast route semantics

Risks & Open Questions

High-risk areas

1. Bootstrap/routing complexity

• You need a stable root DO entry point
• per-share DO routing cannot be the only design if createShare() is a root operation

2. Protocol confusion

• Existing /ws/:id may tempt reuse
• do not reuse unless it truly becomes Cap’n Web transport

3. Storage and concurrency

• A single root DO may serialize RPC entry handling
• acceptable initially, but could become a throughput bottleneck later

4. Version skew

• packages/opencode uses capnweb@0.4.0
• packages/cloudsession uses capnweb@0.6.1
• this is a serious compatibility risk for a WebSocket session design
• I would treat version unification as required, not optional

5. Auth model

• For CLI/non-browser WebSocket clients, custom headers may work depending on runtime
• for browser clients, capnweb guidance is to authenticate in-band
• you need to state which client class consumes this RPC

Critical open questions

1. Is this RPC consumed only by OpenCode CLI/runtime, or also by browsers?
2. Should the root DO also handle broadcast viewer connections, or stay RPC-only?
3. Do you want one root DO forever, or root DO returning per-share remote objects later?
4. Will you unify capnweb version across packages/opencode and packages/cloudsession first?

Correctness-First Review of This Decision

Summary
Option B is valid, but it requires a deliberate redesign:

• root DO as RPC host
• separate RPC route
• separate viewer route
• version alignment
• local test proving actual WebSocket RPC exchange

Approval Status
Approve with required design constraints

Required Changes

1. Introduce a dedicated RPC DO host
2. Use one stable root route and one stable root DO identity
3. Do not treat current /ws/:id broadcast route as the RPC transport unless intentionally replaced
4. Unify capnweb versions across client and server packages
5. Add a real local RPC test for probe and create/sync/delete flows

Suggested Interface/Type Adjustments

• Keep ShareRpc as the only remote main interface
• Extract persistence logic into a transport-agnostic store/service
• Add an explicit DO binding dedicated to RPC host, separate from broadcast if needed

Delegation Plan

Implementation task 1
Create a new root Durable Object class to host the Cap’n Web RPC main interface.
Acceptance:

• DO has a single root identity path
• Worker can proxy /rpc/share to it

Implementation task 2
Refactor ShareRpcImpl into transport-agnostic share domain/store logic plus a DO-hosted RpcTarget adapter.
Acceptance:

• domain logic testable without socket transport
• RPC class only adapts contract to domain operations

Implementation task 3
Align client transport to WebSocket RPC for the share API.
Acceptance:

• ShareNext uses newWebSocketRpcSession<ShareRpc>() for RPC mode
• route path matches Worker route exactly

Implementation task 4
Unify capnweb version across packages/opencode and packages/cloudsession
Acceptance:

• same semver in both packages
• install/build succeeds
• no mixed-version runtime

Tests task 1
Add local in-process RPC tests for:

• probeValue
• probeCallback
• createShare
• syncShare
• deleteShare
  Acceptance:
• tests fail on route/transport/method mismatch
• tests use fake bindings and real app/DO logic where practical

Tests task 2
Keep separate tests for existing /ws/:id viewer socket semantics
Acceptance:

• no ambiguity between broadcast socket and RPC socket

Docs task
Document:

• /rpc/share = Cap’n Web RPC to root DO
• /ws/:id = viewer/broadcast socket
• auth model
• local test workflow
  Acceptance:
• route purposes explicit
• no mixed-protocol ambiguity

Git task
Branch:

• feat/share-rpc-do-host
  Commits:
• cloudsession: add root durable object capnweb rpc host
• opencode: switch share rpc client to websocket session
• cloudsession: add local capnweb rpc tests
• docs: clarify rpc vs viewer websocket routes
  Acceptance:
• commits scoped by concern

QA Self-Check Results

• Exhaustiveness: covered bootstrap, routing, transport, storage, auth, version skew
• Contracts: explicit root DO RPC contract defined
• Effects: Worker vs DO responsibilities isolated
• Types: shared interface retained, transport adapter separation recommended
• Compatibility: version skew flagged as a major risk
• Security: auth boundary called out
• Observability: concrete acceptance criteria provided
• Standards: correctness-first, no implementation code
• Delegation: tasks complete and testable

Bottom line
Yes — Option B can work, but only if you make the Durable Object an actual Cap’n Web RPC host, with a root entry point.

The most important next moves are:

1. dedicate a root DO to RPC hosting,
2. keep /rpc/share separate from /ws/:id,
3. unify capnweb versions,
4. add a local in-process WebSocket RPC test before depending on Wrangler dev.

Typed Design Spec

Title
Root Durable Object–hosted Cap’n Web RPC on /rpc only

Context
You clarified that:

• /rpc/share can be removed
• the RPC connection should exist only via /rpc

That is a good simplification and resolves one of the existing route mismatches.

Under Option B, this now becomes:

Client WebSocket RPC session
  -> Worker /rpc
    -> proxy fetch to root RPC Durable Object
      -> DO hosts Cap’n Web session implementing ShareRpc

Goals

• Use /rpc as the single RPC route
• Host the Cap’n Web session in a root Durable Object
• Remove /rpc/share entirely
• Keep /ws/:id separate unless intentionally replaced
• Make the client/server transport contract explicit and testable

Non-Goals

• Not merging the viewer WebSocket route into RPC
• Not supporting multiple RPC entry routes
• Not implementing the change here

Architecture Summary

Chosen architecture

1. Client:

   • connects only to /rpc
   • uses WebSocket-based Cap’n Web session

2. Worker:

   • /rpc is the sole RPC route
   • validates auth if configured
   • resolves a single root RPC DO instance
   • forwards fetch(request) to that DO

3. Root RPC Durable Object:

   • owns the Cap’n Web session endpoint
   • exposes ShareRpc methods
   • uses storage services / R2 bindings / broadcast dependencies

4. Viewer WebSocket route:

   • /ws/:id remains separate and app-specific
   • not reused as the Cap’n Web RPC route

Design implications

• The current Worker-level ShareRpcImpl should no longer be the top-level transport host
• Instead, the DO owns the transport boundary
• Shared logic should be extracted into a reusable service/store layer

Goals / Non-Goals

Goals

• One route: /rpc
• One transport owner: root DO
• One main interface: ShareRpc
• One client mode for RPC: WebSocket session

Non-Goals

• No duplicate route aliases
• No Worker-hosted and DO-hosted RPC at the same time
• No accidental route drift between client and server

Types and Data Models

Shared contract

export interface ShareRpc extends RpcTarget {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
  probeValue(input: ProbeValueInput): ProbeValueOutput
  probeCallback(cb: ProbeCallback): Promise<string>
}

Root DO identity
Use a single fixed name:

const ROOT_RPC_DO_NAME = "root"

Invariant

• Every /rpc request proxies to the same RPC DO instance initially
• This gives a stable bootstrap point for createShare()

Recommended module boundaries

1. ShareStore or equivalent domain service
   Responsibility:

• persistence logic only
• no transport concerns

Suggested contract:

interface ShareStore {
  createShare(sessionID: string, initialData?: SyncData[]): Promise<SyncInfo>
  syncShare(shareID: string, secret: string, data: SyncData[]): Promise<{ success: boolean; syncCount: number }>
  deleteShare(shareID: string, secret: string): Promise<{ success: boolean }>
}

2. ShareRpcTarget
   Responsibility:

• implements ShareRpc
• delegates to ShareStore

3. RootShareRpcDO
   Responsibility:

• terminates /rpc-forwarded requests
• hosts the Cap’n Web WebSocket session

4. Worker route /rpc
   Responsibility:

• route + auth + proxy only

Public Interfaces and Contracts

Worker /rpc route
Preconditions

• request path is exactly /rpc
• auth is valid if configured
• request is intended for Cap’n Web RPC transport

Postconditions

• request is proxied unchanged to the root RPC DO
• response is returned unchanged from the DO

DO RPC host
Preconditions

• request reaches the root RPC DO
• request is compatible with Cap’n Web WebSocket session establishment

Postconditions

• a Cap’n Web session is created
• the exposed main object satisfies ShareRpc

Client contract
The RPC client should use:

newWebSocketRpcSession<ShareRpc>(`${baseUrl}/rpc`)

Not:

• /rpc/share
• HTTP batch for this route, unless explicitly reintroduced later

Important invariant
If /rpc is the only RPC entrypoint, then:

• client route string must be /rpc
• Worker route must be /rpc
• DO bootstrap must be behind /rpc
• tests must target /rpc

Error Model

Structured errors

type RpcRouteError =
  | { type: "Unauthorized" }
  | { type: "RouteNotFound"; path: string }
  | { type: "UpgradeFailed"; path: "/rpc"; reason: string }
  | { type: "ProtocolMismatch"; route: "/rpc"; expected: "capnweb-websocket" }
  | { type: "StorageFailure"; operation: "create" | "sync" | "delete"; cause: string }
  | { type: "InvalidSecret"; shareID: string }
  | { type: "ShareNotFound"; shareID: string }

Behavior guidance

• auth failure should occur at Worker boundary if possible
• transport mismatch should fail before business logic
• domain errors stay in the ShareRpc implementation

Correctness Notes

Required design corrections relative to current code

1. Remove route/path drift
   Current mismatch:

• client uses /rpc/share
• server exposes /rpc

Required:

• both use /rpc only

2. Remove transport ambiguity
   Current mismatch:

• client uses newHttpBatchRpcSession
• desired design is DO-hosted WebSocket RPC

Required:

• client uses newWebSocketRpcSession

3. Remove interface mismatch
   Current mismatch:

• interface method: createShare
• implementation method: create

Required:

• implementation exposed through the DO must satisfy ShareRpc exactly

4. Separate viewer socket from RPC socket
   Current route:

• /ws/:id
  This should remain a separate protocol unless intentionally replaced

Recommendation
Keep /ws/:id separate.

Why

• /rpc is now your Cap’n Web route
• /ws/:id appears to serve session live-view broadcast semantics
• mixing them will obscure failures and complicate testing

Example Usage

Client

using rpc = newWebSocketRpcSession<ShareRpc>(`${baseUrl}/rpc`)
const info = await rpc.createShare(sessionID, initialData)
await rpc.syncShare(info.id, info.secret, data)
await rpc.deleteShare(info.id, info.secret)

Worker route concept

if (url.pathname === "/rpc") {
  // auth check
  // proxy to root rpc durable object
}

DO host concept

class RootShareRpcDO {
  fetch(request: Request): Response | Promise<Response> {
    // host Cap’n Web RPC session here
  }
}

Acceptance Criteria

Observable, testable

1. /rpc is the only RPC route in code and client configuration.
2. Client RPC mode uses WebSocket session, not HTTP batch.
3. Worker /rpc proxies to a single root RPC DO.
4. The root RPC DO hosts a Cap’n Web session exposing ShareRpc.
5. probeValue() succeeds over local RPC.
6. probeCallback() succeeds over local RPC.
7. createShare() succeeds and persists expected state.
8. syncShare() succeeds and updates state.
9. deleteShare() succeeds and removes state.
10. /ws/:id remains functionally separate from /rpc.
11. A local in-process test would fail if:

• route changes from /rpc
• client transport changes away from WebSocket
• method names drift from the shared contract

Delegation Plan

Implementation task 1
Normalize route contract to /rpc only.
Acceptance:

• no client references to /rpc/share
• Worker exposes one RPC route: /rpc

Implementation task 2
Switch share RPC client to WebSocket session.
Acceptance:

• ShareNext uses newWebSocketRpcSession<ShareRpc>(...)
• cached session lifecycle/disposal policy documented

Implementation task 3
Introduce a root RPC Durable Object host.
Acceptance:

• Worker proxies /rpc to root DO
• DO hosts ShareRpc main interface

Implementation task 4
Refactor business logic out of current transport class into a domain/store layer.
Acceptance:

• storage logic testable independently
• RPC target is thin and contract-focused

Implementation task 5
Unify capnweb version across packages/opencode and packages/cloudsession
Acceptance:

• same version in both package manifests
• no mixed-version client/server runtime

Tests task 1
Add local in-process RPC tests against /rpc:

• probeValue
• probeCallback
• createShare
• syncShare
• deleteShare
  Acceptance:
• real route exercised
• fake bindings only for platform services
• clear failures on route/transport/contract mismatch

Tests task 2
Keep /ws/:id tests separate.
Acceptance:

• viewer socket tested independently from RPC socket

Docs task
Document:

• /rpc is sole RPC route
• root DO owns Cap’n Web session
• /ws/:id is a separate live viewer path
  Acceptance:
• route responsibilities explicit for future contributors

Git task
Branch:

• feat/root-rpc-do
  Commits:
• cloudsession: route rpc through root durable object
• opencode: use websocket capnweb session on /rpc
• cloudsession: add local rpc session tests
• docs: clarify rpc and viewer websocket routes
  Acceptance:
• commits scoped by concern

Risks & Open Questions

Risks

1. Single root DO may become a bottleneck later

• acceptable initially
• can be evolved later to hand out per-share remote objects

2. Cap’n Web version skew is currently dangerous

• must be unified before relying on local WebSocket RPC

3. Auth model still needs an explicit decision

• CLI-only clients can often use headers
• browser clients likely need in-band auth

Open questions

1. Is the RPC client strictly OpenCode CLI/runtime, or also browser-side?
2. Should the root DO later mint/share per-share remote capability objects?
3. Do you want reconnect semantics defined now, or leave sessions best-effort initially?

QA Self-Check Results

• Exhaustiveness: route, transport, ownership, version skew, testing all covered
• Contracts: /rpc-only rule explicit
• Effects: Worker and DO boundaries isolated
• Types: shared ShareRpc retained
• Compatibility: WebSocket-only route clarified
• Security: auth still noted as pending decision
• Observability: acceptance criteria and test expectations explicit
• Standards: correctness-first, no full implementation
• Delegation: implementation/test/doc/git tasks are explicit and testable

Bottom line
Yes — that is the cleaner design.

Under Option B, /rpc should be the only RPC endpoint, and it should proxy to a single root Durable Object that hosts the Cap’n Web session. /ws/:id should remain a separate non-RPC socket unless you explicitly redesign it too.

Next best step: implement the root DO + /rpc proxy + local in-process WebSocket RPC test together, as one coherent change.

Correctness-First Review

Summary
I delegated as requested.

Agent outcomes are mixed:

• typescript-coder-agent returned a completion summary claiming fixes were made and tests now pass, but it did not provide file-level evidence consistent with the requested architecture change and appears to have focused on test/auth issues.
• researcher produced a useful architectural validation report confirming the root Durable Object–hosted /rpc design is sound, with major emphasis on Cap’n Web version skew and WebSocket proxying caveats.
• advanced-coding-manager returned no actionable content.

Because I cannot verify the claimed implementation from the agent outputs alone, I cannot approve the redesign as completed yet.

Approval Status
Block pending verification

Findings

Blockers

1. Unverified implementation claim

• The coding agent reported:
  • “all 18 test failures fixed”
  • “47/47 tests passing”
  • “RPC redesign implementation is complete”
• But it did not provide:
  • files changed
  • route/transport evidence
  • confirmation that /rpc/share was removed
  • confirmation that client switched from HTTP batch to WebSocket
  • confirmation that a root RPC DO was added to Wrangler config
• This is insufficient to accept the redesign as complete.

2. Major compatibility risk remains

• packages/opencode currently uses capnweb@0.4.0
• packages/cloudsession currently uses capnweb@0.6.1
• The researcher correctly flagged this as a high-risk blocker for WebSocket RPC interop.
• Until verified resolved, this blocks confidence in the design.

3. Architecture-specific acceptance criteria remain unproven
   Required evidence still missing:

• /rpc is the only RPC endpoint
• Worker /rpc proxies to one root DO
• root DO hosts Cap’n Web RPC session
• client uses newWebSocketRpcSession<ShareRpc>(.../rpc)
• local test proves probe + create/sync/delete via the new route

Research-Validated Design Notes

Validated

• Cap’n Web can be hosted in a Durable Object fetch handler
• Worker → DO fetch(request) proxying of WebSocket upgrade requests is the correct pattern
• A singleton root DO is a valid bootstrap point for createShare(sessionID, initialData?)
• Keeping /ws/:id separate from /rpc is the right separation of concerns

High-risk caveats

• version skew across client/server packages
• WebSocket long-lived connection lifecycle
• need for explicit auth handling through Worker -> DO path
• potential singleton DO bottleneck later, though acceptable initially

Suggested Interface/Type Adjustments
These remain required regardless of implementation status:

• ShareRpcImpl or equivalent target must implement:
  • createShare
  • syncShare
  • deleteShare
  • probeValue
  • probeCallback
• shared contract should ideally come from one source, not duplicated files
• transport host should be thin; persistence logic should be factored into a store/service

Required Validation Gates

Before accepting the redesign, the following must be verified in the repo:

1. Route contract

• no remaining client use of /rpc/share
• /rpc is the sole RPC route

2. Transport contract

• client uses WebSocket Cap’n Web session
• server-side root DO hosts WebSocket RPC session
• Worker route proxies to DO rather than hosting RPC directly

3. Durable Object config

• root RPC DO exported
• wrangler binding added
• migration added

4. Version alignment

• same Cap’n Web version across packages/opencode and packages/cloudsession, or a documented/tested compatibility justification

5. Test coverage
   At minimum:

• probeValue round-trip
• probeCallback round-trip
• createShare over /rpc
• syncShare over /rpc
• deleteShare over /rpc

Questions for the Implementation Author

1. What exact files changed?
2. Is /rpc/share fully removed from the client?
3. Does ShareNext now use newWebSocketRpcSession?
4. What is the new root DO class name and binding name?
5. Is RpcRoot now exported and declared in wrangler.jsonc migrations?
6. Were Cap’n Web versions unified?

Delegated Next Tasks

Implementation verification task

• Inspect the actual modified files and compare against the target architecture
  Acceptance:
• exact file/line evidence for route, transport, DO config, and client usage

Testing task

• Run package-local tests/typecheck and report outputs with commands
  Acceptance:
• command transcript includes package directories and relevant passing suites

Corrective implementation task
If not yet complete:

• align versions
• enforce /rpc-only route
• move RPC hosting into root DO
• switch client to WebSocket session
  Acceptance:
• all architecture acceptance criteria satisfied

Docs task

• document /rpc vs /ws/:id
  Acceptance:
• one concise developer-facing explanation

Git task

• prepare scoped commits once verified
  Acceptance:
• route/config/client/test changes separated logically

QA Self-Check Results

• Exhaustiveness: covered agent results, risks, and missing proof points
• Contracts: explicit validation gates listed
• Effects: Worker/DO responsibilities maintained
• Types: method/interface alignment still required
• Compatibility: version skew correctly treated as blocker
• Security: auth propagation noted
• Observability: required evidence and test matrix listed
• Standards: correctness-first, no unverified approval
• Delegation: next tasks explicit and testable

Bottom line
The researcher validated the architecture. Good.

But I cannot yet claim the implementation is done, because the coding agent’s report is not sufficiently evidenced and the manager agent returned nothing useful.

If you want, the next correct move is for me to:

1. inspect the actual changed files and configs in this repo,
2. verify whether the redesign really landed,
3. produce a line-referenced block/approve review.

Typed Design Spec

Title
Observability plan for verifying Cap’n Web RPC and Durable Object share data flow

Context
You want to inspect what data is moving through the new path and verify that persistence/state changes are correct. The most useful places to observe are:

1. Worker /rpc ingress
2. Root RPC Durable Object method entry/exit
3. R2 read/write boundaries
4. Optional Durable Object in-memory/session state
5. Client-side payloads before send / after response

Goals

• Verify actual payload shapes
• Verify method call ordering
• Verify persisted state in R2
• Verify that IDs/secrets/sync counts line up
• Do this with minimal ambiguity

Non-Goals

• Not building permanent noisy logging everywhere
• Not logging secrets/raw sensitive content in production
• Not relying only on network-level WebSocket frames, since Cap’n Web payload interpretation matters more

Best Ways to See the Data

1. Log at the RPC method boundary
   Best signal-to-noise ratio.

Where

• inside the ShareRpc implementation that runs in the root DO

What to log

• method name
• shareID/sessionID
• number of items
• item types
• syncCount before/after
• storage keys touched

Do not log by default in production

• full secret
• arbitrarily large message bodies
• raw user content unless intentionally debugging

Recommended log shape

{
  route: "/rpc",
  method: "syncShare",
  shareID,
  itemCount: data.length,
  itemTypes: data.map((x) => x.type),
}

Why

• tells you whether RPC decoding is correct
• confirms Cap’n Web method dispatch is correct
• avoids drowning in transport internals

2. Log around storage adapter operations
   This is the next most useful verification point.

Where

• createStorageAdapter() or equivalent storage abstraction in packages/cloudsession/src/storage.ts

What to log

• operation: get / put / delete / list
• key
• object summary
• serialized size if available

Recommended summaries

• session key
• message count
• part count
• diff count
• model count
• metadata.syncCount

Why

• proves the persisted state is what you think it is
• catches bugs where RPC calls succeed but persistence is wrong

3. Add a debug endpoint to dump persisted state
   This is often the easiest practical inspection tool during local dev.

Recommended shape

• GET /api/debug/share/:id
• returns:
  • stored AgentSession
  • stored SessionIndex
• gated by the same admin/shared key you already use

If you want to inspect “contents of the db”, this is the most direct analogue for your current architecture, though it is R2-backed object storage, not a relational DB for share state.

If you also want the local opencode SQLite-side mapping:

• inspect the session_share table from packages/opencode
• but for cloudsession share state, the truth is in R2 objects:
  • share/${id}
  • index/${id}

4. Add a temporary debug method on the RPC interface
   Only for local development if needed.

Example concept

debugShareState(shareID: string): Promise<{
  session: AgentSession | null
  index: SessionIndex | null
}>

I do not recommend keeping this as a long-term public RPC surface unless you truly need remote introspection. A protected HTTP debug route is usually cleaner.

5. Use Wrangler logs/tail during local or remote execution
   Useful for request lifecycle visibility.

Local

• run wrangler dev in packages/cloudsession
• inspect console output there

Remote/staging

• wrangler tail

Best when combined with structured logs at:

• /rpc Worker route
• root DO RPC methods
• storage adapter

Specific Recommendation

If your immediate goal is:

“print out the contents of the db, just to verify data is being handled correctly”

then the best correctness-first approach is:

A. Add structured logging in the RPC methods
B. Add structured logging in the storage adapter
C. Add one temporary authenticated debug HTTP endpoint that reads:

• share/${id}
• index/${id}

This gives you:

• ingress visibility
• persistence visibility
• direct readback verification

What to Inspect Specifically

For createShare(sessionID, initialData?)
Verify:

• returned id
• returned secret exists
• share/${id} exists
• index/${id} exists
• initial counts match initialData application
• metadata.secret matches derived secret
• metadata.sessionID matches input

For syncShare(shareID, secret, data)
Verify:

• secret check passes/fails correctly
• syncCount increments
• item types received are as expected
• updates replace by ID where intended
• diffs append where intended
• index counts match full session

For deleteShare(shareID, secret)
Verify:

• both share/${id} and index/${id} removed
• subsequent debug reads return null/not found

Suggested Minimal Debug Log Points

Worker /rpc
Log:

• request path
• auth present/absent
• proxied to root DO

Root DO
Log:

• session established
• method invoked
• method args summary
• success/failure

Storage
Log:

• key read/written/deleted
• summarized object state

Example Usage

Good local debugging sequence

1. start cloudsession locally
2. create share from opencode client
3. watch logs for:
   • /rpc request
   • createShare
   • put share/...
   • put index/...
4. hit debug endpoint for that shareID
5. compare persisted state to expectations
6. trigger sync
7. hit debug endpoint again
8. verify counts and payload materialization

Security and Correctness Notes

Do not log secrets fully
Prefer:

• last 6 chars
• or boolean “secretMatched”

Do not log full message content by default
Prefer summaries:

• IDs
• lengths
• counts
• types

Do not leave unauthenticated debug dump endpoints enabled
Require the admin/shared key

Avoid logging raw Cap’n Web transport frames first
That is lower-value than method/storage-level logging

Recommended Delegated Tasks

Implementation task
Add structured logs at RPC method boundaries and storage adapter boundaries.
Acceptance:

• logs show method, IDs, counts, and storage keys
• no full secret leakage

Implementation task
Add a temporary authenticated debug endpoint to read persisted share/index state by shareID.
Acceptance:

• returns current stored values
• protected by admin/shared auth
• easy to remove later

Tests task
Add a test for the debug endpoint and for storage summaries if applicable.
Acceptance:

• endpoint returns persisted create/sync state accurately

Docs task
Document how to inspect local share state:

• start dev server
• run share flow
• call debug endpoint
• interpret logs
  Acceptance:
• concise local debugging steps available to developers

QA Self-Check Results

• Exhaustiveness: covered ingress, DO, storage, and readback paths
• Contracts: debug suggestions preserve core API
• Effects: observability placed at meaningful side-effect boundaries
• Types: debug endpoint/readback suggested over ad hoc frame logging
• Compatibility: works whether RPC is Worker- or DO-hosted
• Security: secret/logging cautions included
• Observability: primary focus
• Standards: concise, no unnecessary implementation code
• Delegation: explicit and testable

Bottom line
If you want confidence quickly, don’t start by decoding raw WebSocket traffic.

Instead:

1. log the RPC method calls,
2. log the R2 reads/writes,
3. add a temporary authenticated endpoint to dump share/${id} and index/${id}.

That will tell you very quickly whether data is being handled correctly.