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]

• chore(kitchen-sink): configurable endpoint #4766 : 3 dependent PRs (#4754 , #4777 , #4778 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• 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]

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

Overview

This PR replaces the keepAwake implementation on the native path from using registerTask (NAPI-side task tracking channel) to using the core keep_awake API (increments the sleep-blocking counter directly in rivetkit-core). This is a meaningful semantic improvement: the old path only tracked the task for shutdown ordering, while the new path correctly blocks both idle sleep and grace finalize until the promise settles.

---

Issues

Missing rejection logging in NAPI keep_awake

The new NAPI method passes the promise directly to core without handling rejections:

pub async fn keep_awake(
    &self,
    promise: Promise<serde_json::Value>,
) -> napi::Result<serde_json::Value> {
    self.inner.keep_awake(promise).await
}

Both sibling methods log when their promise rejects:

• wait_until — tracing::warn!(?error, "actor wait_until promise rejected")
• register_task — tracing::warn!(?error, "actor keep_awake promise rejected")

The new keep_awake silently drops rejections (the void callNative(...) on the TypeScript side swallows the resulting NAPI error). If the original promise rejects, the keep-awake guard is properly decremented (RAII _guard drop), but the rejection goes unlogged. Consider adding the same warning pattern:

pub async fn keep_awake(
    &self,
    promise: Promise<serde_json::Value>,
) -> napi::Result<()> {
    self.inner.keep_awake(async move {
        if let Err(error) = promise.await {
            tracing::warn!(?error, "actor keep_awake promise rejected");
        }
    }).await;
    Ok(())
}

This also simplifies the return type to () since the caller ignores the value anyway.

---

Redundant Promise.resolve() wrapper

this.#ctx.keepAwake(Promise.resolve(promise).then(() => null)),

promise is already a Promise<T>, so Promise.resolve(promise) is a no-op. Can be simplified to:

this.#ctx.keepAwake(promise.then(() => null)),

---

Silent error discard vs. the old targeted swallow

The old code swallowed only isClosedTaskRegistrationError (task registration closed/not configured during teardown) while letting other errors surface. The new code uses void callNative(...) which silently swallows all errors from the native call itself (distinct from the promise rejection). This is probably fine since core's keep_awake doesn't use a closeable channel, but it is a broader suppression than what CLAUDE.md recommends ("Swallow only that specific bridge error"). A comment noting the trade-off, or a targeted error filter, would make the intent explicit.

---

No driver tests for the semantic change

The core keep_awake tests (e.g., sleep_shutdown_waits_for_keep_awake_work_then_finishes_next_tick in rivetkit-core/tests/modules/task.rs) cover the Rust side, but there are no TypeScript driver tests verifying that the native keepAwake path actually blocks idle sleep. Given that the old implementation silently failed to block sleep (it only used register_task), a driver-level test would be valuable to prevent regression.

---

Positive notes

• Clean simplification: the old path was more complex (sync call, error type check, detached tracking). The new path is shorter and the semantics match the documented intent.
• The _guard in core's keep_awake is RAII, so the counter is correctly decremented on both success and error/panic paths.
• Comment in native.ts clearly explains the non-obvious detail that core only observes the settle signal, not the value.
• The index.d.ts type declaration correctly reflects the new async signature.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4748

All packages published as 0.0.0-pr.4748.ee4cd1d 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-ee4cd1d
docker pull rivetdev/engine:full-ee4cd1d

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