feat(rivetkit): add run

[NathanFlurry]

No description provided.

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Jan 22, 2026 at 5:48 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Jan 22, 2026 at 5:37 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Jan 22, 2026 at 5:37 am
mcp-hub	❌ Build Failed (View Logs)	Web	Jan 22, 2026 at 5:36 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 clearAlarm #4004
• feat(rivetkit): c.keepAwake #4003
• feat(rivetkit): add run #4002 👈 (View in Graphite)
• feat: actor messages & queues #3989 : 1 other dependent PR (#4005 )
• 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]

Code Review: feat(rivetkit): add run

This PR adds a new run lifecycle hook to RivetKit actors for background tasks. Overall, the implementation is well-designed and follows existing patterns.

Strengths

1. Well-documented feature with comprehensive examples
2. Comprehensive test coverage for all scenarios
3. Follows existing lifecycle hook patterns
4. Clear API design with abort signal for graceful shutdown

Potential Issues

1. Synchronous run handlers are silently ignored (Medium severity)

In mod.ts:917-942, only Promise-returning functions are tracked. If a user defines a synchronous run handler, it executes once and is silently ignored - the actor wont crash as documented.

Recommendation: Add a warning when run returns a non-Promise, or wrap non-Promise results to trigger the crash behavior.

2. Timeout promise cleanup (Low severity)

In #waitForRunHandler (mod.ts:951-956), the setTimeout is not cancelled if the run handler completes first. While the promise result is ignored, the timeout still fires unnecessarily.

Recommendation: Store the timeout handle and clear it when the race completes early.

3. Test coverage gap

Tests for early exit and error scenarios dont verify that destroyCalled is true, even though the fixture tracks this state.

4. Documentation clarity

The docs state "the actor will crash and reschedule" but tests show the file-system driver doesnt auto-reschedule. Consider clarifying what this means across different drivers.

Security & Performance

No security concerns identified. The abort signal pattern properly prevents resource leaks, and the configurable runStopTimeout prevents shutdown hangs.

Summary

Solid implementation of a useful feature. Main issue is handling synchronous run functions. Recommended fixes:

1. Must fix: Handle or warn about synchronous run functions
2. Should fix: Clean up setTimeout in #waitForRunHandler
3. Nice to have: Improve test assertions for destroyCalled

Great work overall!

[graphite-app]

The run handler only crashes the actor if it returns a Promise. If the run handler is synchronous (returns void), it exits immediately without crashing the actor, which violates the documented behavior.

According to the documentation and comments, if the run handler exits (returns), the actor should crash and reschedule. However, the current code only handles the Promise case.

Fix:

#startRunHandler() {
	if (!this.#config.run) return;

	this.#rLog.debug({ msg: "starting run handler" });

	const runResult = this.#config.run(this.actorContext);

	if (runResult instanceof Promise) {
		this.#runPromise = runResult
			.then(() => {
				this.#rLog.warn({
					msg: "run handler exited unexpectedly, crashing actor to reschedule",
				});
				this.startDestroy();
			})
			.catch((error) => {
				this.#rLog.error({
					msg: "run handler threw error, crashing actor to reschedule",
					error: stringifyError(error),
				});
				this.startDestroy();
			});
	} else {
		// Synchronous return - crash immediately
		this.#rLog.warn({
			msg: "run handler exited unexpectedly (synchronous), crashing actor to reschedule",
		});
		this.startDestroy();
	}
}

Suggested change

	#startRunHandler() {
	if (!this.#config.run) return;
	this.#rLog.debug({ msg: "starting run handler" });
	const runResult = this.#config.run(this.actorContext);
	if (runResult instanceof Promise) {
	this.#runPromise = runResult
	.then(() => {
	// Run handler exited normally - this should crash the actor
	this.#rLog.warn({
	msg: "run handler exited unexpectedly, crashing actor to reschedule",
	});
	this.startDestroy();
	})
	.catch((error) => {
	// Run handler threw an error - crash the actor
	this.#rLog.error({
	msg: "run handler threw error, crashing actor to reschedule",
	error: stringifyError(error),
	});
	this.startDestroy();
	});
	}
	}
	#startRunHandler() {
	if (!this.#config.run) return;
	this.#rLog.debug({ msg: "starting run handler" });
	const runResult = this.#config.run(this.actorContext);
	if (runResult instanceof Promise) {
	this.#runPromise = runResult
	.then(() => {
	// Run handler exited normally - this should crash the actor
	this.#rLog.warn({
	msg: "run handler exited unexpectedly, crashing actor to reschedule",
	});
	this.startDestroy();
	})
	.catch((error) => {
	// Run handler threw an error - crash the actor
	this.#rLog.error({
	msg: "run handler threw error, crashing actor to reschedule",
	error: stringifyError(error),
	});
	this.startDestroy();
	});
	} else {
	// Synchronous return - crash immediately
	this.#rLog.warn({
	msg: "run handler exited unexpectedly (synchronous), crashing actor to reschedule",
	});
	this.startDestroy();
	}
	}

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.