fix(rivetkit): expose engine ray IDs on errors for debug

[abcxff]

No description provided.

[abcxff]

Stack for rivet-dev/actors

• #5605 fix(workflow-engine): mark completed inner-loop iterations v …
• #5603 fix(rivetkit): expose engine ray IDs on errors for debug 👈
• #5601 fix(frontend): submit Vercel drain grace period
• #5604 fix(rivetkit-napi): remove stale HttpRequestBodyStream test …
• main

Get stack: forklift get 5603
Push local edits: forklift submit
Merge when ready: forklift merge 5603

_{change kzmlwrll}

[railway-app]

🚅 Deployed to the actors-pr-5603 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Aug 25, 2026 at 7:39 pm
kitchen-sink	😴 Sleeping (View Logs)	Web	Aug 25, 2026 at 7:38 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Aug 25, 2026 at 7:36 pm
ladle	✅ Success (View Logs)	Web	Aug 25, 2026 at 7:29 pm
mcp-hub	✅ Success (View Logs)	Web	Aug 25, 2026 at 7:27 pm
website	❌ Build Failed (View Logs)	Web	Aug 25, 2026 at 7:27 pm

[claude]

Review

Clean, well-scoped plumbing change that threads an engine rayId through the TypeScript client's error types, the NAPI bridge, and the WebSocket close-reason path so it can be surfaced for debugging. Went through the NAPI bridge round-trip, RivetError/ActorError classes, HTTP response handling, and WS close-reason handling in detail.

Strengths

• The rayId round-trip through the Rust side (BridgeRivetErrorContext → parse_bridge_rivet_error → anyhow_to_bridge_rivet_error_payload) is correct and covered by actor_factory.rs tests, including a same-payload-parsed-twice case.
• x-rivet-ray-id matches the actual header constant emitted by the engine (engine/packages/api-builder/src/middleware.rs::X_RIVET_RAY_ID), so the HTTP-side plumbing (sendHttpRequest, #parseRawFetchErrorResponse, reload()) reads the right header.
• Good defensive test (keeps ray ID separate from application metadata) verifying rayId doesn't collide with a user-supplied metadata.rayId key.
• forbiddenError/inspector-auth path explicitly sets ray_id: None rather than fabricating one, which is correct since that failure never reaches the engine.

Possible gap: per-action errors over an open WebSocket connection

actor-conn.ts's #handleOnMessage handles the protocol's Error message tag (action-level errors delivered over an already-open connection, response.body.tag === "Error") by destructuring { group, code, message, metadata, actionId, actor } and throwing new errors.ActorError(group, code, message, { metadata, actor }) — no rayId is threaded there, and the underlying client-protocol BARE schema for that message has no rayId field at all. So ray IDs are only exposed for:

• HTTP action/request errors (response header)
• WebSocket close events (group.code#rayId in the close reason)
• the NAPI native-callback round trip

but not for the (likely most common) case of an action call failing over an already-connected WebSocket. If that's an intentional first pass (e.g. avoiding a *.bare protocol version bump per CLAUDE.md's rule on not modifying published wire schemas casually), it'd be worth a one-line note or follow-up issue so it isn't lost; otherwise this looks like the natural next place rayId should flow.

Minor

• No test coverage was added for the WS close-reason rayId threading (actor-conn.ts) or the scheduling-error retry path (actor-query.ts / actor-handle.ts#shouldRetrySchedulingError) — only the HTTP action-error path and the NAPI bridge round-trip are tested. Given how mechanical the plumbing is this is low risk, but a small parseWebSocketCloseReason/close-event test would close the loop.

No correctness bugs, security concerns, or performance issues found; this is a straightforward, additive change to error diagnostics.