feat(ocap-kernel): add initRemoteComms and registerLocationHints RPC methods (#849)

## Summary

- Adds `initRemoteComms` kernel-control RPC handler — calls
`kernel.initRemoteComms(options)` with optional `relays`,
`directListenAddresses`, `maxRetryAttempts`, and `maxQueue` params
- Adds `registerLocationHints` kernel-control RPC handler — calls
`kernel.registerLocationHints(peerId, hints)` for registering peer
multiaddr location hints
- Registers both in the kernel-control index and updates the index test

These methods allow the daemon CLI (`ocap daemon exec initRemoteComms`,
`ocap daemon exec registerLocationHints`) to initialize the libp2p
networking stack and register peer location hints, which were previously
only accessible via the Node.js API.

## Test plan

- [x] Unit tests for `initRemoteComms` handler (empty options,
individual options, all options, error propagation)
- [x] Unit tests for `registerLocationHints` handler (single hint,
multiple hints, error propagation)
- [x] Index test updated to include both new handlers/specs
- [x] `yarn workspace @MetaMask/ocap-kernel test:dev:quiet` passes (new
tests green, no regressions)
- [x] `yarn workspace @MetaMask/ocap-kernel build` compiles cleanly
- [x] Manual: `ocap daemon exec initRemoteComms
'{"directListenAddresses":["/ip4/0.0.0.0/udp/0/quic-v1"]}'` then `ocap
daemon exec getStatus` shows `remoteComms.state === "connected"`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces new RPC entry points that can start/affect remote comms
behavior; while changes are additive and well-tested, they expand the
daemon’s externally-invokable surface area.
> 
> **Overview**
> Adds two new kernel-control JSON-RPC methods to expose remote
networking controls: `initRemoteComms` (initializes remote comms with
optional relay/listen/retry/queue options) and `registerLocationHints`
(registers multiaddr dial hints for a peer).
> 
> Registers both methods in
`kernel-control/index.ts`/`rpcHandlers`+`rpcMethodSpecs`, updates the
index export test accordingly, and adds unit tests covering parameter
validation, option forwarding, and error propagation.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
53aa8e2. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/ocap-kernel/src/rpc/kernel-control/index.test.ts

@@ -11,6 +11,10 @@ import {
 } from './execute-db-query.ts';
 import { getStatusHandler, getStatusSpec } from './get-status.ts';
 import { rpcHandlers, rpcMethodSpecs } from './index.ts';
+import {
+  initRemoteCommsHandler,
+  initRemoteCommsSpec,
+} from './init-remote-comms.ts';
 import { isRevokedHandler, isRevokedSpec } from './is-revoked.ts';
 import { issueOcapURLHandler, issueOcapURLSpec } from './issue-ocap-url.ts';
 import {
@@ -20,6 +24,10 @@ import {
 import { pingVatHandler, pingVatSpec } from './ping-vat.ts';
 import { queueMessageHandler, queueMessageSpec } from './queue-message.ts';
 import { redeemOcapURLHandler, redeemOcapURLSpec } from './redeem-ocap-url.ts';
+import {
+  registerLocationHintsHandler,
+  registerLocationHintsSpec,
+} from './register-location-hints.ts';
 import { restartVatHandler, restartVatSpec } from './restart-vat.ts';
 import { revokeHandler, revokeSpec } from './revoke.ts';
 import {
@@ -38,9 +46,11 @@ describe('handlers/index', () => {
       clearState: clearStateHandler,
       executeDBQuery: executeDBQueryHandler,
       getStatus: getStatusHandler,
+      initRemoteComms: initRemoteCommsHandler,
       issueOcapURL: issueOcapURLHandler,
       pingVat: pingVatHandler,
       redeemOcapURL: redeemOcapURLHandler,
+      registerLocationHints: registerLocationHintsHandler,
       restartVat: restartVatHandler,
       revoke: revokeHandler,
       isRevoked: isRevokedHandler,
@@ -67,9 +77,11 @@ describe('handlers/index', () => {
       clearState: clearStateSpec,
       executeDBQuery: executeDBQuerySpec,
       getStatus: getStatusSpec,
+      initRemoteComms: initRemoteCommsSpec,
       issueOcapURL: issueOcapURLSpec,
       pingVat: pingVatSpec,
       redeemOcapURL: redeemOcapURLSpec,
+      registerLocationHints: registerLocationHintsSpec,
       restartVat: restartVatSpec,
       revoke: revokeSpec,
       isRevoked: isRevokedSpec,

packages/ocap-kernel/src/rpc/kernel-control/index.ts

@@ -8,6 +8,10 @@ import {
   executeDBQuerySpec,
 } from './execute-db-query.ts';
 import { getStatusHandler, getStatusSpec } from './get-status.ts';
+import {
+  initRemoteCommsHandler,
+  initRemoteCommsSpec,
+} from './init-remote-comms.ts';
 import { isRevokedHandler, isRevokedSpec } from './is-revoked.ts';
 import { issueOcapURLHandler, issueOcapURLSpec } from './issue-ocap-url.ts';
 import {
@@ -17,6 +21,10 @@ import {
 import { pingVatHandler, pingVatSpec } from './ping-vat.ts';
 import { queueMessageHandler, queueMessageSpec } from './queue-message.ts';
 import { redeemOcapURLHandler, redeemOcapURLSpec } from './redeem-ocap-url.ts';
+import {
+  registerLocationHintsHandler,
+  registerLocationHintsSpec,
+} from './register-location-hints.ts';
 import { restartVatHandler, restartVatSpec } from './restart-vat.ts';
 import { revokeHandler, revokeSpec } from './revoke.ts';
 import {
@@ -36,9 +44,11 @@ export const rpcHandlers = {
   clearState: clearStateHandler,
   executeDBQuery: executeDBQueryHandler,
   getStatus: getStatusHandler,
+  initRemoteComms: initRemoteCommsHandler,
   issueOcapURL: issueOcapURLHandler,
   pingVat: pingVatHandler,
   redeemOcapURL: redeemOcapURLHandler,
+  registerLocationHints: registerLocationHintsHandler,
   revoke: revokeHandler,
   isRevoked: isRevokedHandler,
   restartVat: restartVatHandler,
@@ -52,9 +62,11 @@ export const rpcHandlers = {
   clearState: typeof clearStateHandler;
   executeDBQuery: typeof executeDBQueryHandler;
   getStatus: typeof getStatusHandler;
+  initRemoteComms: typeof initRemoteCommsHandler;
   issueOcapURL: typeof issueOcapURLHandler;
   pingVat: typeof pingVatHandler;
   redeemOcapURL: typeof redeemOcapURLHandler;
+  registerLocationHints: typeof registerLocationHintsHandler;
   revoke: typeof revokeHandler;
   isRevoked: typeof isRevokedHandler;
   restartVat: typeof restartVatHandler;
@@ -73,9 +85,11 @@ export const rpcMethodSpecs = {
   clearState: clearStateSpec,
   executeDBQuery: executeDBQuerySpec,
   getStatus: getStatusSpec,
+  initRemoteComms: initRemoteCommsSpec,
   issueOcapURL: issueOcapURLSpec,
   pingVat: pingVatSpec,
   redeemOcapURL: redeemOcapURLSpec,
+  registerLocationHints: registerLocationHintsSpec,
   revoke: revokeSpec,
   isRevoked: isRevokedSpec,
   restartVat: restartVatSpec,
@@ -89,9 +103,11 @@ export const rpcMethodSpecs = {
   clearState: typeof clearStateSpec;
   executeDBQuery: typeof executeDBQuerySpec;
   getStatus: typeof getStatusSpec;
+  initRemoteComms: typeof initRemoteCommsSpec;
   issueOcapURL: typeof issueOcapURLSpec;
   pingVat: typeof pingVatSpec;
   redeemOcapURL: typeof redeemOcapURLSpec;
+  registerLocationHints: typeof registerLocationHintsSpec;
   revoke: typeof revokeSpec;
   isRevoked: typeof isRevokedSpec;
   restartVat: typeof restartVatSpec;

packages/ocap-kernel/src/rpc/kernel-control/init-remote-comms.test.ts

@@ -0,0 +1,111 @@
+import { is } from '@metamask/superstruct';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import {
+  initRemoteCommsHandler,
+  initRemoteCommsSpec,
+} from './init-remote-comms.ts';
+import type { Kernel } from '../../Kernel.ts';
+
+describe('initRemoteCommsHandler', () => {
+  let mockKernel: Kernel;
+
+  beforeEach(() => {
+    mockKernel = {
+      initRemoteComms: vi.fn().mockResolvedValue(undefined),
+    } as unknown as Kernel;
+  });
+
+  it('calls initRemoteComms with empty options and returns null', async () => {
+    const result = await initRemoteCommsHandler.implementation(
+      { kernel: mockKernel },
+      {},
+    );
+
+    expect(mockKernel.initRemoteComms).toHaveBeenCalledWith({});
+    expect(result).toBeNull();
+  });
+
+  it('passes relays option', async () => {
+    const result = await initRemoteCommsHandler.implementation(
+      { kernel: mockKernel },
+      { relays: ['/dns4/relay.example.com/tcp/443/wss/p2p/QmRelay'] },
+    );
+
+    expect(mockKernel.initRemoteComms).toHaveBeenCalledWith({
+      relays: ['/dns4/relay.example.com/tcp/443/wss/p2p/QmRelay'],
+    });
+    expect(result).toBeNull();
+  });
+
+  it('passes directListenAddresses option', async () => {
+    const result = await initRemoteCommsHandler.implementation(
+      { kernel: mockKernel },
+      { directListenAddresses: ['/ip4/0.0.0.0/udp/0/quic-v1'] },
+    );
+
+    expect(mockKernel.initRemoteComms).toHaveBeenCalledWith({
+      directListenAddresses: ['/ip4/0.0.0.0/udp/0/quic-v1'],
+    });
+    expect(result).toBeNull();
+  });
+
+  it('passes all options', async () => {
+    const params = {
+      relays: ['relay1'],
+      directListenAddresses: ['/ip4/0.0.0.0/udp/0/quic-v1'],
+      maxRetryAttempts: 5,
+      maxQueue: 100,
+    };
+
+    const result = await initRemoteCommsHandler.implementation(
+      { kernel: mockKernel },
+      params,
+    );
+
+    expect(mockKernel.initRemoteComms).toHaveBeenCalledWith({
+      relays: ['relay1'],
+      directListenAddresses: ['/ip4/0.0.0.0/udp/0/quic-v1'],
+      maxRetryAttempts: 5,
+      maxQueue: 100,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('propagates errors from kernel.initRemoteComms', async () => {
+    const error = new Error('Remote comms initialization failed');
+    vi.mocked(mockKernel.initRemoteComms).mockRejectedValueOnce(error);
+
+    await expect(
+      initRemoteCommsHandler.implementation({ kernel: mockKernel }, {}),
+    ).rejects.toThrow(error);
+  });
+
+  describe('params validation', () => {
+    it('accepts valid params', () => {
+      expect(is({}, initRemoteCommsSpec.params)).toBe(true);
+      expect(
+        is({ maxRetryAttempts: 0, maxQueue: 0 }, initRemoteCommsSpec.params),
+      ).toBe(true);
+      expect(
+        is({ maxRetryAttempts: 5, maxQueue: 100 }, initRemoteCommsSpec.params),
+      ).toBe(true);
+    });
+
+    it.each([-1, -100, 1.5, 3.14, -0.5])(
+      'rejects invalid maxRetryAttempts value: %s',
+      (value) => {
+        expect(
+          is({ maxRetryAttempts: value }, initRemoteCommsSpec.params),
+        ).toBe(false);
+      },
+    );
+
+    it.each([-1, -100, 1.5, 3.14, -0.5])(
+      'rejects invalid maxQueue value: %s',
+      (value) => {
+        expect(is({ maxQueue: value }, initRemoteCommsSpec.params)).toBe(false);
+      },
+    );
+  });
+});

packages/ocap-kernel/src/rpc/kernel-control/init-remote-comms.ts

@@ -0,0 +1,75 @@
+import type { MethodSpec, Handler } from '@metamask/kernel-rpc-methods';
+import {
+  object,
+  literal,
+  optional,
+  array,
+  string,
+  integer,
+  min,
+} from '@metamask/superstruct';
+import type { Struct } from '@metamask/superstruct';
+import type { Infer } from '@metamask/superstruct';
+
+import type { Kernel } from '../../Kernel.ts';
+import type { RemoteCommsOptions } from '../../remotes/types.ts';
+
+const initRemoteCommsParamsStruct = object({
+  relays: optional(array(string())),
+  directListenAddresses: optional(array(string())),
+  maxRetryAttempts: optional(min(integer(), 0)),
+  maxQueue: optional(min(integer(), 0)),
+});
+
+// Superstruct's `optional()` infers `T | undefined` for each field, but
+// `JsonRpcParams` (from `@metamask/utils`) does not include `undefined` in its
+// `Json` union. This mapped type strips `| undefined` while preserving
+// optionality, keeping the type derived from the struct (single source of truth).
+type InitRemoteCommsParams = {
+  [K in keyof Infer<typeof initRemoteCommsParamsStruct>]: Exclude<
+    Infer<typeof initRemoteCommsParamsStruct>[K],
+    undefined
+  >;
+};
+
+export const initRemoteCommsSpec: MethodSpec<
+  'initRemoteComms',
+  InitRemoteCommsParams,
+  null
+> = {
+  method: 'initRemoteComms',
+  // Safe: the struct validates JSON-RPC params which never contain `undefined`.
+  params: initRemoteCommsParamsStruct as Struct<InitRemoteCommsParams>,
+  result: literal(null),
+};
+
+export type InitRemoteCommsHooks = {
+  kernel: Pick<Kernel, 'initRemoteComms'>;
+};
+
+export const initRemoteCommsHandler: Handler<
+  'initRemoteComms',
+  InitRemoteCommsParams,
+  Promise<null>,
+  InitRemoteCommsHooks
+> = {
+  ...initRemoteCommsSpec,
+  hooks: { kernel: true },
+  implementation: async ({ kernel }, params): Promise<null> => {
+    const options: RemoteCommsOptions = {};
+    if (params.relays !== undefined) {
+      options.relays = params.relays;
+    }
+    if (params.directListenAddresses !== undefined) {
+      options.directListenAddresses = params.directListenAddresses;
+    }
+    if (params.maxRetryAttempts !== undefined) {
+      options.maxRetryAttempts = params.maxRetryAttempts;
+    }
+    if (params.maxQueue !== undefined) {
+      options.maxQueue = params.maxQueue;
+    }
+    await kernel.initRemoteComms(options);
+    return null;
+  },
+};

packages/ocap-kernel/src/rpc/kernel-control/register-location-hints.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { registerLocationHintsHandler } from './register-location-hints.ts';
+import type { Kernel } from '../../Kernel.ts';
+
+describe('registerLocationHintsHandler', () => {
+  let mockKernel: Kernel;
+
+  beforeEach(() => {
+    mockKernel = {
+      registerLocationHints: vi.fn().mockResolvedValue(undefined),
+    } as unknown as Kernel;
+  });
+
+  it('calls registerLocationHints and returns null', async () => {
+    const params = {
+      peerId: 'peer-123',
+      hints: ['/ip4/192.168.1.1/udp/4001/quic-v1'],
+    };
+
+    const result = await registerLocationHintsHandler.implementation(
+      { kernel: mockKernel },
+      params,
+    );
+
+    expect(mockKernel.registerLocationHints).toHaveBeenCalledWith('peer-123', [
+      '/ip4/192.168.1.1/udp/4001/quic-v1',
+    ]);
+    expect(result).toBeNull();
+  });
+
+  it('passes multiple hints', async () => {
+    const params = {
+      peerId: 'peer-456',
+      hints: ['/ip4/10.0.0.1/udp/4001/quic-v1', '/ip4/10.0.0.1/tcp/4001'],
+    };
+
+    const result = await registerLocationHintsHandler.implementation(
+      { kernel: mockKernel },
+      params,
+    );
+
+    expect(mockKernel.registerLocationHints).toHaveBeenCalledWith('peer-456', [
+      '/ip4/10.0.0.1/udp/4001/quic-v1',
+      '/ip4/10.0.0.1/tcp/4001',
+    ]);
+    expect(result).toBeNull();
+  });
+
+  it('propagates errors from kernel.registerLocationHints', async () => {
+    const error = new Error('Failed to register hints');
+    vi.mocked(mockKernel.registerLocationHints).mockRejectedValueOnce(error);
+
+    await expect(
+      registerLocationHintsHandler.implementation(
+        { kernel: mockKernel },
+        { peerId: 'peer-123', hints: ['hint1'] },
+      ),
+    ).rejects.toThrow(error);
+  });
+});