feat(inspector): expose http api for inspector

[jog1t]

Description

This pull request refactors database type definitions and adds new client protocol schema support. The main changes include:

• Moved database type definitions (DatabaseColumn, DatabaseForeignKey, DatabaseTableInfo, DatabaseSchema) from the actor inspector context to a centralized types file in the inspector module
• Added client protocol v4 schema with new HTTP inspector endpoints for queue status and workflow history
• Updated the build schema script to include v4 compilation
• Added new router endpoints for handling queue requests, workflow history requests, and database schema requests
• Implemented versioned data handlers for the new HTTP inspector response types
• Updated imports to use the centralized type definitions

Type of change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• 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?

The changes include schema compilation and type safety improvements. Testing should verify that the new inspector endpoints return properly formatted responses and that the type definitions are correctly exported and imported.

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

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Feb 20, 2026 at 10:34 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 20, 2026 at 10:21 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 20, 2026 at 10:21 pm
ladle	❌ Build Failed (View Logs)	Web	Feb 20, 2026 at 10:21 pm
mcp-hub	✅ Success (View Logs)	Web	Feb 19, 2026 at 11:26 pm

[jog1t]

• feat(inspector): expose http api for inspector #4245 👈 (View in Graphite)
• 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(inspector): expose http api for inspector

Note: This PR is still in draft. Reviewing current state to provide early feedback.

---

Summary

This PR exposes HTTP API endpoints for the actor inspector (queue status, workflow history, database schema) and introduces a new client protocol v4 with versioned serialization for inspector responses. It also consolidates database-related TypeScript types into a shared inspector/types.ts module.

---

Critical Issues

1. Incomplete handleWorkflowHistoryRequest — no return statement

File: rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts

export async function handleWorkflowHistoryRequest(
    c: HonoContext,
    actorDriver: ActorDriver,
) {
    const actor = await actorDriver.loadActor(c.env.actorId);
    if (!actor.inspector.isWorkflowEnabled()) {
        throw new errors.InvalidRequest("Workflow history is not enabled");
    }

    const history = actor.inspector.getWorkflowHistory();
    // TODO:
}

This function has no return statement after retrieving the history. It will always resolve to undefined, which is almost certainly a bug. The // TODO: comment suggests this was left unfinished. Additionally, this function is never registered as a route in router.ts.

2. Stray no-op route registration

File: rivetkit-typescript/packages/rivetkit/src/actor/router.ts

router.get("/");

A route is registered with no handler, which is a no-op or an error depending on the framework. This looks like leftover debugging code and should be removed.

---

Bugs

3. handleQueueRequest has no fallback for missing limit parameter

File: rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts

const limit = z.coerce.number().positive().safeParse(c.req.query("limit"));
if (!limit.success) {
    throw new errors.InvalidRequest("Invalid limit parameter");
}

When limit is absent from the query string, c.req.query("limit") returns undefined, which fails Zod validation and throws. The existing /inspector/queue handler correctly defaults to "50":

const limit = parseInt(c.req.query("limit") ?? "50", 10);

Consider using z.coerce.number().positive().default(50).safeParse(c.req.query("limit")) or the same ?? "50" pattern.

4. handleDatabaseSchemaRequest defined but never registered

File: rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts

handleDatabaseSchemaRequest is implemented but no corresponding route is added in router.ts. Either the route was forgotten or the function is dead code.

5. Dual queue endpoints with different serialization

There are now two queue-related endpoints:

• GET /inspector/queue — in router.ts using versioned BARE/CBOR serialization
• GET /queue — via handleQueueRequest in router-endpoints.ts returning plain JSON (c.json({ queues: queueNames }))

These return different shapes and use different serialization formats. If they both exist intentionally, the purpose and difference should be documented. If one is redundant, it should be removed.

---

Code Quality

6. Double cast body as Uint8Array as any

File: rivetkit-typescript/packages/rivetkit/src/actor/router.ts

return c.body(body as Uint8Array as any, 200, { ... });

The double cast suggests a type mismatch being suppressed. Either the return type of serializeWithEncoding should be corrected, or the c.body call should be adjusted. Avoid using as any to paper over type issues.

7. Identity protocol converters for v4

File: rivetkit-typescript/packages/rivetkit/src/schemas/client-protocol/versioned.ts

The v3→v4 converters for both ToClient and ToServer are identity casts with no actual transformation:

const v3ToV4 = (v3Data: v3.ToClient): v4.ToClient => {
    return v3Data as unknown as v4.ToClient;
};

If the wire format is identical between v3 and v4, it may not be worth bumping the protocol version. The new HTTP inspector types (HttpInspectorQueueResponse, HttpInspectorWorkflowHistoryResponse) are only used for HTTP responses and don't affect the WebSocket message protocol. Consider whether a version bump is actually necessary here.

---

Style / Conventions

8. Missing newline at end of file

Three new/modified files are missing trailing newlines (indicated by \ No newline at end of file in the diff):

• rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts
• rivetkit-typescript/packages/rivetkit/src/inspector/mod.browser.ts
• rivetkit-typescript/packages/rivetkit/src/inspector/types.ts

9. Indentation in types.ts

File: rivetkit-typescript/packages/rivetkit/src/inspector/types.ts

The file uses 4-space indentation, while the surrounding codebase uses tabs. This should be made consistent.

10. Single quotes in mod.browser.ts

export * from './types';

The rest of the file (and the project's Biome config) uses double quotes. Run the linter to catch this.

---

Missing Per Project Guidelines

Per CLAUDE.md, when adding or modifying inspector endpoints:

• Documentation — website/src/metadata/skill-base-rivetkit.md and website/src/content/docs/actors/debugging.mdx must be updated. Neither is included in this PR.
• Tests — rivetkit-typescript/packages/rivetkit/src/driver-test-suite/tests/actor-inspector.ts must be updated to cover the new HTTP endpoints. No tests are added in this PR.

---

Positives

• The type consolidation (moving DatabaseColumn, DatabaseTableInfo, etc. from the frontend context into inspector/types.ts) is a clean improvement that avoids duplication.
• The Zod schema additions for inspector responses are well-structured.
• The versioned handler pattern for the new HTTP inspector responses is consistent with the existing codebase patterns.
• pnpm lockfile cleanup removing unused packages (example-registry, rivetkit-typescript/packages/db, puppeteer) looks appropriate.

---

Review generated by Claude Code

[graphite-app]

Incomplete route definition. The line router.get("/"); has no handler function, which will cause a runtime error. Hono's get() method requires at least a handler function as the second argument.

router.get("/"); // Invalid - missing handler

This line should either be removed if it's not needed, or completed with a proper handler:

router.get("/", async (c) => {
	// handler implementation
});

Spotted by Graphite Agent



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