refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript

[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
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747 👈 (View in Graphite)
• 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: refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript

The direction here is sound. keepAwake(promise) is a strictly better API than a stateful boolean flag, and the deprecation is appropriate. However, there are a few issues worth addressing before this merges.

HIGH SEVERITY: agent-os calls become silent no-ops on the native path

File: rivetkit-typescript/packages/rivetkit/src/agent-os/actor/index.ts

syncPreventSleep() at line ~108 calls c.setPreventSleep(shouldPrevent) to hold the actor awake while activeSessionIds, activeProcesses, hooks, or shells are active. After this PR, that call is a no-op on the native NAPI path.

Individual hooks are wrapped in c.waitUntil(promise) which covers hook-lifetime work. But activeSessionIds and activeProcesses are long-lived Sets that are not wrapped in keepAwake. Actors on the native path may sleep prematurely while sessions or processes are still active.

Recommendation: Before merging, migrate agent-os to keepAwake with a long-lived promise per tracked session/process, or use noSleep on the native path if the actor should never idle-sleep during active work.

MEDIUM SEVERITY: No runtime signal when setPreventSleep is called on the native path

instance/mod.ts retains the full live setPreventSleep / preventSleep implementation. On the legacy engine-runner path, setPreventSleep(true) still genuinely blocks sleep. On the native NAPI path it is silently ignored. A compile-time @deprecated alone will not surface this to users at runtime.

Recommendation: Emit a console.warn or structured log when setPreventSleep is called on the native path so users get a runtime signal, not just a type-checker hint.

MEDIUM SEVERITY: keepAwake is still marked @deprecated in instance/mod.ts

instance/mod.ts line ~1610 has JSDoc marking keepAwake as deprecated in favor of setPreventSleep, the exact inverse of this PR intent. workflow/context.ts correctly removes the deprecated annotation from keepAwake but instance/mod.ts was not updated.

LOW SEVERITY: Minor doc inconsistencies

• waitUntil JSDoc in workflow/context.ts (line ~548) still lists c.setPreventSleep(true) as an alternative. Should reference keepAwake now.
• Two Zod .describe() strings in config.ts (lines ~1773, ~1811) reference the deprecated API and may surface to tooling/introspection consumers.
• Docs not updated: website/src/content/docs/actors/lifecycle.mdx and related pages still use setPreventSleep as the idiomatic example. Flagging per CLAUDE.md docs-sync conventions (the PR checklist already marks this incomplete).

The agent-os regression is the main blocker. Everything else is cleanup.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4747

All packages published as 0.0.0-pr.4747.40e2709 with tag pr-4747.

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-40e2709
docker pull rivetdev/engine:full-40e2709

Individual packages

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