feat(rivetkit): add actor run handler

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-4005 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	❌ Build Failed (View Logs)	Web	Jan 30, 2026 at 8:21 am
mcp-hub	✅ Success (View Logs)	Web	Jan 30, 2026 at 8:20 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Jan 28, 2026 at 1:13 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Jan 28, 2026 at 1:13 am

[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

• feat(rivetkit): add actor run handler #4005 : 2 dependent PRs (#3734 , #4008 ) 👈 (View in Graphite)
• feat: actor messages & queues #3989 : 2 other dependent PRs (#4002 , #4088 )
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[claude]

PR Review: feat(rivetkit): add actor run handler

Summary

This PR introduces a run handler as an alias for onWake in the RivetKit actor lifecycle. The change includes proper validation to prevent defining both handlers simultaneously, along with comprehensive documentation updates.

✅ Strengths

1. Clean Implementation: The aliasing is implemented correctly using the nullish coalescing operator (??) to prioritize run over onWake
2. Proper Validation: The Zod schema includes a refinement that prevents users from defining both run and onWake, with a clear error message
3. Type Safety: Both run and onWake are properly included in all relevant type definitions (ActorConfig, ActorConfigInput)
4. Documentation: Extensive documentation updates in the lifecycle guide showing the new run handler with practical examples
5. Backwards Compatibility: Existing code using onWake continues to work without changes

🔍 Code Quality Observations

TypeScript Implementation (config.ts)

• Clean addition to schema validation (line 135-140)
• Consistent JSDoc comments explaining the alias relationship
• Proper inclusion in type definitions (lines 526, 587)

Runtime Implementation (mod.ts)

• Simple, clear implementation with explanatory comment (lines 855-856)
• Uses nullish coalescing to give run priority over onWake

Documentation (lifecycle.mdx)

• Restructured to make run the primary handler with onWake as the documented alias
• All examples updated to use run instead of onWake
• Clear note explaining the relationship between the two

🤔 Considerations & Questions

1. Test Coverage: I don't see test additions for the new run handler. Consider adding tests to verify:

   • That run is called correctly when defined
   • That the validation properly rejects defining both run and onWake
   • That run takes priority when both are somehow defined (though validation should prevent this)

2. Migration Path: While backward compatibility is maintained, there's no guidance for users on:

   • Whether they should migrate from onWake to run
   • If onWake will be deprecated in the future
   • What the long-term plan is for these two handlers

3. Error Message Clarity: The error message could be more actionable:

   message: "Cannot define both 'run' and 'onWake'. 'run' is an alias for 'onWake'.",

   Consider: "Cannot define both 'run' and 'onWake'. Use either 'run' (recommended) or 'onWake'."

4. Documentation Frontmatter: The lifecycle.mdx file has its frontmatter removed (converted to H1). Was this intentional? This might affect:

   • SEO (missing description metadata)
   • Site navigation/sidebar generation
   • The skill: true flag which may be used for features

5. Code Examples in Docs: Several documentation examples have been simplified (types removed, etc.). While this makes them more readable, ensure they're still runnable/accurate. For instance:

   • Line 283: Missing validateToken function definition
   • Line 342: Generic types simplified - verify this still type-checks

🎯 Recommendations

High Priority:

1. Add test coverage for the run handler and mutual exclusion validation
2. Restore the frontmatter in lifecycle.mdx or confirm its removal was intentional
3. Verify all simplified code examples in the documentation are valid

Medium Priority:
4. Consider adding a migration guide or note about the relationship between run and onWake
5. Update error message to be more actionable
6. Consider adding a deprecation notice if onWake will eventually be removed

Low Priority:
7. Add inline examples in the JSDoc for the run handler in config.ts

🔒 Security & Performance

• ✅ No security concerns identified
• ✅ No performance impact (simple aliasing)
• ✅ Proper validation prevents configuration errors

📊 Overall Assessment

This is a well-implemented feature that improves the API ergonomics by providing a more intuitive name for the wake handler. The implementation is clean and maintains backward compatibility. The main areas for improvement are test coverage and clarifying the documentation changes (particularly the frontmatter removal).

Recommendation: Approve with minor changes (add tests, verify documentation frontmatter)

[graphite-app]

Merge activity

• Feb 4, 8:36 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 4, 8:37 PM UTC: CI is running for this pull request on a draft pull request (#4114) due to your merge queue CI optimization settings.
• Feb 4, 8:38 PM UTC: Merged by the Graphite merge queue via draft PR: #4114.