feat: @rivetkit/effect SDK

[IGassmann]

Summary

Introduces @rivetkit/effect, an Effect-based SDK for Rivet Actors.

What's here

• examples/effect/ — proposed API surface
• rivetkit-typescript/packages/effect/ — @rivetkit/effect package

Looking for feedback on the API's design.

Benefits

• Typed errors. The current SDK throws untyped exceptions (throw new UserError("...", { code: "..." })). Callers catch unknown. The Effect SDK puts errors in the E channel: Effect<number, CounterOverflowError>. The client sees the exact union of possible errors at compile time.
• Runtime validation at the boundary. The current SDK's action args ((c, amount: number)) are TypeScript-only. Types are erased at runtime. A malicious or drifted-version client can send anything. The Effect SDK validates wire data with Schema.decodeUnknown before it reaches handler code.
• Runtime dependency tracking in the type system. Counter.client depends on Client in the R channel. If you forget Layer.provide, you get a compile error naming the missing runtime dependency. The current SDK's typeof registry gives type-safe method calls, but doesn't track the Effect runtime dependency.
• Testability via Layer swapping. Any service (KV, DB, state, events) can be replaced by providing a different Layer. The current SDK has setupTest but swapping individual services requires the test framework's internals.
• Resource safety. Effect's Scope and addFinalizer guarantee cleanup runs even on errors or interruption. The current SDK has lifecycle hooks (onSleep, onDestroy) but they're not compositional. You can't nest scopes or attach finalizers from within action handlers.
• Wire encoding control. Effect Schema distinguishes encoded (wire) and decoded (runtime) types. Schema.Date decodes an ISO string into a Date, Schema.BigInt decodes a string into a BigInt. The current SDK has no equivalent — you get whatever JSON gives you.
• Effect Queue message processing. The current SDK processes queue messages through an async iterator (c.queue.iter()). The Effect SDK exposes durable messages as an Effect Queue.Dequeue, giving you batching, concurrent consumers via forked fibers, and composability with Stream, Schedule, and other Effect primitives out of the box.
• Distributed tracing across actor calls. Effect spans propagate from caller to handler across the wire. Span shape follows OTel RPC conventions (${actor}/${action} name, kind: "client" | "server", rpc.system.name / rpc.method attributes), and user-defined sub-spans inside handlers nest correctly under the SDK's server span.

Tasks

• 🔜 Run Schema.encode / decode at the state persistence boundary
• 🔜 Implement the "fires the wake-scope finalizer on sleep" test case
• Refactor current implementation
• Bridge Rivetkit aborts and Effect interruption
• Improve mapping of plain SDK errors to Effect SDK errors/defects
• Counter.Events API
• Messages/queues API
• Actor-to-actor communication
• Connections API
• Actor.Db API
• Schedules API
• Get actor's ID from client
• Authorization API
• Runner.serve(), ...
• Allow actor state to be swappable during testing
• Proper TSDoc
• README for @rivetkit/effect
• Plain RivetKit ↔ Effect actor interop
• Find solution for "Rivetkit's auto-spawned engine persists state across runs, so each pnpm test inherits prior runs' dead-envoy actor bindings and stalls on the engine's lost-envoy threshold"

Open Questions

State initialization

• How to define default initial values (current SDK: state: { count: 0 })
• How to support dynamic state from creation input (current SDK: createState(c, input))
• Client-side getOrCreate(key, { createWithInput: { start: 10 } }) equivalent

State persistence semantics

• When/how are SubscriptionRef changes persisted? On every Ref.update, or batched?
• What atomicity guarantees exist within an action? If an action updates state twice, is each update persisted or only the final value?
• What is the equivalent of stateSaveInterval (current SDK batches writes at a configurable interval)?

Configuration and timeouts

• How to configure per-actor timeouts (action timeout, sleep timeout, connection liveness)?
• Where do options like noSleep, maxQueueSize, maxQueueMessageSize live?
• Should these be in Actor.make options, toLayer options, or registry-level config?

Connections

• Per-connection state from params (current SDK: createConnState(c, params))
• Accessing connection state in actions (current SDK: c.conn.state)
• Iterating all connections (current SDK: c.conns)
• Connection lifecycle hooks (onBeforeConnect, onConnect, onDisconnect)

Scheduling

• Delayed action invocation (current SDK: c.schedule.after(delayMs, "actionName", ...args))

Lifecycle hooks

• onCreate, onDestroy
• onBeforeConnect, onConnect, onDisconnect
• onStateChange, onBeforeActionResponse

Actor self-awareness and control

• Actor key access (current SDK: c.key)
• Self-destruction (current SDK: c.destroy())

Low-level handlers

• Raw HTTP handler (current SDK: onRequest)
• Raw WebSocket handler (current SDK: onWebSocket)

Client ergonomics

• Positional action args (current SDK: counter.increment(5)) vs single-object payload (counter.increment({ amount: 5 }))

Access control for events and queues

• The current SDK has canSubscribe on events and canPublish on queues — guards that receive the connection context and return a boolean to allow/deny a specific client. How should these map to the Effect design?

Mixing Effect and plain RivetKit actors

• Can plain RivetKit actors be registered alongside Effect actors in the same Registry.layer?
• A utility like Registry.fromPlain({ chatRoom }) could wrap plain actor configs into a Layer for composition, without requiring schema conversion
• On the client side, calling a plain actor from Effect code would need to be handled.

Future Improvements

• Per-actor client services. Reconsider the client dependency model by replacing the central Counter.client projection with a per-actor service model (Counter.Client plus Counter.clientLayer). This would make application effects depend on the exact actor clients they use instead of the shared Client, improving dependency readability, enabling selective test fakes per actor, supporting per-actor endpoint/token/project overrides through layers, and allowing higher-level services to mock or swap one actor client without replacing the entire transport.
• Unified tracing across the Effect SDK, rivetkit actor instance, and engine. Today, three disjoint span trees are produced per action call: the engine's HTTP request tree (rooted at http_request with parent: None), rivetkit's actor instance tree (rooted at actor.action.<name> via @rivetkit/traces, gated by RIVET_EXPERIMENTAL_OTEL), and the Effect SDK tree (the only one that crosses the wire today, via ActionMeta.trace + Tracer.externalSpan). Joining them would require: (1) the engine's api-builder/guard-core middleware to extract traceparent and replace parent: None, plus forwarding context across the engine→envoy hop; (2) rivetkit's executeAction to read the wire trace context (from ActionMeta or traceparent) and parent actor.action.<name> to it; (3) the Effect SDK to either reparent its server span under rivetkit's actionSpan via a context tag, or migrate to @effect/opentelemetry so both sides emit through one OTel pipeline with standard W3C propagation. End state: a single trace from caller through engine through actor host through handler sub-spans.