feat(omnium): Add controller architecture

packages/extension/src/background.ts

@@ -126,8 +126,12 @@ async function main(): Promise<void> {
   });
   drainPromise.catch(logger.error);
 
-  await ping(); // Wait for the kernel to be ready
-  await startDefaultSubcluster(kernelP);
+  try {
+    await ping(); // Wait for the kernel to be ready
+    await startDefaultSubcluster(kernelP);
+  } catch (error) {
+    offscreenStream.throw(error as Error).catch(logger.error);
+  }
 
   try {
     await drainPromise;

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

@@ -2,7 +2,7 @@ import type { Kernel } from '@metamask/ocap-kernel';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 import { makeKernelCapTP } from './kernel-captp.ts';
-import type { CapTPMessage } from './kernel-captp.ts';
+import type { CapTPMessage } from '../../types.ts';
 
 describe('makeKernelCapTP', () => {
   const mockKernel: Kernel = {} as unknown as Kernel;

packages/kernel-utils/src/index.ts

@@ -12,6 +12,7 @@ export type {
   JsonRpcCall,
   JsonRpcMessage,
   PromiseCallbacks,
+  Promisified,
   TypeGuard,
 } from './types.ts';
 export {

packages/kernel-utils/src/types.ts

@@ -55,6 +55,18 @@ export type PromiseCallbacks<Resolve = unknown> = Omit<
   'promise'
 >;
 
+/**
+ * Utility type that wraps all method return types in Promise.
+ * Methods already returning Promise<T> remain Promise<T>.
+ */
+export type Promisified<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+    ? (...args: A) => Promise<R>
+    : T[K] extends (...args: infer A) => infer R
+      ? (...args: A) => Promise<R>
+      : T[K];
+};
+
 export const EmptyJsonArray = empty(array(UnsafeJsonStruct));
 
 export type EmptyJsonArray = Infer<typeof EmptyJsonArray>;

packages/logger/test/ipc.test.ts

@@ -33,7 +33,7 @@ describe('ipc', () => {
     const logger = new Logger({ transports: [mockTransport] });
     logger.injectStream(stream as unknown as DuplexStream<LogMessage>);
 
-    await waitUntilQuiescent(1000);
+    await waitUntilQuiescent(10);
     expect(mockTransport).toHaveBeenCalledWith({
       level: 'debug',
       message: 'Hello, world!',
@@ -53,7 +53,7 @@ describe('ipc', () => {
     const logger = new Logger({ transports: [mockTransport] });
     logger.injectStream(loggerStream as unknown as DuplexStream<LogMessage>);
 
-    await waitUntilQuiescent(1000);
+    await waitUntilQuiescent(10);
     expect(mockTransport).toHaveBeenCalledWith({
       level: 'debug',
       message: 'Hello, world!',

packages/omnium-gatherum/package.json

@@ -45,14 +45,20 @@
   },
   "dependencies": {
     "@endo/eventual-send": "^1.3.4",
+    "@endo/exo": "^1.5.12",
     "@metamask/kernel-browser-runtime": "workspace:^",
     "@metamask/kernel-shims": "workspace:^",
     "@metamask/kernel-ui": "workspace:^",
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",
+    "@metamask/ocap-kernel": "workspace:^",
     "@metamask/streams": "workspace:^",
+    "@metamask/superstruct": "^3.2.1",
+    "@metamask/utils": "^11.9.0",
+    "immer": "^10.1.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "semver": "^7.7.1",
     "ses": "^1.14.0"
   },
   "devDependencies": {
@@ -70,6 +76,7 @@
     "@types/chrome": "^0.0.313",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
+    "@types/semver": "^7.7.1",
     "@types/webextension-polyfill": "^0",
     "@typescript-eslint/eslint-plugin": "^8.29.0",
     "@typescript-eslint/parser": "^8.29.0",

packages/omnium-gatherum/src/background.ts

@@ -14,17 +14,20 @@ import type { JsonRpcMessage } from '@metamask/kernel-utils';
 import { Logger } from '@metamask/logger';
 import { ChromeRuntimeDuplexStream } from '@metamask/streams/browser';
 
-defineGlobals();
+import { initializeControllers } from './controllers/index.ts';
+import type {
+  CapletControllerFacet,
+  CapletManifest,
+} from './controllers/index.ts';
 
 const OFFSCREEN_DOCUMENT_PATH = '/offscreen.html';
 const logger = new Logger('background');
+const globals = defineGlobals();
 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);
+  omnium.ping?.().catch(logger.error);
 });
 
 // Install/update
@@ -104,12 +107,23 @@ async function main(): Promise<void> {
     },
   });
 
-  kernelP = backgroundCapTP.getKernel();
+  const kernelP = backgroundCapTP.getKernel();
+  globals.setKernelP(kernelP);
 
-  ping = async (): Promise<void> => {
+  globals.setPing(async (): Promise<void> => {
     const result = await E(kernelP).ping();
     logger.info(result);
-  };
+  });
+
+  try {
+    const controllers = await initializeControllers({
+      logger,
+      kernel: kernelP,
+    });
+    globals.setCapletController(controllers.caplet);
+  } catch (error) {
+    offscreenStream.throw(error as Error).catch(logger.error);
+  }
 
   try {
     await offscreenStream.drain((message) => {
@@ -129,31 +143,65 @@ async function main(): Promise<void> {
   }
 }
 
+type GlobalSetters = {
+  setKernelP: (value: Promise<KernelFacade>) => void;
+  setPing: (value: () => Promise<void>) => void;
+  setCapletController: (value: CapletControllerFacet) => void;
+};
+
 /**
  * Define globals accessible via the background console.
+ *
+ * @returns A device for setting the global values.
  */
-function defineGlobals(): void {
+function defineGlobals(): GlobalSetters {
+  Object.defineProperty(globalThis, 'E', {
+    configurable: false,
+    enumerable: true,
+    writable: false,
+    value: E,
+  });
+
   Object.defineProperty(globalThis, 'omnium', {
     configurable: false,
     enumerable: true,
     writable: false,
     value: {},
   });
 
+  let kernelP: Promise<KernelFacade>;
+  let ping: (() => Promise<void>) | undefined;
+  let capletController: CapletControllerFacet;
+
   Object.defineProperties(globalThis.omnium, {
     ping: {
       get: () => ping,
     },
     getKernel: {
       value: async () => kernelP,
     },
+    caplet: {
+      value: harden({
+        install: async (manifest: CapletManifest) =>
+          E(capletController).install(manifest),
+        uninstall: async (capletId: string) =>
+          E(capletController).uninstall(capletId),
+        list: async () => E(capletController).list(),
+        get: async (capletId: string) => E(capletController).get(capletId),
+      }),
+    },
   });
   harden(globalThis.omnium);
 
-  Object.defineProperty(globalThis, 'E', {
-    configurable: false,
-    enumerable: true,
-    writable: false,
-    value: E,
-  });
+  return {
+    setKernelP: (value) => {
+      kernelP = value;
+    },
+    setPing: (value) => {
+      ping = value;
+    },
+    setCapletController: (value) => {
+      capletController = value;
+    },
+  };
 }