feat: Add CapTP infrastructure for kernel communication

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

@@ -132,6 +132,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
         env:
           PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+      - run: yarn build
       - run: yarn test:integration
       - name: Require clean working directory
         shell: bash

package.json

@@ -35,6 +35,7 @@
     "test:e2e": "yarn workspaces foreach --all run test:e2e",
     "test:e2e:ci": "yarn workspaces foreach --all run test:e2e:ci",
     "test:e2e:local": "yarn workspaces foreach --all run test:e2e:local",
+    "test:integration": "yarn workspaces foreach --all run test:integration",
     "test:verbose": "yarn test --reporter verbose",
     "test:watch": "vitest",
     "why:batch": "./scripts/why-batch.sh"

packages/extension/package.json

@@ -42,15 +42,13 @@
     "test:e2e:debug": "playwright test --debug"
   },
   "dependencies": {
+    "@endo/eventual-send": "^1.3.4",
     "@metamask/kernel-browser-runtime": "workspace:^",
-    "@metamask/kernel-rpc-methods": "workspace:^",
     "@metamask/kernel-shims": "workspace:^",
     "@metamask/kernel-ui": "workspace:^",
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",
-    "@metamask/ocap-kernel": "workspace:^",
     "@metamask/streams": "workspace:^",
-    "@metamask/utils": "^11.9.0",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "ses": "^1.14.0"

packages/extension/scripts/build-constants.mjs

@@ -18,7 +18,7 @@ export const kernelBrowserRuntimeSrcDir = path.resolve(
  */
 export const trustedPreludes = {
   background: {
-    path: path.resolve(sourceDir, 'env/background-trusted-prelude.js'),
+    content: "import './endoify.js';",
   },
   'kernel-worker': { content: "import './endoify.js';" },
 };

packages/extension/src/background.ts

@@ -1,20 +1,32 @@
+import { E } from '@endo/eventual-send';
 import {
-  connectToKernel,
-  rpcMethodSpecs,
+  makeBackgroundCapTP,
+  makeCapTPNotification,
+  isCapTPNotification,
+  getCapTPMessage,
+} from '@metamask/kernel-browser-runtime';
+import type {
+  KernelFacade,
+  CapTPMessage,
 } from '@metamask/kernel-browser-runtime';
 import defaultSubcluster from '@metamask/kernel-browser-runtime/default-cluster';
-import { RpcClient } from '@metamask/kernel-rpc-methods';
-import { delay } from '@metamask/kernel-utils';
-import type { JsonRpcCall } from '@metamask/kernel-utils';
+import { delay, isJsonRpcMessage, stringify } from '@metamask/kernel-utils';
+import type { JsonRpcMessage } from '@metamask/kernel-utils';
 import { Logger } from '@metamask/logger';
-import { kernelMethodSpecs } from '@metamask/ocap-kernel/rpc';
 import { ChromeRuntimeDuplexStream } from '@metamask/streams/browser';
-import { isJsonRpcResponse } from '@metamask/utils';
-import type { JsonRpcResponse } from '@metamask/utils';
+
+defineGlobals();
 
 const OFFSCREEN_DOCUMENT_PATH = '/offscreen.html';
 const logger = new Logger('background');
 let bootPromise: Promise<void> | null = null;
+let kernelP: Promise<KernelFacade>;
+let ping: () => Promise<void>;
+
+// With this we can click the extension action button to wake up the service worker.
+chrome.action.onClicked.addListener(() => {
+  ping?.().catch(logger.error);
+});
 
 // Install/update
 chrome.runtime.onInstalled.addListener(() => {
@@ -79,85 +91,98 @@ async function main(): Promise<void> {
   // Without this delay, sending messages via the chrome.runtime API can fail.
   await delay(50);
 
+  // Create stream for CapTP messages
   const offscreenStream = await ChromeRuntimeDuplexStream.make<
-    JsonRpcResponse,
-    JsonRpcCall
-  >(chrome.runtime, 'background', 'offscreen', isJsonRpcResponse);
-
-  const rpcClient = new RpcClient(
-    kernelMethodSpecs,
-    async (request) => {
-      await offscreenStream.write(request);
+    JsonRpcMessage,
+    JsonRpcMessage
+  >(chrome.runtime, 'background', 'offscreen', isJsonRpcMessage);
+
+  // Set up CapTP for E() based communication with the kernel
+  const backgroundCapTP = makeBackgroundCapTP({
+    send: (captpMessage: CapTPMessage) => {
+      const notification = makeCapTPNotification(captpMessage);
+      offscreenStream.write(notification).catch((error) => {
+        logger.error('Failed to send CapTP message:', error);
+      });
     },
-    'background:',
-  );
+  });
+
+  // Get the kernel remote presence
+  kernelP = backgroundCapTP.getKernel();
 
-  const ping = async (): Promise<void> => {
-    const result = await rpcClient.call('ping', []);
+  ping = async () => {
+    const result = await E(kernelP).ping();
     logger.info(result);
   };
 
-  // globalThis.kernel will exist due to dev-console.js in background-trusted-prelude.js
-  Object.defineProperties(globalThis.kernel, {
-    ping: {
-      value: ping,
-    },
-    sendMessage: {
-      value: async (message: JsonRpcCall) =>
-        await offscreenStream.write(message),
-    },
-  });
-  harden(globalThis.kernel);
-
-  // With this we can click the extension action button to wake up the service worker.
-  chrome.action.onClicked.addListener(() => {
-    ping().catch(logger.error);
+  // Handle incoming CapTP messages from the kernel
+  const drainPromise = offscreenStream.drain((message) => {
+    if (isCapTPNotification(message)) {
+      const captpMessage = getCapTPMessage(message);
+      backgroundCapTP.dispatch(captpMessage);
+    } else {
+      throw new Error(`Unexpected message: ${stringify(message)}`);
+    }
   });
-
-  // Pipe responses back to the RpcClient
-  const drainPromise = offscreenStream.drain(async (message) =>
-    rpcClient.handleResponse(message.id as string, message),
-  );
   drainPromise.catch(logger.error);
 
   await ping(); // Wait for the kernel to be ready
-  await startDefaultSubcluster();
+  await startDefaultSubcluster(kernelP);
 
   try {
     await drainPromise;
   } catch (error) {
-    throw new Error('Offscreen connection closed unexpectedly', {
+    const finalError = new Error('Offscreen connection closed unexpectedly', {
       cause: error,
     });
+    backgroundCapTP.abort(finalError);
+    throw finalError;
   }
 }
 
 /**
  * Idempotently starts the default subcluster.
+ *
+ * @param kernelPromise - Promise for the kernel facade.
  */
-async function startDefaultSubcluster(): Promise<void> {
-  const kernelStream = await connectToKernel({ label: 'background', logger });
-  const rpcClient = new RpcClient(
-    rpcMethodSpecs,
-    async (request) => {
-      await kernelStream.write(request);
-    },
-    'background',
-  );
+async function startDefaultSubcluster(
+  kernelPromise: Promise<KernelFacade>,
+): Promise<void> {
+  const status = await E(kernelPromise).getStatus();
 
-  kernelStream
-    .drain(async (message) =>
-      rpcClient.handleResponse(message.id as string, message),
-    )
-    .catch(logger.error);
-
-  const status = await rpcClient.call('getStatus', []);
   if (status.subclusters.length === 0) {
-    const result = await rpcClient.call('launchSubcluster', {
-      config: defaultSubcluster,
-    });
+    const result = await E(kernelPromise).launchSubcluster(defaultSubcluster);
     logger.info(`Default subcluster launched: ${JSON.stringify(result)}`);
   } else {
     logger.info('Subclusters already exist. Not launching default subcluster.');
   }
 }
+
+/**
+ * Define globals accessible via the background console.
+ */
+function defineGlobals(): void {
+  Object.defineProperty(globalThis, 'kernel', {
+    configurable: false,
+    enumerable: true,
+    writable: false,
+    value: {},
+  });
+
+  Object.defineProperties(globalThis.kernel, {
+    ping: {
+      get: () => ping,
+    },
+    getKernel: {
+      value: async () => kernelP,
+    },
+  });
+  harden(globalThis.kernel);
+
+  Object.defineProperty(globalThis, 'E', {
+    value: E,
+    configurable: false,
+    enumerable: true,
+    writable: false,
+  });
+}

packages/extension/src/global.d.ts

@@ -0,0 +1,39 @@
+import type { KernelFacade } from '@metamask/kernel-browser-runtime';
+
+// Type declarations for kernel dev console API.
+declare global {
+  /**
+   * The E() function from @endo/eventual-send for making eventual sends.
+   * Set globally in the trusted prelude before lockdown.
+   *
+   * @example
+   * ```typescript
+   * const kernel = await kernel.getKernel();
+   * const status = await E(kernel).getStatus();
+   * ```
+   */
+  // eslint-disable-next-line no-var,id-length
+  var E: typeof import('@endo/eventual-send').E;
+
+  // eslint-disable-next-line no-var
+  var kernel: {
+    /**
+     * Ping the kernel to verify connectivity.
+     */
+    ping: () => Promise<void>;
+
+    /**
+     * Get the kernel remote presence for use with E().
+     *
+     * @returns A promise for the kernel facade remote presence.
+     * @example
+     * ```typescript
+     * const kernel = await kernel.getKernel();
+     * const status = await E(kernel).getStatus();
+     * ```
+     */
+    getKernel: () => Promise<KernelFacade>;
+  };
+}
+
+export {};

packages/extension/src/offscreen.ts

@@ -3,8 +3,8 @@ import {
   PlatformServicesServer,
   createRelayQueryString,
 } from '@metamask/kernel-browser-runtime';
-import { delay, isJsonRpcCall } from '@metamask/kernel-utils';
-import type { JsonRpcCall } from '@metamask/kernel-utils';
+import { delay, isJsonRpcMessage } from '@metamask/kernel-utils';
+import type { JsonRpcMessage } from '@metamask/kernel-utils';
 import { Logger } from '@metamask/logger';
 import type { DuplexStream } from '@metamask/streams';
 import {
@@ -13,8 +13,6 @@ import {
   MessagePortDuplexStream,
 } from '@metamask/streams/browser';
 import type { PostMessageTarget } from '@metamask/streams/browser';
-import type { JsonRpcResponse } from '@metamask/utils';
-import { isJsonRpcResponse } from '@metamask/utils';
 
 const logger = new Logger('offscreen');
 
@@ -27,11 +25,11 @@ async function main(): Promise<void> {
   // Without this delay, sending messages via the chrome.runtime API can fail.
   await delay(50);
 
-  // Create stream for messages from the background script
+  // Create stream for CapTP messages from the background script
   const backgroundStream = await ChromeRuntimeDuplexStream.make<
-    JsonRpcCall,
-    JsonRpcResponse
-  >(chrome.runtime, 'offscreen', 'background', isJsonRpcCall);
+    JsonRpcMessage,
+    JsonRpcMessage
+  >(chrome.runtime, 'offscreen', 'background', isJsonRpcMessage);
 
   const kernelStream = await makeKernelWorker();
 
@@ -48,7 +46,7 @@ async function main(): Promise<void> {
  * @returns The message port stream for worker communication
  */
 async function makeKernelWorker(): Promise<
-  DuplexStream<JsonRpcResponse, JsonRpcCall>
+  DuplexStream<JsonRpcMessage, JsonRpcMessage>
 > {
   // Assign local relay address generated from `yarn ocap relay`
   const relayQueryString = createRelayQueryString([
@@ -72,9 +70,9 @@ async function makeKernelWorker(): Promise<
   );
 
   const kernelStream = await MessagePortDuplexStream.make<
-    JsonRpcResponse,
-    JsonRpcCall
-  >(port, isJsonRpcResponse);
+    JsonRpcMessage,
+    JsonRpcMessage
+  >(port, isJsonRpcMessage);
 
   await PlatformServicesServer.make(worker as PostMessageTarget, (vatId) =>
     makeIframeVatWorker({

packages/extension/test/build/build-tests.ts

@@ -2,21 +2,13 @@ import { runTests } from '@ocap/repo-tools/build-utils/test';
 import type { UntransformedFiles } from '@ocap/repo-tools/build-utils/test';
 import path from 'node:path';
 
-import {
-  outDir,
-  sourceDir,
-  trustedPreludes,
-} from '../../scripts/build-constants.mjs';
+import { outDir, trustedPreludes } from '../../scripts/build-constants.mjs';
 
 const untransformedFiles = [
   {
     sourcePath: path.resolve('../kernel-shims/dist/endoify.js'),
     buildPath: path.resolve(outDir, 'endoify.js'),
   },
-  {
-    sourcePath: path.resolve(sourceDir, 'env/dev-console.js'),
-    buildPath: path.resolve(outDir, 'dev-console.js'),
-  },
   ...Object.values(trustedPreludes).map((prelude) => {
     if ('path' in prelude) {
       return {