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

[abcxff]

No description provided.

[abcxff]

Stack for rivet-dev/actors

• #5593 fix(rivetkit-core): always signal actor stop handle on teard …
• #5603 fix(rivetkit): expose engine ray IDs on errors for debug 👈
• 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)
website	❌ Build Failed (View Logs)	Web	Aug 31, 2026 at 5:08 pm
frontend-cloud	😴 Sleeping (View Logs)	Web	Aug 31, 2026 at 3:48 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Aug 29, 2026 at 12:50 pm
kitchen-sink	😴 Sleeping (View Logs)	Web	Aug 27, 2026 at 3:31 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

[claude]

Review: expose engine ray IDs on errors for debug

Overall this is a clean, well-scoped change. I traced the ray ID plumbing end-to-end across all the boundaries it touches and it's consistent:

• HTTP path: x-rivet-ray-id is set unconditionally server-side (api-builder/src/middleware.rs) and read from the response header on the client (client/utils.ts, actor-handle.ts), not from the JSON body. This is a good design choice, it avoids needing to bump the HttpResponseErrorSchema/BARE wire schema at all, so no protocol version churn.
• WebSocket close path: parseWebSocketCloseReason correctly parses the existing {group}.{code}#{ray_id} format produced by guard-core/src/utils.rs::err_to_close_frame, which was already in place before this PR.
• NAPI bridge round-trip: BridgeRivetErrorContext/BridgeRivetErrorPayload thread ray_id through parse_bridge_rivet_error -> anyhow_to_bridge_rivet_error_payload correctly, and the added Rust test (actor_factory.rs moved_tests) exercises the full round trip via the #[path] test shim per the repo's convention.
• TS RivetError/decodeBridgeRivetErrorPayload: correctly coerces the native bridge's rayId: null to undefined, with a regression test for it. The "keeps ray ID separate from application metadata" test is a good addition given rayId and user metadata.rayId could otherwise be confused.
• Effect-package (RivetError.ts) getters follow the exact same delegation pattern as the existing public/statusCode getters, so no new inconsistency there.

Gap: WebSocket in-band Error protocol messages do not carry a ray ID

In actor-conn.ts, action/connection errors delivered via the WS protocol's Error message tag (as opposed to a close frame) are destructured from response.body.val as { group, code, message, metadata, actionId, actor } (around lines 737 and 765). There is no rayId in that wire message, so ActorError instances built from that path (both the per-action inFlight.reject(...) around line 757 and the connection-level errorToThrow around line 787) never get a ray ID, even after this PR. The checkForSchedulingError call at line 792 in that same function also was not updated to pass a rayId param, unlike its sibling call in the close-handler further down which was.

This is presumably intentional given the "never modify a published *.bare protocol version" constraint (adding rayId there would need a new schema version), but it does mean the debugging feature only covers HTTP action calls, WS close/disconnect, and NAPI-bridge callback errors, not action errors reported over an already-open persistent WebSocket connection, which is a common way actors are called. Worth a one-line note in the PR description or a follow-up ticket if full coverage is the goal, since it is easy to assume "ray ID is now on all ActorErrors" from the PR title.

Minor / test coverage

• No unit test for parseWebSocketCloseReason's new rayId extraction or for the actor-conn.ts wiring that attaches it to the thrown ActorError/actorSchedulingError. The new tests in rivet-error.test.ts cover the bridge round-trip and the HTTP-header path well, but the WS close-reason path is untested.
• docs-internal/engine/napi-bridge.md update matches the actual payload shape.

Nothing here blocks the PR; the WS in-band gap is the one thing worth a decision on (accept as scoped, or track as a follow-up).