feat(rivetkit): expose c.keepAwake(promise) through native path

[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

[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

• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748 👈 (View in Graphite)
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

PR Review: feat(rivetkit): expose c.keepAwake(promise) through native path

Overview

This PR routes the native-path keepAwake through a new keep_awake NAPI method that directly uses rivetkit-core's keep-awake counter (via a KeepAwakeGuard), replacing the previous registerTask approach. The core semantics are the same - prevent idle sleep while the promise is in flight - but the mechanism is now more direct and properly maps to the SleepController keep-awake counter.

---

Issues

1. Silent error swallowing (significant)

The old code explicitly caught and only swallowed isClosedTaskRegistrationErrors, rethrowing everything else. The new code uses void on the returned Promise, which silently drops all errors, including genuine unexpected failures from callNative. This violates the project's fail-by-default rule.

If the wrapped JS promise rejects, the NAPI keep_awake method propagates that rejection back through the bridge, callNative normalizes it into a RivetError, and then void silently discards it with no log or warning. Compare to wait_until in Rust, which explicitly logs a warning on rejection.

Suggested fix - add a .catch to at least warn on unexpected bridge errors:

void callNative(() =>
    this.#ctx.keepAwake(promise.then(() => null)),
).catch((error) => {
    if (!isClosedTaskRegistrationError(error)) {
        logger().warn('keep_awake bridge error', { error });
    }
});

Alternatively, restructure the NAPI method to match the wait_until pattern: handle the rejection inside Rust with a tracing::warn! and return Ok(()), so the TS-side void is safe.

2. Unnecessary Promise.resolve() wrap

promise is already a Promise<T>; wrapping it with Promise.resolve(promise) adds an extra microtask tick for no reason. promise.then(() => null) is sufficient.

3. Pre-existing: misleading log message in register_task

In actor_context.rs:639, inside the register_task body, the log reads "actor keep_awake promise rejected". It should say "actor register_task promise rejected". Not introduced by this PR, but easy to fix in the same change.

---

What's working well

• The core semantics are correct. keep_awake in rivetkit-core directly increments/decrements sleep_keep_awake_count via a RAII guard, which is the right primitive to use here.
• Removing the isClosedTaskRegistrationError swallow is appropriate: keep_awake in core has no "closed" state, so the counter is always valid to increment.
• The TypeScript-side contract (keepAwake<T> returns the original Promise<T> unchanged) is preserved correctly.
• The index.d.ts type declaration is correctly added.

---

Test coverage

No new tests cover the native-path keepAwake behavior. The existing rivetkit-core Rust tests (e.g. sleep_shutdown_waits_for_keep_awake_work_then_finishes_next_tick) verify the core guard semantics, but there are no driver-level integration tests that exercise the NAPI bridge path specifically - e.g. asserting the actor stays alive while a c.keepAwake(promise) is in flight. Worth adding a driver test before merging.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4748

All packages published as 0.0.0-pr.4748.d1a6ff3 with tag pr-4748.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-d1a6ff3
docker pull rivetdev/engine:full-d1a6ff3

Individual packages

npm install rivetkit@pr-4748
npm install @rivetkit/react@pr-4748
npm install @rivetkit/rivetkit-napi@pr-4748
npm install @rivetkit/workflow-engine@pr-4748