feat(kernel-daemon): add IPC server, client, and lifecycle

Introduce the `@ocap/kernel-daemon` package with Unix-domain-socket
IPC infrastructure:

- `DaemonServer` — JSON-RPC dispatcher over `net.Server`
- `connectToDaemon` / `sendShutdown` — IPC client helpers
- `startDaemon` / `stopDaemon` / `isDaemonRunning` — process lifecycle
- Constants for socket, PID, DB, and log file paths

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: grypez

.depcheckrc.yml

@@ -17,6 +17,9 @@ ignores:
   - '@ts-bridge/cli'
   - '@ts-bridge/shims'
 
+  # yargs (type-only usage in kernel-daemon)
+  - '@types/yargs'
+
   # vitest
   - 'vite'
   - '@types/vitest'

packages/kernel-daemon/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ocap/kernel-daemon",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Persistent ocap kernel daemon with IPC server and client",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --no-references --clean",
+    "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./dist ./.turbo ./logs",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn constraints && yarn lint:dependencies",
+    "lint:dependencies": "depcheck --quiet",
+    "lint:eslint": "eslint . --cache",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix && yarn lint:dependencies",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path ../../.gitignore --log-level error",
+    "test": "vitest run --config vitest.config.ts",
+    "test:clean": "yarn test --no-cache --coverage.clean",
+    "test:dev": "yarn test --mode development",
+    "test:verbose": "yarn test --reporter verbose",
+    "test:watch": "vitest --config vitest.config.ts",
+    "test:dev:quiet": "yarn test:dev --reporter @ocap/repo-tools/vitest-reporters/silent",
+    "build:docs": "typedoc"
+  },
+  "dependencies": {
+    "@metamask/kernel-rpc-methods": "workspace:^",
+    "@metamask/logger": "workspace:^"
+  },
+  "devDependencies": {
+    "@ocap/repo-tools": "workspace:^",
+    "@ts-bridge/cli": "^0.6.3",
+    "@ts-bridge/shims": "^0.1.1",
+    "@types/node": "^22.13.1",
+    "@types/yargs": "^17.0.33",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.23.0",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "typescript": "~5.8.2",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "yargs": "^17.7.2"
+  },
+  "engines": {
+    "node": "^20.11 || >=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/ocap-kernel.git"
+  }
+}

packages/kernel-daemon/src/constants.ts

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Base directory for daemon state files.
+ */
+export const DAEMON_DIR = join(homedir(), '.ocap-kernel-daemon');
+
+/**
+ * Path to the daemon PID file.
+ */
+export const PID_FILE = join(DAEMON_DIR, 'daemon.pid');
+
+/**
+ * Path to the daemon Unix domain socket.
+ */
+export const SOCK_FILE = join(DAEMON_DIR, 'daemon.sock');
+
+/**
+ * Path to the persistent SQLite database.
+ */
+export const DB_FILE = join(DAEMON_DIR, 'store.db');
+
+/**
+ * Path to the daemon log file.
+ */
+export const LOG_FILE = join(DAEMON_DIR, 'daemon.log');

packages/kernel-daemon/src/daemon-client.test.ts

@@ -0,0 +1,118 @@
+import { EventEmitter } from 'node:events';
+import { createConnection } from 'node:net';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { connectToDaemon, sendShutdown } from './daemon-client.ts';
+
+vi.mock('@metamask/kernel-rpc-methods', () => {
+  const MockRpcClient = vi.fn();
+  // eslint-disable-next-line vitest/prefer-spy-on -- vi.spyOn fails on bare vi.fn() constructors
+  MockRpcClient.prototype.handleResponse = vi.fn();
+  // eslint-disable-next-line vitest/prefer-spy-on -- vi.spyOn fails on bare vi.fn() constructors
+  MockRpcClient.prototype.call = vi.fn();
+  return { RpcClient: MockRpcClient };
+});
+
+vi.mock('node:net', () => ({
+  createConnection: vi.fn(),
+}));
+
+const makeMockSocket = () => {
+  const emitter = new EventEmitter();
+  return Object.assign(emitter, {
+    write: vi.fn(),
+    end: vi.fn(),
+    destroy: vi.fn(),
+    removeAllListeners: vi.fn(),
+  });
+};
+
+const mockMethodSpecs = {
+  getStatus: { method: 'getStatus' },
+};
+
+const mockLogger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+};
+
+describe('daemon-client', () => {
+  let mockSocket: ReturnType<typeof makeMockSocket>;
+
+  beforeEach(() => {
+    mockSocket = makeMockSocket();
+    vi.mocked(createConnection).mockReturnValue(mockSocket as never);
+  });
+
+  describe('connectToDaemon', () => {
+    it('resolves with a daemon connection on successful connect', async () => {
+      const connectionPromise = connectToDaemon(
+        mockMethodSpecs,
+        mockLogger as never,
+      );
+      mockSocket.emit('connect');
+      const connection = await connectionPromise;
+
+      expect(connection.client).toBeDefined();
+      expect(connection.close).toBeInstanceOf(Function);
+      expect(connection.socket).toBe(mockSocket);
+    });
+
+    it('rejects when connection fails', async () => {
+      const connectionPromise = connectToDaemon(
+        mockMethodSpecs,
+        mockLogger as never,
+      );
+      mockSocket.emit('error', new Error('ENOENT'));
+
+      await expect(connectionPromise).rejects.toThrow(
+        'Failed to connect to daemon: ENOENT',
+      );
+    });
+
+    it('removes all listeners and destroys socket on close', async () => {
+      const connectionPromise = connectToDaemon(
+        mockMethodSpecs,
+        mockLogger as never,
+      );
+      mockSocket.emit('connect');
+      const connection = await connectionPromise;
+
+      connection.close();
+
+      expect(mockSocket.removeAllListeners).toHaveBeenCalled();
+      expect(mockSocket.destroy).toHaveBeenCalled();
+    });
+  });
+
+  describe('sendShutdown', () => {
+    it('sends shutdown command and resolves on response', async () => {
+      const shutdownPromise = sendShutdown();
+      mockSocket.emit('connect');
+
+      expect(mockSocket.write).toHaveBeenCalledWith(
+        expect.stringContaining('"method":"shutdown"'),
+      );
+
+      // Simulate response
+      mockSocket.emit(
+        'data',
+        Buffer.from('{"jsonrpc":"2.0","id":"shutdown-1","result":true}\n'),
+      );
+
+      await shutdownPromise;
+      expect(mockSocket.destroy).toHaveBeenCalled();
+    });
+
+    it('rejects when connection fails', async () => {
+      const shutdownPromise = sendShutdown();
+      mockSocket.emit('error', new Error('ECONNREFUSED'));
+
+      await expect(shutdownPromise).rejects.toThrow(
+        'Failed to connect to daemon: ECONNREFUSED',
+      );
+    });
+  });
+});

packages/kernel-daemon/src/daemon-client.ts

@@ -0,0 +1,104 @@
+import { RpcClient } from '@metamask/kernel-rpc-methods';
+import type { Logger } from '@metamask/logger';
+import { createConnection } from 'node:net';
+
+import { SOCK_FILE } from './constants.ts';
+import type { DaemonConnection } from './types.ts';
+
+/**
+ * Connect to the daemon's Unix domain socket and return an RPC client.
+ *
+ * @param methodSpecs - RPC method specifications for the client (e.g. rpcMethodSpecs
+ * from kernel-browser-runtime). Passed as a parameter to avoid cyclic dependencies.
+ * @param logger - Logger instance.
+ * @returns A daemon connection with an RPC client and close function.
+ */
+export async function connectToDaemon(
+  methodSpecs: Record<string, { method: string }>,
+  logger: Logger,
+): Promise<DaemonConnection> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(SOCK_FILE);
+
+    socket.once('connect', () => {
+      const sendMessage = async (
+        payload: Record<string, unknown>,
+      ): Promise<void> => {
+        socket.write(`${JSON.stringify(payload)}\n`);
+      };
+
+      const client = new RpcClient(
+        methodSpecs as never,
+        sendMessage,
+        'cli-',
+        logger,
+      );
+
+      let buffer = '';
+      socket.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString();
+        let newlineIndex: number;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, newlineIndex);
+          buffer = buffer.slice(newlineIndex + 1);
+          try {
+            const response = JSON.parse(line);
+            if (response.id !== undefined && response.id !== null) {
+              client.handleResponse(String(response.id), response);
+            }
+          } catch {
+            logger.error('Failed to parse daemon response');
+          }
+        }
+      });
+
+      resolve({
+        client,
+        socket,
+        close: () => {
+          socket.removeAllListeners();
+          socket.destroy();
+        },
+      });
+    });
+
+    socket.once('error', (error) => {
+      reject(new Error(`Failed to connect to daemon: ${error.message}`));
+    });
+  });
+}
+
+/**
+ * Send a raw shutdown command to the daemon over the Unix socket.
+ * This bypasses the typed RPC client since `shutdown` is daemon-specific.
+ *
+ * @returns A promise that resolves when the shutdown acknowledgment is received.
+ */
+export async function sendShutdown(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(SOCK_FILE);
+
+    socket.once('connect', () => {
+      const request = {
+        jsonrpc: '2.0',
+        id: 'shutdown-1',
+        method: 'shutdown',
+        params: [],
+      };
+      socket.write(`${JSON.stringify(request)}\n`);
+
+      let buffer = '';
+      socket.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString();
+        if (buffer.includes('\n')) {
+          socket.destroy();
+          resolve();
+        }
+      });
+    });
+
+    socket.once('error', (error) => {
+      reject(new Error(`Failed to connect to daemon: ${error.message}`));
+    });
+  });
+}