@2389research/coven-openclaw 0.1.0

package/src/channel.ts

@@ -0,0 +1,253 @@
+// ABOUTME: ChannelPlugin definition wiring all coven adapters together.
+// ABOUTME: Follows the same pattern as openclaw's Discord channel plugin.
+
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import {
+  listCovenAccountIds,
+  resolveCovenAccount,
+  type ResolvedCovenAccount,
+} from "./config.js";
+import { normalizeCovenTarget } from "./normalize.js";
+import { CovenGrpcClient, type CovenWelcome } from "./grpc-client.js";
+import { covenSendMessageToInbound } from "./protocol.js";
+import { probeCoven, type CovenProbeResult } from "./status.js";
+import { registerCovenMcp, unregisterCovenMcp } from "./mcp-bridge.js";
+
+// Track active gRPC clients per account
+const activeClients = new Map<string, CovenGrpcClient>();
+
+export const covenPlugin: ChannelPlugin<ResolvedCovenAccount, CovenProbeResult> = {
+  id: "coven" as any,
+
+  meta: {
+    id: "coven" as any,
+    label: "Coven Gateway",
+    selectionLabel: "Coven Gateway (gRPC)",
+    docsPath: "/channels/coven",
+    blurb: "Connect openclaw agents to coven-gateway via gRPC AgentStream.",
+    order: 90,
+  },
+
+  capabilities: {
+    chatTypes: ["direct", "thread"],
+    media: true,
+  },
+
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+  },
+
+  reload: { configPrefixes: ["channels.coven"] },
+
+  config: {
+    listAccountIds: (cfg) => listCovenAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveCovenAccount(cfg, accountId),
+    defaultAccountId: () => "default",
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const next = structuredClone(cfg);
+      if (!next.channels) next.channels = {};
+      if (!next.channels.coven) next.channels.coven = {};
+      if (!next.channels.coven.accounts) next.channels.coven.accounts = {};
+      if (!next.channels.coven.accounts[accountId]) {
+        next.channels.coven.accounts[accountId] = {};
+      }
+      next.channels.coven.accounts[accountId].enabled = enabled;
+      return next;
+    },
+    isConfigured: (account) => Boolean(account.endpoint?.trim()),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: `coven-${account.accountId}`,
+      enabled: account.enabled,
+      configured: Boolean(account.endpoint?.trim()),
+    }),
+  },
+
+  messaging: {
+    normalizeTarget: normalizeCovenTarget,
+    targetResolver: {
+      looksLikeId: (raw) => raw.startsWith("coven:"),
+      hint: "coven:<accountId>:<threadId>",
+    },
+  },
+
+  heartbeat: {
+    checkReady: async ({ cfg, accountId }) => {
+      const account = resolveCovenAccount(cfg, accountId);
+      const client = activeClients.get(account.accountId);
+      if (!client || !client.connected) {
+        return { ok: false, reason: "coven-not-connected" };
+      }
+      return { ok: true, reason: "ok" };
+    },
+  },
+
+  status: {
+    defaultRuntime: {
+      accountId: "default",
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeCoven(account, timeoutMs),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: `coven-${account.accountId}`,
+      enabled: account.enabled,
+      configured: Boolean(account.endpoint?.trim()),
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+    }),
+  },
+
+  outbound: {
+    deliveryMode: "direct",
+    chunker: null,
+    textChunkLimit: 4000,
+    sendText: async ({ to, text }) => {
+      const parts = to.split(":");
+      if (parts.length < 3 || parts[0] !== "coven") {
+        throw new Error(`Invalid coven target: ${to}`);
+      }
+      const accountId = parts[1];
+      const client = activeClients.get(accountId);
+      if (!client || !client.connected) {
+        throw new Error(`No active coven connection for account: ${accountId}`);
+      }
+
+      client.send({
+        response: {
+          request_id: "",
+          text,
+        },
+      });
+
+      return {
+        channel: "coven" as any,
+        messageId: `coven-${Date.now()}`,
+      };
+    },
+    sendMedia: async ({ to }) => {
+      const parts = to.split(":");
+      const accountId = parts[1] ?? "default";
+      const client = activeClients.get(accountId);
+      if (!client || !client.connected) {
+        throw new Error(`No active coven connection for account: ${accountId}`);
+      }
+
+      return {
+        channel: "coven" as any,
+        messageId: `coven-${Date.now()}`,
+      };
+    },
+  },
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const agentName = account.mode === "single" ? "openclaw" : "default";
+
+      ctx.log?.info?.(
+        `[${account.accountId}] connecting to coven-gateway at ${account.endpoint}`
+      );
+
+      const client = new CovenGrpcClient(account);
+      activeClients.set(account.accountId, client);
+
+      try {
+        const welcome = await client.connect(agentName);
+        ctx.log?.info?.(
+          `[${account.accountId}] registered as ${welcome.agent_id} (instance: ${welcome.instance_id})`
+        );
+
+        if (welcome.mcp_endpoint && welcome.mcp_token) {
+          registerCovenMcp(welcome);
+          ctx.log?.info?.(
+            `[${account.accountId}] MCP bridge registered at ${welcome.mcp_endpoint}`
+          );
+        }
+
+        client.on("send_message", (msg: any) => {
+          const inbound = covenSendMessageToInbound(msg, account.accountId);
+          ctx.log?.info?.(
+            `[${account.accountId}] inbound message: ${inbound.requestId} from ${inbound.sender}`
+          );
+        });
+
+        client.on("inject_context", (msg: any) => {
+          ctx.log?.info?.(
+            `[${account.accountId}] context injection: ${msg.injection_id}`
+          );
+          client.send({
+            injection_ack: {
+              injection_id: msg.injection_id,
+              accepted: true,
+            },
+          });
+        });
+
+        client.on("cancel_request", (msg: any) => {
+          ctx.log?.info?.(
+            `[${account.accountId}] cancel request: ${msg.request_id}`
+          );
+          client.send({
+            response: {
+              request_id: msg.request_id,
+              cancelled: { reason: msg.reason ?? "server_requested" },
+            },
+          });
+        });
+
+        client.on("shutdown", (msg: any) => {
+          ctx.log?.warn?.(
+            `[${account.accountId}] server shutdown: ${msg.reason}`
+          );
+          client.disconnect();
+        });
+
+        client.on("disconnected", async () => {
+          ctx.log?.warn?.(
+            `[${account.accountId}] disconnected, attempting reconnect...`
+          );
+          unregisterCovenMcp();
+          const newWelcome = await client.reconnect();
+          if (newWelcome) {
+            ctx.log?.info?.(
+              `[${account.accountId}] reconnected as ${newWelcome.agent_id}`
+            );
+            if (newWelcome.mcp_endpoint && newWelcome.mcp_token) {
+              registerCovenMcp(newWelcome);
+            }
+          } else {
+            ctx.log?.error?.(
+              `[${account.accountId}] reconnection failed after max attempts`
+            );
+          }
+        });
+
+        client.on("error", (err: Error) => {
+          ctx.log?.error?.(
+            `[${account.accountId}] gRPC error: ${err.message}`
+          );
+        });
+      } catch (err) {
+        activeClients.delete(account.accountId);
+        throw err;
+      }
+
+      return () => {
+        const c = activeClients.get(account.accountId);
+        if (c) {
+          c.disconnect();
+          activeClients.delete(account.accountId);
+          unregisterCovenMcp();
+        }
+      };
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,40 @@
+// ABOUTME: JSON schema definition for the coven channel configuration.
+// ABOUTME: Defines the shape of accounts under channels.coven in openclaw config.
+
+export type CovenAuthMethod = "ssh" | "jwt" | "none";
+export type CovenAgentMode = "multi" | "single";
+
+export type CovenReconnectConfig = {
+  maxAttempts: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+};
+
+export type CovenAccountConfig = {
+  endpoint?: string;
+  mode?: CovenAgentMode;
+  agentFilter?: string[];
+  tls?: boolean;
+  authMethod?: CovenAuthMethod;
+  sshKeyPath?: string;
+  jwtSecret?: string;
+  jwtToken?: string;
+  heartbeatIntervalMs?: number;
+  reconnect?: Partial<CovenReconnectConfig>;
+  enabled?: boolean;
+};
+
+export type CovenChannelConfig = {
+  accounts?: Record<string, CovenAccountConfig>;
+};
+
+export const DEFAULT_ENDPOINT = "localhost:50051";
+export const DEFAULT_MODE: CovenAgentMode = "multi";
+export const DEFAULT_AUTH_METHOD: CovenAuthMethod = "ssh";
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+
+export const DEFAULT_RECONNECT: CovenReconnectConfig = {
+  maxAttempts: 10,
+  baseDelayMs: 1000,
+  maxDelayMs: 60000,
+};

package/src/config.ts

@@ -0,0 +1,91 @@
+// ABOUTME: Account resolution and config adapter for the coven channel plugin.
+// ABOUTME: Lists accounts, resolves account settings with defaults, handles enable/disable.
+
+import {
+  DEFAULT_ENDPOINT,
+  DEFAULT_MODE,
+  DEFAULT_AUTH_METHOD,
+  DEFAULT_HEARTBEAT_INTERVAL_MS,
+  DEFAULT_RECONNECT,
+  type CovenAgentMode,
+  type CovenAuthMethod,
+  type CovenReconnectConfig,
+  type CovenAccountConfig,
+} from "./config-schema.js";
+import { readLinkedConfig } from "./linked-config.js";
+
+export type ResolvedCovenAccount = {
+  accountId: string;
+  endpoint: string;
+  mode: CovenAgentMode;
+  agentFilter: string[];
+  tls: boolean;
+  authMethod: CovenAuthMethod;
+  sshKeyPath: string;
+  jwtSecret: string;
+  jwtToken: string;
+  heartbeatIntervalMs: number;
+  reconnect: CovenReconnectConfig;
+  enabled: boolean;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyConfig = Record<string, any>;
+
+function getCovenSection(cfg: AnyConfig): AnyConfig | undefined {
+  return cfg?.channels?.coven;
+}
+
+function getAccountsMap(
+  cfg: AnyConfig
+): Record<string, CovenAccountConfig> | undefined {
+  return getCovenSection(cfg)?.accounts;
+}
+
+export function listCovenAccountIds(cfg: AnyConfig): string[] {
+  const accounts = getAccountsMap(cfg);
+  if (!accounts) return [];
+  return Object.keys(accounts);
+}
+
+export function resolveCovenAccount(
+  cfg: AnyConfig,
+  accountId?: string | null
+): ResolvedCovenAccount {
+  const resolvedId = accountId ?? "default";
+  const accounts = getAccountsMap(cfg) ?? {};
+  const raw: CovenAccountConfig = accounts[resolvedId] ?? {};
+
+  // Read linked config once for fallback values
+  const linked = readLinkedConfig();
+
+  // Use linked config gateway when no explicit endpoint is configured
+  const endpoint =
+    raw.endpoint ?? (linked?.gateway ? linked.gateway : DEFAULT_ENDPOINT);
+
+  // Default to "jwt" auth when linked config provides a token and no explicit authMethod
+  const authMethod =
+    raw.authMethod ?? (linked?.token ? "jwt" : DEFAULT_AUTH_METHOD);
+
+  // Populate jwtToken from linked config when not explicitly set
+  const jwtToken = raw.jwtToken ?? (linked?.token ? linked.token : "");
+
+  return {
+    accountId: resolvedId,
+    endpoint,
+    mode: raw.mode ?? DEFAULT_MODE,
+    agentFilter: raw.agentFilter ?? [],
+    tls: raw.tls ?? false,
+    authMethod,
+    sshKeyPath: raw.sshKeyPath ?? "~/.ssh/id_ed25519",
+    jwtSecret: raw.jwtSecret ?? "",
+    jwtToken,
+    heartbeatIntervalMs: raw.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+    reconnect: {
+      maxAttempts: raw.reconnect?.maxAttempts ?? DEFAULT_RECONNECT.maxAttempts,
+      baseDelayMs: raw.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT.baseDelayMs,
+      maxDelayMs: raw.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT.maxDelayMs,
+    },
+    enabled: raw.enabled ?? true,
+  };
+}

package/src/grpc-client.ts

@@ -0,0 +1,270 @@
+// ABOUTME: gRPC stream management for the coven-gateway AgentStream connection.
+// ABOUTME: Handles connect, disconnect, reconnect with exponential backoff, and heartbeat.
+
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EventEmitter } from "node:events";
+import type { ResolvedCovenAccount } from "./config.js";
+import { buildRegistration, type RegistrationParams } from "./registration.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROTO_PATH = path.resolve(__dirname, "../proto/coven.proto");
+
+export const PROTO_VERSION = "2026-02-14";
+
+export type CovenWelcome = {
+  server_id: string;
+  agent_id: string;
+  instance_id: string;
+  principal_id: string;
+  available_tools: unknown[];
+  mcp_token: string;
+  mcp_endpoint: string;
+  secrets: Record<string, string>;
+};
+
+type ProtoDefinition = ReturnType<typeof grpc.loadPackageDefinition>;
+
+function loadProtoDefinition(): ProtoDefinition {
+  const packageDef = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: true,
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+  });
+  return grpc.loadPackageDefinition(packageDef);
+}
+
+let cachedProto: ProtoDefinition | null = null;
+
+function getProto(): ProtoDefinition {
+  if (!cachedProto) {
+    cachedProto = loadProtoDefinition();
+  }
+  return cachedProto;
+}
+
+export class CovenGrpcClient extends EventEmitter {
+  private account: ResolvedCovenAccount;
+  private grpcClient: any = null;
+  private stream: any = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private _connected = false;
+  private _heartbeatsSent = 0;
+  private _agentName: string | null = null;
+  private _disconnecting = false;
+
+  constructor(account: ResolvedCovenAccount) {
+    super();
+    this.account = account;
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  get heartbeatsSent(): number {
+    return this._heartbeatsSent;
+  }
+
+  async connect(
+    agentName: string,
+    registrationOverrides?: Partial<RegistrationParams>
+  ): Promise<CovenWelcome> {
+    this._agentName = agentName;
+
+    const proto = getProto() as any;
+    const credentials = this.account.tls
+      ? grpc.credentials.createSsl()
+      : grpc.credentials.createInsecure();
+
+    this.grpcClient = new proto.coven.CovenControl(
+      this.account.endpoint,
+      credentials
+    );
+
+    const metadata = new grpc.Metadata();
+    if (this.account.jwtToken) {
+      metadata.set("authorization", `Bearer ${this.account.jwtToken}`);
+    }
+
+    this.stream = this.grpcClient.AgentStream(metadata);
+
+    this._disconnecting = false;
+
+    return new Promise<CovenWelcome>((resolve, reject) => {
+      const registration = buildRegistration({
+        account: this.account,
+        agentName,
+        ...registrationOverrides,
+      });
+
+      const timeoutId = setTimeout(() => {
+        cleanup();
+        reject(new Error("Registration timed out waiting for Welcome"));
+      }, 10000);
+
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        if (this.stream) {
+          this.stream.removeListener("data", onData);
+          this.stream.removeListener("error", onError);
+        }
+      };
+
+      const onData = (msg: any) => {
+        if (msg.welcome) {
+          cleanup();
+          this._connected = true;
+          this.startHeartbeat();
+          this.attachStreamHandlers();
+          resolve(msg.welcome);
+        } else if (msg.registration_error) {
+          cleanup();
+          reject(
+            new Error(
+              `Registration rejected: ${msg.registration_error.reason}`
+            )
+          );
+        }
+      };
+
+      const onError = (err: Error) => {
+        cleanup();
+        reject(err);
+      };
+
+      this.stream.on("data", onData);
+      this.stream.on("error", onError);
+
+      this.stream.write({ register: registration });
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    this._disconnecting = true;
+    this.stopHeartbeat();
+    this._connected = false;
+
+    const stream = this.stream;
+    const client = this.grpcClient;
+
+    this.stream = null;
+    this.grpcClient = null;
+
+    if (stream) {
+      // Replace all listeners with a no-op error sink to absorb any
+      // CANCELLED errors that fire asynchronously after close/end.
+      stream.removeAllListeners("data");
+      stream.removeAllListeners("end");
+      stream.removeAllListeners("error");
+      stream.on("error", () => {});
+      stream.end();
+    }
+
+    if (client) {
+      client.close();
+    }
+  }
+
+  send(message: Record<string, unknown>): void {
+    if (!this.stream) {
+      throw new Error("Not connected — call connect() first");
+    }
+    this.stream.write(message);
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this._connected && this.stream) {
+        this.stream.write({
+          heartbeat: { timestamp_ms: Date.now() },
+        });
+        this._heartbeatsSent++;
+      }
+    }, this.account.heartbeatIntervalMs);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private attachStreamHandlers(): void {
+    if (!this.stream) return;
+
+    this.stream.on("data", (msg: any) => {
+      if (msg.send_message) {
+        this.emit("send_message", msg.send_message);
+      } else if (msg.inject_context) {
+        this.emit("inject_context", msg.inject_context);
+      } else if (msg.cancel_request) {
+        this.emit("cancel_request", msg.cancel_request);
+      } else if (msg.shutdown) {
+        this.emit("shutdown", msg.shutdown);
+      } else if (msg.tool_approval) {
+        this.emit("tool_approval", msg.tool_approval);
+      } else if (msg.pack_tool_result) {
+        this.emit("pack_tool_result", msg.pack_tool_result);
+      }
+    });
+
+    this.stream.on("error", (err: Error) => {
+      if (this._disconnecting) return;
+      this._connected = false;
+      this.stopHeartbeat();
+      this.emit("error", err);
+    });
+
+    this.stream.on("end", () => {
+      if (this._disconnecting) return;
+      this._connected = false;
+      this.stopHeartbeat();
+      this.emit("disconnected");
+    });
+  }
+
+  async reconnect(): Promise<CovenWelcome | null> {
+    const { maxAttempts, baseDelayMs, maxDelayMs } = this.account.reconnect;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const delay = Math.min(
+        baseDelayMs * Math.pow(2, attempt - 1),
+        maxDelayMs
+      );
+
+      await new Promise((r) => setTimeout(r, delay));
+
+      try {
+        if (this.grpcClient) {
+          this.grpcClient.close();
+          this.grpcClient = null;
+        }
+
+        if (!this._agentName) {
+          throw new Error(
+            "Cannot reconnect: no agent name from initial connect"
+          );
+        }
+
+        const welcome = await this.connect(this._agentName);
+        this.emit("reconnected", welcome);
+        return welcome;
+      } catch (err) {
+        this.emit("reconnect_attempt", { attempt, maxAttempts, error: err });
+        if (attempt === maxAttempts) {
+          this.emit("reconnect_failed", err);
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+}