feat: basic rivetkit impl

[MasterPtato]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[MasterPtato]

• chore: remove global epoxy contention #4554
• feat: native SQLite backend via napi-rs with KV channel protocol #4496
• feat: actor query in gateway #4553
• feat: add sleep and reschedule endpoints for actors #4556
• fix: optimize e2e actor path #4551
• feat(pb): actor v1 to v2 migration #4548
• feat(envoy-client): fully flesh out tunnel impl #4547
• feat: basic rivetkit impl #4544 👈 (View in Graphite)
• feat: basic envoy tunnel impl #4534
• chore: envoy client #4521 : 1 other dependent PR (#4531 )
• feat(pb): actors v3 #4463
• feat(ups): implement queue subs #4486
• feat(cache): add in flight deduping #4459
• fix(cache): clean up lib #4457
• fix(config): allow configuring topo dcs via map, fix pg ssl mode config #4456
• fix(api): dont 500 on cross dc response #4449
• chore: update byte units on frontend #4444
• fix: runner alloc idx logic, api auth for actor get #4443
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[railway-app]

🚅 Deployed to the rivet-pr-4544 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	🕒 Building (View Logs)	Web	Apr 5, 2026 at 11:33 am
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:33 am
ladle	🕐 Queued (View Logs)	Web	Apr 5, 2026 at 11:33 am
frontend-inspector	🕒 Building (View Logs)	Web	Apr 5, 2026 at 11:32 am
frontend-cloud	🕒 Building (View Logs)	Web	Apr 5, 2026 at 11:32 am
mcp-hub	✅ Success (View Logs)	Web	Mar 31, 2026 at 10:26 pm

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• example-agent-os
• example-agent-os-e2e
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4544

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4544

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4544

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4544

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4544

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4544

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4544

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4544

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4544

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4544

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4544

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4544

commit: e4db945

[claude]

Code Review: PR #4544 — feat: basic rivetkit impl

Summary

This PR renames the "runner" abstraction to "envoy" throughout the TypeScript SDK and engine configuration, introduces a new /actors2 API endpoint for RivetKit-specific actor creation (name-based pool selection), adds WebSocket tunnel support in the envoy client, fixes several metric name collisions, and corrects a state machine bug in the actor2 workflow runtime.

---

Issues

1. Unresolved TODO — serverless SSE handler is completely stubbed out

File: rivetkit-typescript/packages/rivetkit/src/drivers/engine/actor-driver.ts, serverlessHandleStart

The entire body of serverlessHandleStart has been replaced with a block comment starting with // TODO:. The method now only awaits this.#envoyStopped.promise unconditionally, meaning:

• The SSE stream never sends the init packet.
• The abort handler that gracefully shuts down the envoy on connection loss is removed.
• Any serverless deployment that calls this handler will hang indefinitely until the envoy stops on its own.

This is a regression. The TODO must be resolved before merging.

2. handle: null as any is an unsafe initialization

File: engine/sdks/typescript/envoy-client/src/tasks/envoy/index.ts

SharedContext.handle is typed as EnvoyHandle but initialized as null as any. There is a window between startConnection(shared) being called and shared.handle = handle being set. If the connection task fires a synchronous callback during startConnection, it would see a null handle. Consider creating the handle first and then calling startConnection.

3. Field name mismatch in tunnel.ts payload size check

File: engine/sdks/typescript/envoy-client/src/tasks/envoy/tunnel.ts

The code checks ctx.protocolMetadata?.maxPayloadSize but the ProtocolMetadata type uses maxResponsePayloadSize. WebSocketTunnelAdapter.#handleSend correctly uses maxResponsePayloadSize. This inconsistency silently skips the payload size check for HTTP responses since undefined > number evaluates to false.

4. shutdown(immediate) ignores the immediate parameter

File: engine/sdks/typescript/envoy-client/src/tasks/envoy/index.ts, createHandle

The immediate flag is accepted but never forwarded. EngineActorDriver.shutdown passes immediate specifically to distinguish graceful drain from immediate stop. Ignoring it means all shutdowns are treated as graceful.

5. Commented-out hibernatable WebSocket restoration

File: rivetkit-typescript/packages/rivetkit/src/drivers/engine/actor-driver.ts

Both #hwsLoadAll and the restoreHibernatingRequests call in onBeforeActorStart are commented out with // TODO:. sendHibernatableWebSocketMessageAck is also commented out. Without acks, the gateway may re-deliver messages indefinitely. These should reference a tracking issue.

6. /actors2 endpoint lifecycle is undocumented

Files: engine/packages/api-public/src/router.rs, engine/packages/api-peer/src/router.rs

The PR introduces /actors2 as a parallel endpoint with no comment explaining its intended lifecycle (will /actors be removed? Will /actors2 be renamed?). The TODO: check rivetkit version before choosing actor version comment in create.rs confirms this is provisional. This should be tracked in an issue or code comment.

---

Minor / Nits

• Error message accuracy — engine/packages/pegboard-envoy/src/ws_to_tunnel_task.rs: The message changed from "actor does not belong to envoy" to "actor does not exist". The actor may exist but belong to a different namespace. Consider "actor does not belong to this namespace".

• Unstructured log — engine/sdks/typescript/envoy-client/src/tasks/connection.ts: console.error("envoy tx should not be closed") should use the structured logger consistent with the rest of the file.

• Array allocation in getActor hot path — Array.from(gens.values()).reverse() allocates on every lookup. A simple descending iteration avoids this.

• Input2 naming — Input2 / Operation2 in pegboard/src/ops/actor/create.rs is not self-documenting. A comment or a more descriptive name would clarify intent.

• Missing trailing newline — rivetkit-typescript/packages/rivetkit/package.json is missing a trailing newline at EOF.

• Indentation inconsistency — engine/packages/pegboard/src/ops/actor/create.rs: input.crash_policy is not indented consistently with the other arguments and will be reformatted by cargo fmt.

---

Positive Changes

• Fixing the metric name collision (pegboard_event_multiplexer_count / pegboard_ingested_events_total) between pegboard-envoy and pegboard-runner is a good correctness fix.
• The WorkflowError::Udb retry path in gasoline/src/error.rs is a sensible resilience improvement.
• Moving WS_PROTOCOL_TOKEN into a shared mod.rs export is correct de-duplication.
• The state machine fix in actor2/runtime.rs (setting Transition::Sleeping before returning StoppedResult::Continue, and moving SendOutboundInput before the transition update) correctly prevents stale transition state.
• The findActor to getActor rename with "highest generation" semantics is a correctness improvement.
• The get_for_envoy to get_for_kv rename and replacement of the envoy-key ownership check with a namespace check aligns the security model with the new architecture.

[NathanFlurry]

Merge activity

• Apr 5, 11:11 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 5, 11:33 AM UTC: Graphite rebased this pull request as part of a merge.
• Apr 5, 11:33 AM UTC: @NathanFlurry merged this pull request with Graphite.