@brantrusnak/openclaw-omadeus 1.0.0

package/src/reply-dispatcher.ts

@@ -0,0 +1,63 @@
+import {
+  createReplyPrefixContext,
+  type OpenClawConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";
+import { sendOmadeusMessage, type OutboundDeps } from "./outbound.js";
+import { getOmadeusRuntime } from "./runtime.js";
+
+type Log = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string, extra?: Record<string, unknown>) => void;
+  debug?: (msg: string) => void;
+};
+
+export type CreateOmadeusReplyDispatcherParams = {
+  cfg: OpenClawConfig;
+  agentId: string;
+  accountId?: string;
+  runtime: RuntimeEnv;
+  log: Log;
+  outboundDeps: OutboundDeps;
+  roomId: string;
+};
+
+export function createOmadeusReplyDispatcher(params: CreateOmadeusReplyDispatcherParams) {
+  const core = getOmadeusRuntime();
+  const { cfg, agentId, roomId, accountId } = params;
+
+  const prefixContext = createReplyPrefixContext({ cfg, agentId });
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit(cfg, "omadeus", accountId, {
+    fallbackLimit: 4000,
+  });
+  const chunkMode = core.channel.text.resolveChunkMode(cfg, "omadeus");
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
+      deliver: async (payload: ReplyPayload) => {
+        const text = payload.text ?? "";
+        if (!text.trim()) return;
+
+        const chunks = core.channel.text.chunkTextWithMode(text, textChunkLimit, chunkMode);
+        for (const chunk of chunks) {
+          await sendOmadeusMessage(params.outboundDeps, { to: String(roomId), text: chunk });
+        }
+      },
+      onError: (error, info) => {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        params.runtime.error?.(`omadeus ${info.kind} reply failed: ${errMsg}`);
+        params.log.error("reply failed", { kind: info.kind, error: errMsg });
+      },
+    });
+
+  return {
+    dispatcher,
+    replyOptions: { ...replyOptions, onModelSelected: prefixContext.onModelSelected },
+    markDispatchIdle,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,7 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "../runtime-api.js";
+
+const { setRuntime: setOmadeusRuntime, getRuntime: getOmadeusRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("Omadeus runtime not initialized");
+
+export { getOmadeusRuntime, setOmadeusRuntime };

package/src/setup-core.ts

@@ -0,0 +1,54 @@
+import type { ChannelSetupAdapter } from "openclaw/plugin-sdk/setup";
+import type { OpenClawConfig } from "../runtime-api.js";
+
+function readSetupStringField(input: Record<string, unknown>, key: string): string | undefined {
+  const value = input[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readSetupNumberField(input: Record<string, unknown>, key: string): number | undefined {
+  const value = input[key];
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value.trim());
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+export const omadeusSetupAdapter: ChannelSetupAdapter = {
+  validateInput: ({ input }) => {
+    const rawInput = input as Record<string, unknown>;
+    const email = readSetupStringField(rawInput, "email");
+    if (!email && !input.useEnv) {
+      return "Omadeus requires --email (or use OMADEUS_EMAIL env var).";
+    }
+    return null;
+  },
+  applyAccountConfig: ({ cfg, input }) => {
+    const rawInput = input as Record<string, unknown>;
+    const casUrl = input.httpUrl?.trim() || undefined;
+    const maestroUrl = input.url?.trim() || undefined;
+    const email = readSetupStringField(rawInput, "email");
+    const password = input.password?.trim() || undefined;
+    const organizationId = readSetupNumberField(rawInput, "organizationId");
+
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        omadeus: {
+          ...(cfg.channels as Record<string, unknown>)?.["omadeus"],
+          enabled: true,
+          ...(casUrl ? { casUrl } : {}),
+          ...(maestroUrl ? { maestroUrl } : {}),
+          ...(email ? { email } : {}),
+          ...(password ? { password } : {}),
+          ...(organizationId ? { organizationId } : {}),
+        },
+      },
+    } as OpenClawConfig;
+  },
+};

package/src/setup-surface.ts

@@ -0,0 +1 @@
+export { omadeusSetupWizard } from "./onboarding.js";

package/src/socket/dolphin.socket.ts

@@ -0,0 +1,31 @@
+import type { OmadeusTokenManager } from "../token.js";
+import { createOmadeusSocketClient, type OmadeusSocketClient } from "./socket.js";
+
+export type DolphinSocketOptions = {
+  maestroUrl: string;
+  tokenManager: OmadeusTokenManager;
+  /** Called for every event received on the Dolphin data socket. */
+  onEvent?: (data: Record<string, unknown>) => void;
+  onConnect?: () => void;
+  onDisconnect?: (reason: string) => void;
+  onError?: (error: Error) => void;
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+};
+
+export type DolphinSocketClient = OmadeusSocketClient;
+
+export function createDolphinSocketClient(opts: DolphinSocketOptions): DolphinSocketClient {
+  const { maestroUrl, tokenManager, onEvent, onConnect, onDisconnect, onError, log } = opts;
+
+  return createOmadeusSocketClient({
+    maestroUrl,
+    tokenManager,
+    pathSuffix: "dolphin-ws",
+    logPrefix: "[dolphin]",
+    onEvent,
+    onConnect,
+    onDisconnect,
+    onError,
+    log,
+  });
+}

package/src/socket/jaguar.socket.ts

@@ -0,0 +1,49 @@
+import { isOmadeusMessage } from "../inbound.js";
+import type { OmadeusTokenManager } from "../token.js";
+import type { OmadeusMessage } from "../types.js";
+import { createOmadeusSocketClient, type OmadeusSocketClient } from "./socket.js";
+
+export type JaguarSocketOptions = {
+  maestroUrl: string;
+  tokenManager: OmadeusTokenManager;
+  onMessage?: (msg: OmadeusMessage) => void;
+  /** Called for any non-message events (typing, presence, etc.). */
+  onOtherEvent?: (data: Record<string, unknown>) => void;
+  onConnect?: () => void;
+  onDisconnect?: (reason: string) => void;
+  onError?: (error: Error) => void;
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+};
+
+export type JaguarSocketClient = OmadeusSocketClient;
+
+export function createJaguarSocketClient(opts: JaguarSocketOptions): JaguarSocketClient {
+  const {
+    maestroUrl,
+    tokenManager,
+    onMessage,
+    onOtherEvent,
+    onConnect,
+    onDisconnect,
+    onError,
+    log,
+  } = opts;
+
+  return createOmadeusSocketClient({
+    maestroUrl,
+    tokenManager,
+    pathSuffix: "ws",
+    logPrefix: "[jaguar]",
+    onEvent: (data) => {
+      if (isOmadeusMessage(data)) {
+        onMessage?.(data as OmadeusMessage);
+      } else {
+        onOtherEvent?.(data);
+      }
+    },
+    onConnect,
+    onDisconnect,
+    onError,
+    log,
+  });
+}

package/src/socket/socket.ts

@@ -0,0 +1,207 @@
+import { WebSocket } from "ws";
+import type { OmadeusTokenManager } from "../token.js";
+
+export type OmadeusSocketOptions = {
+  maestroUrl: string;
+  tokenManager: OmadeusTokenManager;
+  /** Path suffix for the websocket endpoint (e.g. "ws" or "dolphin-ws"). */
+  pathSuffix: string;
+  /** Log prefix, e.g. "[jaguar]" or "[dolphin]". */
+  logPrefix: string;
+  onEvent?: (data: Record<string, unknown>) => void;
+  onConnect?: () => void;
+  onDisconnect?: (reason: string) => void;
+  onError?: (error: Error) => void;
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+};
+
+export type OmadeusSocketClient = {
+  connect(): void;
+  disconnect(): void;
+  isConnected(): boolean;
+  /** Send a raw JSON payload over the socket. */
+  send(data: unknown): void;
+};
+
+const RECONNECT_BASE_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+// Heartbeat tuning knobs for Omadeus sockets.
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_MISSED_MAX = 5;
+const KEEP_ALIVE_CONTENT = "keep-alive";
+const KEEP_ALIVE_ACTION = "answer";
+
+function isKeepAliveMessage(data: Record<string, unknown>): boolean {
+  const content = (data as { content?: unknown }).content;
+  const payloadData = (data as { data?: unknown }).data;
+  return content === KEEP_ALIVE_CONTENT || payloadData === KEEP_ALIVE_CONTENT;
+}
+
+export function createOmadeusSocketClient(opts: OmadeusSocketOptions): OmadeusSocketClient {
+  const {
+    maestroUrl,
+    tokenManager,
+    pathSuffix,
+    logPrefix,
+    onEvent,
+    onConnect,
+    onDisconnect,
+    onError,
+    log,
+  } = opts;
+
+  let ws: WebSocket | null = null;
+  let reconnectAttempt = 0;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let heartbeatMissCount = 0;
+  let intentionalClose = false;
+
+  function buildWsUrl(): string {
+    const base = maestroUrl.replace(/^http/, "ws");
+    const token = tokenManager.getToken();
+    return `${base}/${pathSuffix}?token=${encodeURIComponent(token)}`;
+  }
+
+  function scheduleReconnect() {
+    if (intentionalClose) return;
+    const delayMs = Math.min(RECONNECT_BASE_MS * 2 ** reconnectAttempt, RECONNECT_MAX_MS);
+    reconnectAttempt++;
+    log?.info(`${logPrefix} reconnecting in ${delayMs}ms (attempt ${reconnectAttempt})`);
+    reconnectTimer = setTimeout(() => connect(), delayMs);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  function resetHeartbeat() {
+    heartbeatMissCount = 0;
+  }
+
+  function sendKeepAlive() {
+    if (ws?.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    heartbeatMissCount += 1;
+    ws.send(JSON.stringify({ data: KEEP_ALIVE_CONTENT, action: KEEP_ALIVE_ACTION }));
+
+    if (heartbeatMissCount >= HEARTBEAT_MISSED_MAX) {
+      log?.warn(
+        `${logPrefix} heartbeat unanswered ${heartbeatMissCount} times; reconnecting socket`,
+      );
+      ws.close();
+    }
+  }
+
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(() => {
+      sendKeepAlive();
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  function connect() {
+    if (ws) {
+      ws.removeAllListeners();
+      ws.close();
+      ws = null;
+    }
+    intentionalClose = false;
+    stopHeartbeat();
+    resetHeartbeat();
+
+    if (tokenManager.needsRefresh()) {
+      tokenManager
+        .refresh()
+        .then(() => connect())
+        .catch((err) => {
+          onError?.(err instanceof Error ? err : new Error(String(err)));
+          scheduleReconnect();
+        });
+      return;
+    }
+
+    const url = buildWsUrl();
+    log?.info(`${logPrefix} connecting...`);
+
+    ws = new WebSocket(url);
+
+    ws.on("open", () => {
+      reconnectAttempt = 0;
+      log?.info(`${logPrefix} connected`);
+      onConnect?.();
+      resetHeartbeat();
+      sendKeepAlive();
+      startHeartbeat();
+    });
+
+    ws.on("message", (raw) => {
+      try {
+        const data = JSON.parse(String(raw)) as Record<string, unknown>;
+
+        const action = (data as { action?: unknown }).action;
+        if (isKeepAliveMessage(data) && action === KEEP_ALIVE_ACTION) {
+          resetHeartbeat();
+          return;
+        }
+
+        // If backend sends heartbeat pings, answer them immediately.
+        if (isKeepAliveMessage(data) && action === "heartbeat") {
+          if (ws?.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ data: KEEP_ALIVE_CONTENT, action: KEEP_ALIVE_ACTION }));
+          }
+          return;
+        }
+
+        onEvent?.(data);
+      } catch {
+        log?.warn(`${logPrefix} unparseable message: ${String(raw).slice(0, 200)}`);
+      }
+    });
+
+    ws.on("close", (code, reason) => {
+      const msg = `code=${code} reason=${String(reason)}`;
+      log?.info(`${logPrefix} disconnected: ${msg}`);
+      onDisconnect?.(msg);
+      ws = null;
+      stopHeartbeat();
+      resetHeartbeat();
+      scheduleReconnect();
+    });
+
+    ws.on("error", (err) => {
+      log?.error(`${logPrefix} error: ${err.message}`);
+      onError?.(err);
+    });
+  }
+
+  function disconnect() {
+    intentionalClose = true;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    stopHeartbeat();
+    resetHeartbeat();
+    if (ws) {
+      ws.removeAllListeners();
+      ws.close();
+      ws = null;
+    }
+  }
+
+  return {
+    connect,
+    disconnect,
+    isConnected: () => ws?.readyState === WebSocket.OPEN,
+    send: (data) => {
+      if (ws?.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(data));
+      }
+    },
+  };
+}

package/src/store.ts

@@ -0,0 +1,18 @@
+export type CasSession = {
+  token: string;
+  refreshCookie: string;
+};
+
+let currentSession: CasSession | null = null;
+
+export function setCasSession(session: CasSession): void {
+  currentSession = session;
+}
+
+export function getCasSession(): CasSession | null {
+  return currentSession;
+}
+
+export function clearCasSession(): void {
+  currentSession = null;
+}

package/src/token.ts

@@ -0,0 +1,120 @@
+import { authenticate } from "./auth.js";
+import type { OmadeusJwtPayload } from "./types.js";
+import { decodeJwtPayload, tokenExpiresInMs } from "./utils/jwt.util.js";
+
+// Re-authenticate 5 minutes before expiry
+const TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+// Node.js timers use a 32-bit signed integer for delays; clamp below this to avoid overflow warnings.
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/** Whether the token should be refreshed now (within safety margin). */
+export function shouldRefreshToken(token: string): boolean {
+  return tokenExpiresInMs(token) < TOKEN_REFRESH_MARGIN_MS;
+}
+
+export type OmadeusTokenManager = {
+  getToken(): string;
+  getPayload(): OmadeusJwtPayload;
+  refresh(): Promise<void>;
+  startAutoRefresh(): void;
+  stopAutoRefresh(): void;
+  needsRefresh(): boolean;
+};
+
+export function createTokenManager(params: {
+  casUrl: string;
+  maestroUrl: string;
+  email: string;
+  password: string;
+  organizationId: number;
+  initialToken?: string;
+  onRefresh?: (token: string) => void;
+  onError?: (error: Error) => void;
+}): OmadeusTokenManager {
+  const { casUrl, maestroUrl, email, password, organizationId, initialToken, onRefresh, onError } =
+    params;
+
+  let currentToken = "";
+  let currentPayload: OmadeusJwtPayload | null = null;
+  if (initialToken) {
+    try {
+      const payload = decodeJwtPayload(initialToken);
+      currentToken = initialToken;
+      currentPayload = payload;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError?.(error);
+      // Ignore malformed seed token and fall back to authenticate().
+    }
+  }
+  let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const refresh = async () => {
+    if (currentToken && !shouldRefreshToken(currentToken)) {
+      return;
+    }
+    const { dolphinToken, payload } = await authenticate({
+      casUrl,
+      maestroUrl,
+      email,
+      password,
+      organizationId,
+    });
+    currentToken = dolphinToken;
+    currentPayload = payload;
+    onRefresh?.(dolphinToken);
+  };
+
+  const scheduleNextRefresh = () => {
+    if (refreshTimer) {
+      clearTimeout(refreshTimer);
+      refreshTimer = null;
+    }
+    if (!currentToken) return;
+
+    const expiresInMs = tokenExpiresInMs(currentToken);
+    const desiredDelayMs = expiresInMs - TOKEN_REFRESH_MARGIN_MS;
+    const refreshInMs = Math.min(Math.max(desiredDelayMs, 10_000), MAX_TIMEOUT_MS);
+
+    refreshTimer = setTimeout(async () => {
+      try {
+        await refresh();
+        scheduleNextRefresh();
+      } catch (err) {
+        onError?.(err instanceof Error ? err : new Error(String(err)));
+        // Retry in 30s on failure
+        refreshTimer = setTimeout(() => void scheduleNextRefresh(), 30_000);
+      }
+    }, refreshInMs);
+  };
+
+  return {
+    getToken() {
+      return currentToken;
+    },
+    getPayload() {
+      if (!currentPayload) throw new Error("Omadeus: not authenticated");
+      return currentPayload;
+    },
+    async refresh() {
+      try {
+        await refresh();
+      } catch (err) {
+        onError?.(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+      }
+    },
+    startAutoRefresh() {
+      scheduleNextRefresh();
+    },
+    stopAutoRefresh() {
+      if (refreshTimer) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+      }
+    },
+    needsRefresh() {
+      return !currentToken || shouldRefreshToken(currentToken);
+    },
+  };
+}