chore: simplify queue api

[NathanFlurry]

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

[railway-app]

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

Service	Status	Web	Updated (UTC)
ladle	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 10:40 pm
website	😴 Sleeping (View Logs)	Web	Feb 19, 2026 at 5:48 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 5:39 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 5:39 am
mcp-hub	✅ Success (View Logs)	Web	Feb 19, 2026 at 5:39 am

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit): fix run workflow teardown #4239
• feat(rivetkit): canInvoke #4237
• chore(rivetkit): make execute generic #4231
• chore: update workflow queues api #4230
• chore: simplify queue api #4229 👈 (View in Graphite)
• refactor(rivetkit): add typed event and queue schemas for actors #4209 : 1 other dependent PR (#4224 )
• feat: configure rivetkit storage path #4233
• chore(rivetkit): migrate file system driver to sqlite #4206
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• 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
• custom-serverless-vercel
• example-elysia
• example-elysia-vercel
• 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-hono-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• 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
• example-sqlite-raw-vercel
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc
• example-trpc-vercel

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

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

@rivetkit/traces

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

@rivetkit/workflow-engine

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 8d79ee3

[claude]

PR Review: chore: simplify queue api

This PR significantly simplifies the queue API both on the client side (replacing the proxy-based handle.queue.name.send() with a direct handle.send(name, body)) and on the actor server side (replacing the overloaded c.queue.next(name) with options-object-based c.queue.next({ names, count }), plus a new c.queue.iter() async iterator). Overall a good cleanup with solid test coverage.

---

Positives

• for await ... of c.queue.iter() is far more ergonomic than the old while(true) { const msg = await c.queue.next(...) } pattern; examples like ai-agent are cleaner for it.
• c.aborted as a convenience alias for c.abortSignal.aborted removes noise in run-loop examples.
• Waiter cleanup is now correct. The old code never removed the actor-abort event listener after a waiter resolved, which was a memory/listener leak. The new cleanup() closure + actorAbortCleanup / signalAbortCleanup pattern fixes this properly.
• EventSchemaConfig / QueueSchemaConfig split makes type constraints more precise and self-documenting throughout the generic chains.
• joinAbortSignals is a clean utility and handles the early-abort case correctly.
• tryNext() for non-blocking polling is a useful addition.
• Consistent updates across both regular and Vercel example variants.

---

Issues / Concerns

1. Schema validation silently removed from enqueue (queue-manager.ts)

The validateSchema call was removed from enqueue. Previously, if a queue was declared with a StandardSchema (e.g., a Zod schema), the payload would be validated before persisting. Now that queue<T>() returns a plain QueueTypeToken, there is nothing to validate against at runtime. This is fine for the new token API, but if someone was relying on StandardSchema validation on queues, it silently stops working. Worth a note in the PR description or a deprecation warning.

2. QueueCompleteNotConfigured is defined but never referenced

errors.ts adds QueueCompleteNotConfigured, but a search of the diff shows no call site. Either it should be used in #makeCompletableMessage or completeMessageById to surface a descriptive error, or it should be removed.

3. options as any in ActorHandleRaw.send / ActorConnRaw.send

TypeScript overload resolution cannot pick between the two QueueSender overloads, so as any is used as an escape hatch. A single implementation signature (name, body, options?: QueueSendOptions) => Promise<QueueSendResult | void> on the private implementation (separate from the public overloads) would eliminate the cast.

4. New nullable fields in persisted message format without visible migration

enqueue now serializes four new fields (failureCount, availableAt, inFlight, inFlightAt, all null). Existing persisted messages lack these fields. Is the deserialization side tolerant of missing fields? If not, actors with queued messages at deploy time will error on the next drain. Please confirm the versioned deserializer handles this gracefully.

5. #pendingCompletableMessageIds not cleared on error paths in #makeCompletableMessage

If completeMessage throws (e.g. a transient DB error), completed is reset to false so the caller can retry. However messageId remains in #pendingCompletableMessageIds, which means calling c.queue.next() again will immediately throw QueuePreviousMessageNotCompleted. The user cannot receive any new message until they successfully complete the one that errored. Whether this is intentional is worth a comment, because the error message may be confusing when the user did call complete() but it threw.

6. iter() does not check user-provided signal in loop condition

The while condition only checks this.#abortSignal.aborted. If the caller passes a signal that is aborted between iterations, the loop enters next() which throws ActorAborted and the catch block exits cleanly — functionally correct but slightly surprising. Adding && !resolvedOpts.signal?.aborted to the while condition would make the intent explicit.

7. isQueueSchemaDefinition heuristic is fragile

The function matches any object with a non-undefined message property. The type system prevents misuse in well-typed code, but at runtime it could misclassify. Adding a discriminant symbol (e.g. Symbol.for("rivetkit.queueDefinition")) would make the runtime check robust.

8. Minor: docs no longer mention message durability guarantee

The updated queue.mdx removed the sentence about messages persisting until acknowledged. The durability guarantee still holds but is no longer stated. Worth re-adding under a short "Durability" note.

---

Nits

• The promiseWithResolvers(() => {}) calls pass a no-op cancel callback. If that parameter is always unused, removing it (or documenting what it is for) would reduce confusion.
• #normalizeNames deduplicates names with new Set, which is correct, but the outer receive() also converts to a Set for O(1) lookup — the dedup in #normalizeNames is harmless but slightly redundant.
• The receiveRequest action in the test fixture changed name to names without a comment; a quick mention of the rename in the PR description would help reviewers tracking the breaking-change surface.

---

Summary: The core design is solid and the ergonomics are meaningfully better. The main things to verify before merge are: (1) persisted message format backward compatibility, (2) whether QueueCompleteNotConfigured is intentionally unused, and (3) the behavior of completable messages when complete() throws.

[graphite-app]

Merge activity

• Feb 19, 10:44 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 19, 10:45 PM UTC: CI is running for this pull request on a draft pull request (#4238) due to your merge queue CI optimization settings.
• Feb 19, 10:45 PM UTC: Merged by the Graphite merge queue via draft PR: #4238.