feat: Add CapTP infrastructure for kernel communication #751

rekmarks · 2026-01-14T22:25:20Z

Answers @kumavis's challenge of "What're you afraid of CapTP or something?" by replacing our kernel JSON-RPC API with E() on a facet of the kernel. This makes it easy to expose as much of the kernel API as we want via eventual send, and allows us to benefit from pipelining internally. In addition, it facilitates the removal of the command stream and the related RPC API logic. Finally, a number of rationalizations are applied to the extension and omnium.

This PR is part of a stack followed by: #752, #753, and #754

Note

Introduces CapTP-based communication and removes the JSON-RPC command stream.

Add CapTP utilities in kernel-browser-runtime: makeBackgroundCapTP, makeKernelCapTP, makeKernelFacade, and JSON-RPC captp notification helpers; export new KernelFacade and CapTPMessage types
Update kernel-worker to use CapTP for background↔kernel messaging; initialize kernel without a command stream; route internal RPC only for panel/internal comms
Refactor @metamask/ocap-kernel to drop command stream handling and kernel RPC entrypoints; Kernel.make now accepts only platform services and the database; adjust stop() accordingly
Migrate extension and omnium backgrounds/offscreens to CapTP over ChromeRuntimeDuplexStream, use global E and kernel/omnium helpers; remove env/dev-console and background trusted prelude files; add TS globals
Add unit and integration tests for CapTP (background-captp, kernel-side CapTP, and E() end-to-end); introduce vitest.integration.config.ts and test:integration scripts; CI gains an "Integration Tests" job
Update deps (add @endo/captp, @endo/eventual-send), tsconfigs, build constants, and minor coverage thresholds

^{Written by Cursor Bugbot for commit cbf22fd. This will update automatically on new commits. Configure here.}

…tion Implements userspace E() infrastructure using @endo/captp to enable the background script to use E() naturally with kernel objects. Key changes: - Add CapTP setup on kernel side (kernel-browser-runtime): - kernel-facade.ts: Creates kernel facade exo with makeDefaultExo - kernel-captp.ts: Sets up CapTP endpoint with kernel facade as bootstrap - message-router.ts: Routes messages between kernel RPC and CapTP - Add CapTP setup on background side (omnium-gatherum): - background-captp.ts: Sets up CapTP endpoint to connect to kernel - types.ts: TypeScript types for the kernel facade - Update message streams to use JsonRpcMessage for bidirectional support - CapTP messages wrapped in JSON-RPC notifications: { method: 'captp', params: [msg] } - Make E globally available in background via defineGlobals() - Expose omnium.getKernel() for obtaining kernel remote presence Usage: const kernel = await omnium.getKernel(); const status = await E(kernel).getStatus(); 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…cture Completes the migration from JSON-RPC to CapTP for background ↔ kernel communication and harmonizes the extension and omnium-gatherum packages. Remove the Kernel internal RPC infrastructure entirely: - Remove commandStream parameter from Kernel constructor and make() method - Remove #commandStream and #rpcService private fields - Remove #handleCommandMessage method and stream draining logic - Delete packages/ocap-kernel/src/rpc/kernel/ directory (contained only ping handler) - Update all Kernel.make() call sites across packages The Kernel no longer accepts or processes JSON-RPC commands directly. All external communication now flows through CapTP via the KernelFacade. Move background CapTP infrastructure from omnium-gatherum to kernel-browser-runtime: - Move background-captp.ts to packages/kernel-browser-runtime/src/ - Export from kernel-browser-runtime index: makeBackgroundCapTP, isCapTPNotification, getCapTPMessage, makeCapTPNotification, and related types - Delete packages/omnium-gatherum/src/captp/ directory - Delete packages/kernel-browser-runtime/src/kernel-worker/captp/message-router.ts (no longer needed since all communication uses CapTP) Both omnium-gatherum and extension now import CapTP utilities from kernel-browser-runtime. Update extension to use CapTP/E() instead of RpcClient: - Replace RpcClient with makeBackgroundCapTP in background.ts - Add getKernel() method to globalThis.kernel for E() usage - Update ping() to use E(kernel).ping() instead of rpcClient.call() - Remove @metamask/kernel-rpc-methods and @MetaMask/ocap-kernel dependencies Harmonize extension trusted prelude setup with omnium: - Delete extension separate dev-console.js and background-trusted-prelude.js - Add global.d.ts with TypeScript declarations for E and kernel globals - Both packages now use the same pattern: defineGlobals() call at module top Remove unused dependencies flagged by depcheck: - kernel-browser-runtime: Remove @endo/promise-kit - extension: Remove @MetaMask/ocap-kernel, @metamask/utils - kernel-test: Remove @metamask/streams, @metamask/utils - nodejs: Remove @metamask/utils - omnium-gatherum: Remove @endo/captp, @endo/marshal, @metamask/kernel-rpc-methods, @MetaMask/ocap-kernel, @metamask/utils Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add comprehensive tests for the CapTP infrastructure: - background-captp.test.ts: Tests for utility functions and makeBackgroundCapTP - kernel-facade.test.ts: Tests for facade delegation to kernel methods - kernel-captp.test.ts: Tests for makeKernelCapTP factory - captp.integration.test.ts: Full round-trip E() tests with real endoify Configure vitest with inline projects to use different setupFiles: - Unit tests use mock-endoify for isolated testing - Integration tests use real endoify for CapTP/E() functionality 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ntegration Split the vitest configuration into two separate files to fix issues with tests running from the repo root: - vitest.config.ts: Unit tests with mock-endoify - vitest.integration.config.ts: Integration tests with node-endoify Add test:integration script to run integration tests separately. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

rekmarks · 2026-01-15T00:12:33Z

.github/workflows/lint-build-test.yml

          node-version: ${{ matrix.node-version }}
        env:
          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+      - run: yarn build


In general I hate that we have to build before anything except the e2e tests but we already live in sin so this is fine for now. I'm of a mind to start caching builds in CI after this PR.

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-facade.test.ts

rekmarks · 2026-01-15T01:15:30Z

@claude review

packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts

…stream messages

packages/extension/src/background.ts

packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts

FUDCo · 2026-01-16T19:55:53Z

packages/extension/src/offscreen.ts

+import { delay, isJsonRpcMessage } from '@metamask/kernel-utils';
+import type { JsonRpcMessage } from '@metamask/kernel-utils';


If we are swapping out JSON-RPC for CapTP as our IPC layer, what's going on here? The changes to this file substitute JsonRpcMessage for both JsonRpcCall and JsonRpcResponse, but it's still JsonRpcSomething. One of the things I find very pleasing about this PR is the net code reduction from getting rid of all the JSON-RPC boilerplate, but this particular change right here puzzles me.

Ah, we get rid of the RPC Client / Server stuff and the kernel's command stream, but the captp wire messages have a JSON-RPC wrapper. This buys us a little bit of flexibility in case we ever want to pass other kinds of data over these streams. I think I can just remove the wrapper without side effects if you feel strongly about it.

I may actually have found another message type we want to pass over this stream so I think it's best to leave it.

FUDCo · 2026-01-16T22:01:33Z

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-captp.ts

+/**
+ * A CapTP message that can be sent over the wire.
+ */
+export type CapTPMessage = Record<string, Json>;


I notice this type is also defined the same way with the same name and exported in packages/kernel-browser-runtime/src/background-captp.ts. That feels a little sketchy to me.

FUDCo

This is looking very good. I can feel my blood pressure dropping.

Holding off on clicking Approve right now because I'm unsure what automatic mayhem doing that might trigger. I think we might need to coordinate the order of landing with my latest PR #744 to minimize merge nightmares.

FUDCo

Woot!

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-01-20T19:32:22Z

packages/extension/src/background.ts

 */
-async function startDefaultSubcluster(): Promise<void> {
-  const kernelStream = await connectToKernel({ label: 'background', logger });
-  const rpcClient = new RpcClient(


Missing stream cleanup on initialization failure causes duplicate listeners

Medium Severity

When main() fails after creating offscreenStream but before completing (e.g., during ping()), the stream and its chrome.runtime.onMessage listener are never cleaned up. When start() triggers a retry, a new stream is created with another listener. Both listeners remain active, causing messages to be delivered to both the old orphaned backgroundCapTP and the new one. This leads to duplicate message processing and potential state corruption in the CapTP protocol.

Additional Locations (1)

packages/omnium-gatherum/src/background.ts#L86-L129

rekmarks and others added 4 commits January 14, 2026 11:21

feat(omnium): Add dev console object to background

773f8d9

rekmarks requested a review from a team as a code owner January 14, 2026 22:25

rekmarks mentioned this pull request Jan 14, 2026

feat(omnium): Add controller architecture #752

Draft

rekmarks and others added 4 commits January 14, 2026 15:29

fix: Fix browser-runtime integration test config

56d6ead

chore: Build before integration tests in CI

1c07cdf

chore: Add @ocap/nodejs dev dep to browser-runtime

8c4927e

rekmarks commented Jan 15, 2026

View reviewed changes

cursor bot reviewed Jan 15, 2026

View reviewed changes

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-facade.test.ts Outdated Show resolved Hide resolved

rekmarks added 5 commits January 14, 2026 16:26

refactor: Rationalize kernel promise handling in backgrounds

916f94a

test: Fix some slop in browser-runtime tests

e9b82e0

test: Further browser-runtime test rationalizations

da8a92c

refactor: Remove extraneous comments and type casts

fa89c36

chore: Fix test coverage values

25aad34

This comment was marked as resolved.

Sign in to view

refactor: Respond to Claude's review

91d5741

cursor bot reviewed Jan 15, 2026

View reviewed changes

packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts Show resolved Hide resolved

refactor: Use consistent error throwing pattern for unexpected CapTP …

bef3b9d

…stream messages

cursor bot reviewed Jan 15, 2026

View reviewed changes

packages/extension/src/background.ts Show resolved Hide resolved

packages/extension/src/background.ts Show resolved Hide resolved

refactor: Make background changes compatible with re-executing main()

6e88cad

cursor bot reviewed Jan 15, 2026

View reviewed changes

packages/extension/src/background.ts Show resolved Hide resolved

packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts Show resolved Hide resolved

refactor: Abort kernel-side captp connection on stream failure as well

fc29d6b

FUDCo reviewed Jan 16, 2026

View reviewed changes

Merge branch 'main' into rekm/captp-infrastructure

aacb481

refactor(browser-runtime): Deduplicate types

cbf22fd

rekmarks enabled auto-merge January 20, 2026 19:25

FUDCo approved these changes Jan 20, 2026

View reviewed changes

rekmarks added this pull request to the merge queue Jan 20, 2026

Merged via the queue into main with commit 399c457 Jan 20, 2026
28 checks passed

rekmarks deleted the rekm/captp-infrastructure branch January 20, 2026 19:31

cursor bot reviewed Jan 20, 2026

View reviewed changes

		import { delay, isJsonRpcMessage } from '@metamask/kernel-utils';
		import type { JsonRpcMessage } from '@metamask/kernel-utils';

feat: Add CapTP infrastructure for kernel communication #751

feat: Add CapTP infrastructure for kernel communication #751

Uh oh!

Conversation

rekmarks commented Jan 14, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rekmarks Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rekmarks commented Jan 15, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FUDCo Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rekmarks Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

FUDCo Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FUDCo left a comment

Choose a reason for hiding this comment

Uh oh!

FUDCo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 20, 2026

Choose a reason for hiding this comment

Missing stream cleanup on initialization failure causes duplicate listeners

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rekmarks commented Jan 14, 2026 •

edited by cursor bot

Loading

rekmarks Jan 16, 2026 •

edited

Loading

FUDCo Jan 16, 2026 •

edited

Loading