@2389research/hermit-openclaw 0.1.0

package/index.ts

@@ -0,0 +1,20 @@
+// ABOUTME: Plugin entry point for the Hermit OpenClaw channel plugin.
+// ABOUTME: Exports the default plugin object with register(api) for OpenClaw discovery.
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { hermitPlugin } from "./src/channel.js";
+import { setHermitRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "hermit-openclaw",
+  name: "Hermit E2EE",
+  description: "E2EE messaging via the Hermit daemon gRPC API",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setHermitRuntime(api.runtime);
+    api.registerChannel({ plugin: hermitPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "hermit-openclaw",
+  "name": "Hermit E2EE",
+  "description": "E2EE messaging via the Hermit daemon gRPC API",
+  "channels": ["hermit"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@2389research/hermit-openclaw",
+  "version": "0.1.0",
+  "description": "OpenClaw channel plugin for Hermit E2EE messaging",
+  "type": "module",
+  "openclaw": {
+    "extensions": "./index.ts",
+    "channel": "hermit",
+    "install": "npm install"
+  },
+  "files": [
+    "src/",
+    "proto",
+    "index.ts",
+    "openclaw.plugin.json",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "proto": "buf generate"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.10.0",
+    "@grpc/proto-loader": "^0.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,123 @@
+// ABOUTME: ChannelPlugin definition wiring all Hermit adapters for OpenClaw.
+// ABOUTME: Manages gRPC client lifecycle, inbox subscriptions, and message routing.
+
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import { HermitClient } from "./client.js";
+import type { ResolvedHermitAccount } from "./config.js";
+import { listHermitAccountIds, resolveHermitAccount } from "./config.js";
+import type { HermitChannelConfig } from "./config-schema.js";
+import { parseSessionKey, normalizeHermitTarget } from "./normalize.js";
+import type { HermitProbeResult } from "./status.js";
+import { probeHermit } from "./status.js";
+import { dispatchInboxEvent } from "./dispatch.js";
+import type { InboxSubscription } from "./stream.js";
+import { subscribeToInbox } from "./stream.js";
+
+const activeClients = new Map<string, HermitClient>();
+const activeSubscriptions = new Map<string, InboxSubscription>();
+
+export const hermitPlugin: ChannelPlugin<ResolvedHermitAccount, HermitProbeResult> = {
+  id: "hermit",
+
+  meta: {
+    id: "hermit",
+    label: "Hermit E2EE",
+    order: 91,
+  },
+
+  capabilities: {
+    chatTypes: ["direct"],
+    media: false,
+  },
+
+  config: {
+    listAccountIds(cfg: HermitChannelConfig): string[] {
+      return listHermitAccountIds(cfg);
+    },
+
+    resolveAccount(cfg: HermitChannelConfig, accountId: string): ResolvedHermitAccount {
+      return resolveHermitAccount(cfg, accountId);
+    },
+
+    defaultAccountId(cfg: HermitChannelConfig): string {
+      const ids = listHermitAccountIds(cfg);
+      return ids[0] ?? "default";
+    },
+  },
+
+  messaging: {
+    normalizeTarget: normalizeHermitTarget,
+    targetResolver: {
+      looksLikeId(raw: string): boolean {
+        return raw.startsWith("hermit:");
+      },
+    },
+  },
+
+  heartbeat: {
+    async checkReady(account: ResolvedHermitAccount): Promise<boolean> {
+      const result = await probeHermit(account, 3000);
+      return result.ok;
+    },
+  },
+
+  status: {
+    async probeAccount(account: ResolvedHermitAccount): Promise<HermitProbeResult> {
+      return probeHermit(account);
+    },
+  },
+
+  outbound: {
+    async sendText(
+      account: ResolvedHermitAccount,
+      sessionKey: string,
+      text: string
+    ): Promise<void> {
+      const { channelId } = parseSessionKey(sessionKey);
+      const client = activeClients.get(account.accountId);
+      if (!client) {
+        throw new Error(`No active Hermit client for account ${account.accountId}`);
+      }
+      await client.postMessage(channelId, text, account.principalUid);
+    },
+
+    async sendMedia(): Promise<void> {
+      throw new Error("Hermit does not support media messages");
+    },
+  },
+
+  gateway: {
+    async startAccount(account: ResolvedHermitAccount): Promise<() => void> {
+      const client = new HermitClient({ address: account.endpoint });
+      activeClients.set(account.accountId, client);
+
+      let sub: InboxSubscription | undefined;
+      if (account.principalUid) {
+        sub = subscribeToInbox(
+          client,
+          account.principalUid,
+          (item) => {
+            dispatchInboxEvent(
+              { client, accountId: account.accountId, principalUid: account.principalUid },
+              item
+            ).catch((err) => {
+              console.error(`[hermit] dispatch error: ${err}`);
+            });
+          },
+          {
+            onError: (err) => console.error(`[hermit] inbox stream error: ${err.message}`),
+            onEnd: () => console.log(`[hermit] inbox stream ended for ${account.accountId}`),
+          }
+        );
+        activeSubscriptions.set(account.accountId, sub);
+      }
+
+      return () => {
+        sub?.cancel();
+        activeSubscriptions.delete(account.accountId);
+        client.close();
+        activeClients.delete(account.accountId);
+      };
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,377 @@
+// ABOUTME: gRPC client wrapper that connects to the Hermit daemon.
+// ABOUTME: Exposes typed methods for agent, channel, and event operations.
+
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Configuration options for the HermitClient.
+ */
+export interface HermitClientConfig {
+  /** gRPC endpoint address. Defaults to 127.0.0.1:13370. */
+  address?: string;
+  /** Path to the proto directory. Defaults to ../proto relative to this file. */
+  protoDir?: string;
+}
+
+/**
+ * Mirrors the EventEnvelope message from hermit.v1.common.
+ */
+export interface EventEnvelope {
+  channelId: string;
+  eventId: string;
+  createdAtServer: { seconds: number; nanos: number } | null;
+  createdAtClient: { seconds: number; nanos: number } | null;
+  ciphertext: Buffer;
+  cipherSuite: string;
+  mlsEpoch: number;
+  payloadVersion: number;
+  size: number | null;
+}
+
+/**
+ * Mirrors the DecryptedPayload message from hermit.v1.common.
+ */
+export interface DecryptedPayload {
+  eventId: string;
+  channelId: string;
+  senderUid: string;
+  eventKind: string;
+  content: Buffer;
+  sentAt: { seconds: number; nanos: number } | null;
+}
+
+/**
+ * Mirrors the InboxItem message from hermit.v1.common.
+ */
+export interface InboxItem {
+  channelId: string;
+  eventId: string;
+  createdAtServer: { seconds: number; nanos: number } | null;
+}
+
+/**
+ * Mirrors the ChannelSummary message from hermit.v1.common.
+ */
+export interface ChannelSummary {
+  channelId: string;
+  channelType: number;
+  title: string | null;
+  lastEventId: string;
+  lastEventAt: { seconds: number; nanos: number } | null;
+  unreadCount: number;
+}
+
+/**
+ * Mirrors the PrincipalInfo message from hermit.v1.common.
+ */
+export interface PrincipalInfo {
+  principalUid: string;
+  displayName: string;
+  principalType: number;
+}
+
+const DEFAULT_ADDRESS = "127.0.0.1:13370";
+
+const PROTO_LOADER_OPTIONS: protoLoader.Options = {
+  keepCase: false,
+  longs: Number,
+  enums: Number,
+  defaults: true,
+  oneofs: true,
+  includeDirs: [],
+};
+
+/**
+ * Resolves the default proto directory path, accounting for the symlink
+ * at openclaw-extension/proto -> ../../crates/hermit-proto/proto.
+ */
+function defaultProtoDir(): string {
+  return path.resolve(__dirname, "..", "proto");
+}
+
+/**
+ * Loads all Hermit proto files and returns the grpc package definition.
+ */
+function loadProtos(protoDir: string): grpc.GrpcObject {
+  const protoFiles = [
+    path.join(protoDir, "hermit", "v1", "common.proto"),
+    path.join(protoDir, "hermit", "v1", "agents.proto"),
+    path.join(protoDir, "hermit", "v1", "channels.proto"),
+    path.join(protoDir, "hermit", "v1", "events.proto"),
+    path.join(protoDir, "hermit", "v1", "auth.proto"),
+    path.join(protoDir, "hermit", "v1", "presence.proto"),
+    path.join(protoDir, "hermit", "v1", "admin.proto"),
+  ];
+
+  const packageDef = protoLoader.loadSync(protoFiles, {
+    ...PROTO_LOADER_OPTIONS,
+    includeDirs: [protoDir],
+  });
+
+  return grpc.loadPackageDefinition(packageDef);
+}
+
+/**
+ * Typed wrapper around the Hermit daemon's gRPC services.
+ *
+ * Usage:
+ *   const client = new HermitClient();
+ *   const { agentUid, localToken } = await client.registerAgent("my-agent");
+ */
+export class HermitClient {
+  readonly address: string;
+  readonly protoDir: string;
+
+  private agentService: grpc.Client;
+  private channelService: grpc.Client;
+  private eventService: grpc.Client;
+
+  constructor(config: HermitClientConfig = {}) {
+    this.address = config.address ?? DEFAULT_ADDRESS;
+    this.protoDir = config.protoDir ?? defaultProtoDir();
+
+    const pkgDef = loadProtos(this.protoDir);
+    const hermitV1 = (pkgDef.hermit as grpc.GrpcObject).v1 as grpc.GrpcObject;
+
+    const credentials = grpc.credentials.createInsecure();
+
+    const AgentServiceClient = hermitV1.AgentService as typeof grpc.Client;
+    const ChannelServiceClient = hermitV1.ChannelService as typeof grpc.Client;
+    const EventServiceClient = hermitV1.EventService as typeof grpc.Client;
+
+    this.agentService = new AgentServiceClient(this.address, credentials);
+    this.channelService = new ChannelServiceClient(this.address, credentials);
+    this.eventService = new EventServiceClient(this.address, credentials);
+  }
+
+  /**
+   * Registers a new agent with the Hermit daemon.
+   */
+  registerAgent(
+    displayName: string
+  ): Promise<{ agentUid: string; localToken: string }> {
+    return new Promise((resolve, reject) => {
+      (this.agentService as any).registerAgent(
+        { displayName },
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve({
+            agentUid: response.agentUid,
+            localToken: response.localToken,
+          });
+        }
+      );
+    });
+  }
+
+  /**
+   * Creates a direct channel with the specified target agent.
+   */
+  createChannel(
+    targetAgentUid: string
+  ): Promise<{ channelId: string }> {
+    return new Promise((resolve, reject) => {
+      (this.channelService as any).createChannelDirect(
+        { targetAgentUid },
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve({ channelId: response.channelId });
+        }
+      );
+    });
+  }
+
+  /**
+   * Posts an encrypted message to a channel. The daemon handles MLS encryption.
+   */
+  postMessage(
+    channelId: string,
+    plaintext: string,
+    senderUid?: string
+  ): Promise<{ eventId: string }> {
+    return new Promise((resolve, reject) => {
+      const request: Record<string, unknown> = {
+        channelId,
+        plaintext: Buffer.from(plaintext, "utf-8"),
+        eventKind: "message",
+      };
+      if (senderUid !== undefined) {
+        request.senderUid = senderUid;
+      }
+
+      (this.eventService as any).postEncryptedEvent(
+        request,
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve({ eventId: response.eventId });
+        }
+      );
+    });
+  }
+
+  /**
+   * Decrypts a single event from a channel.
+   */
+  decryptEvent(
+    channelId: string,
+    eventId: string,
+    principalUid?: string
+  ): Promise<DecryptedPayload> {
+    return new Promise((resolve, reject) => {
+      const request: Record<string, unknown> = { channelId, eventId };
+      if (principalUid !== undefined) {
+        request.principalUid = principalUid;
+      }
+
+      (this.eventService as any).decryptEvent(
+        request,
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve({
+            eventId: response.eventId,
+            channelId: response.channelId,
+            senderUid: response.senderUid,
+            eventKind: response.eventKind,
+            content: Buffer.from(response.content),
+            sentAt: response.sentAt ?? null,
+          });
+        }
+      );
+    });
+  }
+
+  /**
+   * Lists encrypted event envelopes from a channel.
+   */
+  listEvents(
+    channelId: string,
+    limit: number = 50
+  ): Promise<EventEnvelope[]> {
+    return new Promise((resolve, reject) => {
+      (this.eventService as any).listEvents(
+        { channelId, limit },
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          const events: EventEnvelope[] = (response.events ?? []).map(
+            (e: any) => ({
+              channelId: e.channelId,
+              eventId: e.eventId,
+              createdAtServer: e.createdAtServer ?? null,
+              createdAtClient: e.createdAtClient ?? null,
+              ciphertext: Buffer.from(e.ciphertext ?? []),
+              cipherSuite: e.cipherSuite,
+              mlsEpoch: e.mlsEpoch,
+              payloadVersion: e.payloadVersion,
+              size: e.size ?? null,
+            })
+          );
+          resolve(events);
+        }
+      );
+    });
+  }
+
+  /**
+   * Opens a server-streaming subscription to the inbox for a principal.
+   * Each time a new event arrives, the callback is invoked with the InboxItem.
+   * Returns the underlying gRPC call object so the caller can cancel it.
+   */
+  streamInbox(
+    principalUid: string,
+    callback: (item: InboxItem) => void
+  ): grpc.ClientReadableStream<any> {
+    const call = (this.eventService as any).streamInbox({ principalUid });
+
+    call.on("data", (data: any) => {
+      callback({
+        channelId: data.channelId,
+        eventId: data.eventId,
+        createdAtServer: data.createdAtServer ?? null,
+      });
+    });
+
+    return call;
+  }
+
+  /**
+   * Lists all agents registered with the daemon.
+   */
+  listAgents(): Promise<PrincipalInfo[]> {
+    return new Promise((resolve, reject) => {
+      (this.agentService as any).listAgents(
+        {},
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(
+            (response.agents ?? []).map((a: any) => ({
+              principalUid: a.principalUid,
+              displayName: a.displayName,
+              principalType: a.principalType,
+            }))
+          );
+        }
+      );
+    });
+  }
+
+  /**
+   * Lists all channels the daemon knows about.
+   */
+  listChannels(): Promise<ChannelSummary[]> {
+    return new Promise((resolve, reject) => {
+      (this.channelService as any).listChannels(
+        {},
+        (err: grpc.ServiceError | null, response: any) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(
+            (response.channels ?? []).map((c: any) => ({
+              channelId: c.channelId,
+              channelType: c.channelType,
+              title: c.title ?? null,
+              lastEventId: c.lastEventId,
+              lastEventAt: c.lastEventAt ?? null,
+              unreadCount: c.unreadCount,
+            }))
+          );
+        }
+      );
+    });
+  }
+
+  /**
+   * Closes all underlying gRPC connections.
+   */
+  close(): void {
+    this.agentService.close();
+    this.channelService.close();
+    this.eventService.close();
+  }
+}

package/src/config-schema.ts

@@ -0,0 +1,14 @@
+// ABOUTME: TypeScript types and defaults for Hermit channel plugin configuration.
+// ABOUTME: Defines per-account config shape and the top-level channel config.
+
+export type HermitAccountConfig = {
+  endpoint?: string;
+  principalUid?: string;
+  enabled?: boolean;
+};
+
+export type HermitChannelConfig = {
+  accounts?: Record<string, HermitAccountConfig>;
+};
+
+export const DEFAULT_ENDPOINT = "127.0.0.1:13370";

package/src/config.ts

@@ -0,0 +1,32 @@
+// ABOUTME: Account listing and resolution adapters for the Hermit channel plugin.
+// ABOUTME: Reads account config from the OpenClaw channel settings and merges with defaults.
+
+import type { HermitAccountConfig, HermitChannelConfig } from "./config-schema.js";
+import { DEFAULT_ENDPOINT } from "./config-schema.js";
+
+export interface ResolvedHermitAccount {
+  accountId: string;
+  endpoint: string;
+  principalUid: string | undefined;
+  enabled: boolean;
+}
+
+export function listHermitAccountIds(cfg: HermitChannelConfig): string[] {
+  if (!cfg.accounts || Object.keys(cfg.accounts).length === 0) {
+    return ["default"];
+  }
+  return Object.keys(cfg.accounts);
+}
+
+export function resolveHermitAccount(
+  cfg: HermitChannelConfig,
+  accountId: string
+): ResolvedHermitAccount {
+  const raw: HermitAccountConfig = cfg.accounts?.[accountId] ?? {};
+  return {
+    accountId,
+    endpoint: raw.endpoint ?? DEFAULT_ENDPOINT,
+    principalUid: raw.principalUid,
+    enabled: raw.enabled ?? true,
+  };
+}

package/src/dispatch.ts

@@ -0,0 +1,34 @@
+// ABOUTME: Bridges inbound Hermit inbox events into OpenClaw's reply dispatch system.
+// ABOUTME: Decrypts incoming events and feeds them to the agent via PluginRuntime.
+
+import type { InboxItem } from "./client.js";
+import { HermitClient } from "./client.js";
+import { getHermitRuntime } from "./runtime.js";
+
+export interface DispatchContext {
+  client: HermitClient;
+  accountId: string;
+  principalUid?: string;
+}
+
+export async function dispatchInboxEvent(
+  ctx: DispatchContext,
+  item: InboxItem
+): Promise<void> {
+  const _runtime = getHermitRuntime();
+
+  const decrypted = await ctx.client.decryptEvent(
+    item.channelId,
+    item.eventId,
+    ctx.principalUid
+  );
+
+  const content = decrypted.content.toString("utf-8");
+  const sessionKey = `hermit:${ctx.accountId}:${item.channelId}`;
+
+  // Inbound event dispatched — the runtime bridge will be wired once
+  // OpenClaw's channel dispatch API stabilizes.
+  console.log(
+    `[hermit] inbound event ${item.eventId} on ${sessionKey}: ${content.slice(0, 80)}`
+  );
+}

package/src/normalize.ts

@@ -0,0 +1,24 @@
+// ABOUTME: Session key formatting and parsing for Hermit channel sessions.
+// ABOUTME: Keys follow the pattern hermit:{accountId}:{channelId}.
+
+export interface ParsedSessionKey {
+  accountId: string;
+  channelId: string;
+}
+
+export function formatSessionKey(accountId: string, channelId: string): string {
+  return `hermit:${accountId}:${channelId}`;
+}
+
+export function parseSessionKey(key: string): ParsedSessionKey {
+  const parts = key.split(":");
+  if (parts.length !== 3 || parts[0] !== "hermit") {
+    throw new Error(`Invalid Hermit session key: ${key}`);
+  }
+  return { accountId: parts[1], channelId: parts[2] };
+}
+
+export function normalizeHermitTarget(raw: string): string {
+  parseSessionKey(raw);
+  return raw;
+}

package/src/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,66 @@
+// ABOUTME: Type declarations for the openclaw/plugin-sdk module (peer dependency).
+// ABOUTME: Minimal stubs covering the ChannelPlugin, PluginRuntime, and registration APIs.
+
+declare module "openclaw/plugin-sdk" {
+  /** Runtime context provided by the OpenClaw host to plugins. */
+  export interface PluginRuntime {
+    /** Channel reply dispatch helpers. */
+    channel: {
+      reply: {
+        dispatchReplyWithBufferedBlockDispatcher: (
+          sessionKey: string,
+          blocks: string[]
+        ) => Promise<void>;
+      };
+    };
+    [key: string]: unknown;
+  }
+
+  /** API object passed to a plugin's register() function. */
+  export interface OpenClawPluginApi {
+    runtime: PluginRuntime;
+    registerChannel(opts: { plugin: ChannelPlugin<any, any> }): void;
+    [key: string]: unknown;
+  }
+
+  /** Channel plugin contract. Generic over account shape and probe result. */
+  export interface ChannelPlugin<TAccount = unknown, TProbe = unknown> {
+    id: string;
+    meta: {
+      id: string;
+      label: string;
+      order: number;
+    };
+    capabilities: {
+      chatTypes: string[];
+      media: boolean;
+    };
+    config: {
+      listAccountIds(cfg: any): string[];
+      resolveAccount(cfg: any, accountId: string): TAccount;
+      defaultAccountId(cfg: any): string;
+    };
+    messaging: {
+      normalizeTarget: (raw: string) => string;
+      targetResolver: {
+        looksLikeId(raw: string): boolean;
+      };
+    };
+    heartbeat: {
+      checkReady(account: TAccount): Promise<boolean>;
+    };
+    status: {
+      probeAccount(account: TAccount): Promise<TProbe>;
+    };
+    outbound: {
+      sendText(account: TAccount, sessionKey: string, text: string): Promise<void>;
+      sendMedia(...args: unknown[]): Promise<void>;
+    };
+    gateway: {
+      startAccount(account: TAccount): Promise<() => void>;
+    };
+  }
+
+  /** Returns an empty config schema for plugins that need no configuration. */
+  export function emptyPluginConfigSchema(): Record<string, never>;
+}

package/src/runtime.ts

@@ -0,0 +1,17 @@
+// ABOUTME: Singleton holder for the OpenClaw PluginRuntime instance.
+// ABOUTME: Set during plugin registration, accessed by adapters at runtime.
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setHermitRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getHermitRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Hermit runtime not initialized — was register() called?");
+  }
+  return runtime;
+}

package/src/status.ts

@@ -0,0 +1,45 @@
+// ABOUTME: Health probe for the Hermit daemon gRPC endpoint.
+// ABOUTME: Returns reachability and latency for account status reporting.
+
+import * as grpc from "@grpc/grpc-js";
+import type { ResolvedHermitAccount } from "./config.js";
+
+export interface HermitProbeResult {
+  ok: boolean;
+  latencyMs: number;
+  serverReachable: boolean;
+  error?: string;
+}
+
+export async function probeHermit(
+  account: ResolvedHermitAccount,
+  timeoutMs: number = 5000
+): Promise<HermitProbeResult> {
+  const start = Date.now();
+  const client = new grpc.Client(
+    account.endpoint,
+    grpc.credentials.createInsecure()
+  );
+
+  return new Promise<HermitProbeResult>((resolve) => {
+    const deadline = new Date(Date.now() + timeoutMs);
+    client.waitForReady(deadline, (err) => {
+      const latencyMs = Date.now() - start;
+      client.close();
+      if (err) {
+        resolve({
+          ok: false,
+          latencyMs,
+          serverReachable: false,
+          error: err.message,
+        });
+      } else {
+        resolve({
+          ok: true,
+          latencyMs,
+          serverReachable: true,
+        });
+      }
+    });
+  });
+}

package/src/stream.ts

@@ -0,0 +1,73 @@
+// ABOUTME: Inbox stream subscription helper for real-time event delivery.
+// ABOUTME: Wraps the gRPC StreamInbox server-streaming call with a cancellable handle.
+
+import * as grpc from "@grpc/grpc-js";
+import { HermitClient, InboxItem } from "./client.js";
+
+/**
+ * Handle returned by subscribeToInbox, allowing the caller to cancel the
+ * server-streaming subscription.
+ */
+export interface InboxSubscription {
+  /** Cancels the gRPC stream. Safe to call multiple times. */
+  cancel: () => void;
+}
+
+/**
+ * Options for configuring the inbox subscription behavior.
+ */
+export interface SubscribeOptions {
+  /** Called when the stream encounters a non-cancellation error. */
+  onError?: (err: grpc.ServiceError) => void;
+  /** Called when the server closes the stream. */
+  onEnd?: () => void;
+}
+
+/**
+ * Subscribes to the inbox stream for a given principal. Each time the daemon
+ * delivers a new event notification, the onEvent callback fires with the
+ * channel ID and event ID. The caller can stop listening by calling cancel()
+ * on the returned subscription handle.
+ *
+ * Usage:
+ *   const sub = subscribeToInbox(client, agentUid, (item) => {
+ *     console.log(`New event ${item.eventId} in ${item.channelId}`);
+ *   });
+ *   // later...
+ *   sub.cancel();
+ */
+export function subscribeToInbox(
+  client: HermitClient,
+  principalUid: string,
+  onEvent: (item: InboxItem) => void,
+  options: SubscribeOptions = {}
+): InboxSubscription {
+  const call = client.streamInbox(principalUid, onEvent);
+
+  call.on("error", (err: grpc.ServiceError) => {
+    // gRPC fires CANCELLED when we call cancel(); that is not a real error.
+    if (err.code === grpc.status.CANCELLED) {
+      return;
+    }
+    if (options.onError) {
+      options.onError(err);
+    }
+  });
+
+  call.on("end", () => {
+    if (options.onEnd) {
+      options.onEnd();
+    }
+  });
+
+  let cancelled = false;
+
+  return {
+    cancel() {
+      if (!cancelled) {
+        cancelled = true;
+        call.cancel();
+      }
+    },
+  };
+}

package/src/tools.ts

@@ -0,0 +1,152 @@
+// ABOUTME: OpenClaw-compatible tool definitions and handler functions for Hermit.
+// ABOUTME: Defines hermit_read_recent and hermit_send_message tools with JSON Schema parameters.
+
+import { HermitClient, DecryptedPayload } from "./client.js";
+
+/**
+ * JSON Schema parameter definition for an OpenClaw tool property.
+ */
+interface ToolProperty {
+  type: string;
+  description: string;
+  default?: unknown;
+}
+
+/**
+ * OpenClaw-compatible tool specification.
+ */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, ToolProperty>;
+    required: string[];
+  };
+}
+
+/**
+ * Tool definitions exposed to the OpenClaw runtime. Each tool maps to one or
+ * more gRPC calls against the Hermit daemon.
+ */
+export const tools: ToolDefinition[] = [
+  {
+    name: "hermit_read_recent",
+    description: "Read recent messages from a Hermit channel",
+    parameters: {
+      type: "object",
+      properties: {
+        channel_id: {
+          type: "string",
+          description: "Channel ID to read messages from",
+        },
+        count: {
+          type: "number",
+          description: "Number of messages to read",
+          default: 10,
+        },
+      },
+      required: ["channel_id"],
+    },
+  },
+  {
+    name: "hermit_send_message",
+    description: "Send an encrypted message to a Hermit channel",
+    parameters: {
+      type: "object",
+      properties: {
+        channel_id: {
+          type: "string",
+          description: "Channel ID to send the message to",
+        },
+        text: {
+          type: "string",
+          description: "Message text to send",
+        },
+      },
+      required: ["channel_id", "text"],
+    },
+  },
+];
+
+/**
+ * Parameters accepted by the hermit_read_recent tool.
+ */
+export interface ReadRecentParams {
+  channel_id: string;
+  count?: number;
+}
+
+/**
+ * Parameters accepted by the hermit_send_message tool.
+ */
+export interface SendMessageParams {
+  channel_id: string;
+  text: string;
+}
+
+/**
+ * A single decrypted message returned by handleReadRecent.
+ */
+export interface ReadRecentMessage {
+  eventId: string;
+  senderUid: string;
+  eventKind: string;
+  content: string;
+  sentAt: { seconds: number; nanos: number } | null;
+}
+
+/**
+ * Result from sending a message via handleSendMessage.
+ */
+export interface SendMessageResult {
+  eventId: string;
+  channelId: string;
+  status: "sent";
+}
+
+/**
+ * Reads recent messages from a channel by listing events and decrypting each one.
+ *
+ * Fetches envelopes via ListEvents, then decrypts all in parallel via DecryptEvent.
+ */
+export async function handleReadRecent(
+  client: HermitClient,
+  params: ReadRecentParams
+): Promise<ReadRecentMessage[]> {
+  const limit = params.count ?? 10;
+  const envelopes = await client.listEvents(params.channel_id, limit);
+
+  const messages = await Promise.all(
+    envelopes.map(async (envelope) => {
+      const decrypted: DecryptedPayload = await client.decryptEvent(
+        params.channel_id,
+        envelope.eventId
+      );
+      return {
+        eventId: decrypted.eventId,
+        senderUid: decrypted.senderUid,
+        eventKind: decrypted.eventKind,
+        content: decrypted.content.toString("utf-8"),
+        sentAt: decrypted.sentAt,
+      } satisfies ReadRecentMessage;
+    })
+  );
+
+  return messages;
+}
+
+/**
+ * Sends an encrypted message to a channel.
+ */
+export async function handleSendMessage(
+  client: HermitClient,
+  params: SendMessageParams
+): Promise<SendMessageResult> {
+  const { eventId } = await client.postMessage(params.channel_id, params.text);
+  return {
+    eventId,
+    channelId: params.channel_id,
+    status: "sent",
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["index.ts", "src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}