feat(drivers/engine): pass inspector to metadata

[jog1t]

TL;DR

Updated the engine-runner dependency to version 4b0f765 and enhanced actor metadata handling.

What changed?

• Updated @rivetkit/engine-runner from version f8860f3 to 4b0f765
• Added inspector token to actor metadata for improved debugging capabilities
• Modified the prepopulation of actor names to use an object structure with metadata
• Added automatic generation of a random studio token if one doesn't exist
• Removed unused imports (noopNext, WSContext, InternalError)

How to test?

1. Run the application with the updated engine-runner
2. Verify that actors are properly initialized with metadata
3. Check that the inspector token is correctly passed to the engine runner
4. Confirm that reconnection logic works as expected

Why make this change?

This change enhances the actor system by providing better metadata support, which improves debugging capabilities through the inspector token. The updated engine-runner version includes improvements that require these structural changes to the actor initialization process. The automatic token generation ensures that the system always has a valid token for studio operations.

[claude]

Claude finished @jog1t's task —— View job

---

Code Review Completed

I've analyzed this PR that adds inspector token metadata to the engine drivers. Here's my review:

Todo List:

• Read and analyze all changed files
• Review code quality and implementation
• Check for potential bugs and issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage
• Provide comprehensive feedback

---

Summary

This PR updates the engine driver to pass the inspector token as metadata to the engine runner, enabling proper inspector authentication. The changes include updating to a newer engine-runner version and modifying both the actor and manager drivers.

Code Quality & Implementation ✅

• Good: Clean implementation following existing patterns
• Good: Consistent with file-system driver approach (packages/core/src/drivers/file-system/manager.ts:58-61)
• Good: Proper fallback token generation when studio token isn't configured
• Good: Uses existing generateRandomString() utility for token generation

Potential Issues ⚠️

1. Token Security Concern (manager-driver.ts:43-46)

if (!this.#runConfig.studio.token()) {
    const token = generateRandomString();
    this.#runConfig.studio.token = () => token;
}

• Issue: Random tokens are generated without persistence across restarts
• Impact: Inspector connections will break when the service restarts
• Recommendation: Consider using a more stable token generation strategy or persisting tokens

2. Dependency Version Update (package.json:170)

• Issue: Engine-runner version changed from f8860f3 to 4b0f765
• Concern: No commit message or PR description explaining what changed in the engine-runner
• Recommendation: Document what features/fixes this engine-runner version provides

3. prepopulateActorNames Structure Change (actor-driver.ts:90-95)

// Before: Object.keys(this.#registryConfig.use)
// After: Object.fromEntries(Object.keys(...).map(name => [name, { metadata: {} }]))

• Observation: Changed from array to object structure with metadata field
• Status: Appears intentional but should be documented

Security Assessment ✅

• Good: No hardcoded secrets or credentials
• Good: Inspector tokens are properly scoped and not exposed in logs
• Good: Follows existing security patterns from file-system driver

Performance Considerations ✅

• Good: Minimal performance impact
• Good: Token generation happens only once during initialization
• Good: No additional runtime overhead for request handling

Test Coverage ❓

• Missing: No specific tests for the inspector token metadata feature
• Existing: Engine driver tests exist (tests/driver-test-suite-engine.test.ts) but don't cover inspector functionality
• Recommendation: Add test cases to verify:
  • Inspector token is properly passed to engine runner
  • Fallback token generation works when studio token is missing
  • Token consistency across engine driver lifecycle

Breaking Changes ⚠️

• Potential: The prepopulateActorNames structure change might affect external engine-runner consumers
• Mitigation: Engine-runner version update likely handles this compatibility

Recommendations

1. Add PR description explaining:

   • Why this change was needed
   • What the new engine-runner version provides
   • Impact of the prepopulateActorNames structure change

2. Consider token persistence for production scenarios:

   // Consider persisting tokens for service restarts
   if (!this.#runConfig.studio.token()) {
       const token = await getOrCreatePersistedToken(); // hypothetical
       this.#runConfig.studio.token = () => token;
   }

3. Add test coverage for inspector token functionality

4. Document the metadata structure changes in the codebase

Overall Assessment

Approval Recommended ✅

This is a solid implementation that follows existing patterns and enables proper inspector functionality. The security and performance impact is minimal. Main concerns are around token persistence and missing test coverage, but these don't block the core functionality.

---

[jog1t]

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: update sdk #1189
• refactor: studio -> inspector #1185
• feat(drivers/engine): pass inspector to metadata #1184 👈 (View in Graphite)
• fix(inspector): bring back the actor inspector #1174 : 1 other dependent PR (#1175 )
• chore(core): update keys -> key #1183
• chore: update sdk #1182
• feat(engine): add engine driver #1173 : 1 other dependent PR (#1178 )
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

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.

[pkg-pr-new]

More templates

• example-ai-agent
• example-better-auth-external-db
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• counter
• example-crdt
• example-database
• example-sqlite
• example-elysia
• example-express
• example-game
• example-hono
• example-hono-react
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler-proxy
• example-react
• example-redis
• example-redis-hono
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/actor@1184

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/core@1184

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/db@1184

rivetkit

pnpm add https://pkg.pr.new/rivet-gg/rivetkit@1184

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/cloudflare-workers@1184

@rivetkit/redis

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/redis@1184

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/framework-base@1184

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/next-js@1184

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/react@1184

commit: 28bfa65

[graphite-app]

Merge activity

• Sep 2, 9:13 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Sep 2, 9:13 AM UTC: CI is running for this pull request on a draft pull request (#1190) due to your merge queue CI optimization settings.
• Sep 2, 9:14 AM UTC: Merged by the Graphite merge queue via draft PR: #1190.