@brantrusnak/openclaw-omadeus 1.0.0

package/src/config.ts

@@ -0,0 +1,80 @@
+import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "../runtime-api.js";
+import { OMADEUS_CAS_URL, OMADEUS_MAESTRO_URL } from "./defaults.js";
+import type { OmadeusChannelConfig, ResolvedOmadeusAccount } from "./types.js";
+
+export function getOmadeusChannelConfig(cfg: OpenClawConfig): OmadeusChannelConfig | undefined {
+  return (cfg.channels as Record<string, unknown> | undefined)?.["omadeus"] as
+    | OmadeusChannelConfig
+    | undefined;
+}
+
+export function listOmadeusAccountIds(cfg: OpenClawConfig): string[] {
+  const section = getOmadeusChannelConfig(cfg);
+  if (!section && !resolveOmadeusEnvCredentials()) return [];
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultOmadeusAccountId(_cfg: OpenClawConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveOmadeusAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedOmadeusAccount {
+  const { cfg } = params;
+  const section = getOmadeusChannelConfig(cfg) ?? {};
+  const envCredentials = resolveOmadeusEnvCredentials();
+  const email = section.email?.trim() || envCredentials?.email || "";
+  const password = section.password?.trim() || envCredentials?.password || "";
+  const orgId = section.organizationId ?? envCredentials?.organizationId;
+  const sessionToken = section.sessionToken?.trim() ?? "";
+  const hasCredentials = Boolean(email && password && orgId);
+  const hasSessionToken = Boolean(sessionToken);
+  const hasConfigCredentials = Boolean(
+    section.email?.trim() && section.password?.trim() && section.organizationId,
+  );
+  const credentialSource = hasConfigCredentials
+    ? "config"
+    : hasCredentials
+      ? "env"
+      : hasSessionToken
+        ? "session"
+        : "none";
+
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    name: "Omadeus",
+    enabled: section.enabled !== false,
+    config: section,
+    casUrl: section.casUrl?.trim() || OMADEUS_CAS_URL,
+    maestroUrl: section.maestroUrl?.trim() || OMADEUS_MAESTRO_URL,
+    email,
+    password,
+    organizationId: orgId ?? 0,
+    ...(hasSessionToken ? { sessionToken } : {}),
+    credentialSource,
+  };
+}
+
+function resolveOmadeusEnvCredentials():
+  | {
+      email: string;
+      password: string;
+      organizationId: number;
+    }
+  | undefined {
+  const email = process.env.OMADEUS_EMAIL?.trim();
+  const password = process.env.OMADEUS_PASSWORD?.trim();
+  const organizationIdRaw = process.env.OMADEUS_ORGANIZATION_ID?.trim();
+  if (!email || !password || !organizationIdRaw || !/^\d+$/.test(organizationIdRaw)) {
+    return undefined;
+  }
+  return {
+    email,
+    password,
+    organizationId: Number(organizationIdRaw),
+  };
+}
+
+/** Whether messages from the authenticated user should be ignored. */

package/src/defaults.ts

@@ -0,0 +1,2 @@
+export const OMADEUS_CAS_URL = "https://dev1-cas.rouztech.com";
+export const OMADEUS_MAESTRO_URL = "https://dev3-maestro.rouztech.com";

package/src/inbound.ts

@@ -0,0 +1,112 @@
+import type {
+  OmadeusInboundMessage,
+  OmadeusMessage,
+  OmadeusMessageDetails,
+} from "./types.js";
+
+type Log = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  debug?: (msg: string) => void;
+};
+
+const USER_REF_PATTERN = /\{user_reference_id:(\d+)\}/g;
+const BOLD_MENTION_PREFIX_PATTERN = /^\*\*@[^*]+\*\*/;
+
+/**
+ * Parse the `details` JSON string to extract the rawMessage with mention
+ * template tokens like `{user_reference_id:87}`.
+ */
+function parseDetails(raw: string | null): OmadeusMessageDetails | null {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as OmadeusMessageDetails;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether the bot user (by referenceId) is @-mentioned in the message.
+ * Omadeus encodes mentions as `{user_reference_id:N}` in details.rawMessage.
+ */
+function isBotMentioned(details: OmadeusMessageDetails | null, selfReferenceId: number): boolean {
+  const raw = details?.rawMessage;
+  if (!raw) return false;
+  for (const match of raw.matchAll(USER_REF_PATTERN)) {
+    if (Number(match[1]) === selfReferenceId) return true;
+  }
+  return false;
+}
+
+/**
+ * Fallback mention detection when details.rawMessage is absent.
+ * Omadeus often prefixes mentioned messages with `**@Display Name** ...`.
+ */
+function hasMentionPrefixInBody(body: string): boolean {
+  return BOLD_MENTION_PREFIX_PATTERN.test(body.trim());
+}
+
+/**
+ * Strip the formatted @mention from the body so the agent sees clean text.
+ * The body contains `**@Display Name** actual text`; this strips the bold
+ * mention prefix when it appears at the start.
+ */
+function stripLeadingMention(body: string): string {
+  return body.replace(/^\*\*@[^*]+\*\*\s*/, "").trim();
+}
+
+/**
+ * Determine whether a raw Jaguar socket payload is an OmadeusMessage.
+ */
+export function isOmadeusMessage(data: unknown): data is OmadeusMessage {
+  if (typeof data !== "object" || data === null) return false;
+  const obj = data as Record<string, unknown>;
+  return obj.type === "message" && typeof obj.roomId === "number" && typeof obj.body === "string";
+}
+
+/**
+ * Parse a Jaguar socket message into an OpenClaw inbound message.
+ *
+ * Returns null when:
+ * - The event is not a chat message
+ * - The body is empty or the message was removed
+ */
+export function parseJaguarMessage(
+  msg: OmadeusMessage,
+  opts: {
+    selfReferenceId: number;
+  },
+  log?: Log,
+): OmadeusInboundMessage | null {
+  if (msg.type !== "message") {
+    log?.debug?.(`[jaguar-inbound] ignoring type: ${msg.type}`);
+    return null;
+  }
+
+  if (msg.removedAt) return null;
+
+  const body = (msg.body ?? "").trim();
+  if (!body) return null;
+
+  const details = parseDetails(msg.details);
+  const mentioned = isBotMentioned(details, opts.selfReferenceId) || hasMentionPrefixInBody(body);
+  const content = mentioned ? stripLeadingMention(body) : body;
+
+  if (!content) return null;
+
+  return {
+    messageId: msg.id,
+    from: String(msg.senderReferenceId),
+    fromReferenceId: msg.senderReferenceId,
+    content,
+    roomId: msg.roomId,
+    roomName: msg.roomName,
+    subscribableType: msg.subscribableType,
+    subscribableKind: msg.subscribableKind,
+    isMention: mentioned,
+    timestamp: msg.createdAtTimestamp
+      ? Math.floor(msg.createdAtTimestamp * 1000)
+      : Date.now(),
+  };
+}

package/src/message-handler.ts

@@ -0,0 +1,357 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  logInboundDrop,
+  resolveControlCommandGate,
+  type OpenClawConfig,
+  type RuntimeEnv,
+} from "../runtime-api.js";
+import { createNugget, resolveTaskChannelRoomId, searchNuggetByNumber } from "./api/nugget.api.js";
+import {
+  appendNuggetLookupContextForAgent,
+  parseChannelTaskCreateIntent,
+  parseNuggetLookupIntent,
+  parseRecurringScheduleIntent,
+} from "./nugget-lookup.js";
+import type { OutboundDeps } from "./outbound.js";
+import { createOmadeusReplyDispatcher } from "./reply-dispatcher.js";
+import { getOmadeusChannelConfig } from "./config.js";
+import { getOmadeusRuntime } from "./runtime.js";
+import type { OmadeusInboundMessage } from "./types.js";
+
+type Log = {
+  info: (msg: string, extra?: Record<string, unknown>) => void;
+  warn: (msg: string, extra?: Record<string, unknown>) => void;
+  error: (msg: string, extra?: Record<string, unknown>) => void;
+  debug?: (msg: string, extra?: Record<string, unknown>) => void;
+};
+
+export type OmadeusMessageHandlerDeps = {
+  cfg: OpenClawConfig;
+  runtime: RuntimeEnv;
+  log: Log;
+  outboundDeps: OutboundDeps;
+};
+
+export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
+  const { cfg, runtime, log, outboundDeps } = deps;
+  const core = getOmadeusRuntime();
+  const omadeusCfg = getOmadeusChannelConfig(cfg);
+
+  const inboundDebounceMs = core.channel.debounce.resolveInboundDebounceMs({
+    cfg,
+    channel: "omadeus",
+  });
+
+  const handleMessageNow = async (inbound: OmadeusInboundMessage) => {
+    const isDirectMessage = inbound.subscribableKind === "direct";
+    const senderId = String(inbound.fromReferenceId);
+    const senderName = inbound.from;
+    const roomId = String(inbound.roomId);
+    const rawBody = inbound.content;
+
+    if (!rawBody.trim()) {
+      log.debug?.("skipping empty message");
+      return;
+    }
+
+    const selectedPublicRoomId = omadeusCfg?.selectedChannelPublicRoomId;
+    const selectedPrivateRoomId = omadeusCfg?.selectedChannelPrivateRoomId;
+    const selectedMemberReferenceId = omadeusCfg?.selectedMemberReferenceId;
+    const hasSelectedScope =
+      typeof selectedPublicRoomId === "number" || typeof selectedPrivateRoomId === "number";
+    let inSelectedChannelRoom = false;
+    let isSelectedMemberTaskPrivate = false;
+    if (hasSelectedScope) {
+      inSelectedChannelRoom =
+        inbound.roomId === selectedPublicRoomId || inbound.roomId === selectedPrivateRoomId;
+      const isSelectedMember =
+        typeof selectedMemberReferenceId !== "number" ||
+        inbound.fromReferenceId === selectedMemberReferenceId;
+      isSelectedMemberTaskPrivate =
+        inbound.subscribableKind === "task" && inbound.isMention && isSelectedMember;
+      const allowSelectedChannelMessage = inSelectedChannelRoom && isSelectedMember;
+      if (!allowSelectedChannelMessage && !isSelectedMemberTaskPrivate) {
+        log.info("omadeus: dropped message outside selected channel scope", {
+          roomId: inbound.roomId,
+          roomName: inbound.roomName,
+          selectedPublicRoomId,
+          selectedPrivateRoomId,
+          selectedMemberReferenceId,
+          kind: inbound.subscribableKind,
+          fromReferenceId: inbound.fromReferenceId,
+          isMention: inbound.isMention,
+          selectedMemberMatched: isSelectedMember,
+        });
+        return;
+      }
+    }
+
+    const useAccessGroups =
+      (cfg.commands as Record<string, unknown> | undefined)?.useAccessGroups !== false;
+
+    // For group messages, only respond when mentioned (unless groupPolicy is open)
+    const bypassMentionGate = hasSelectedScope && (inSelectedChannelRoom || isSelectedMemberTaskPrivate);
+    if (!isDirectMessage && !inbound.isMention && !bypassMentionGate) {
+      log.debug?.("skipping group message (not mentioned)");
+      return;
+    }
+    if (!isDirectMessage && !inbound.isMention && bypassMentionGate) {
+      log.info("omadeus: processing selected-scope group message without mention", {
+        roomId: inbound.roomId,
+        roomName: inbound.roomName,
+        kind: inbound.subscribableKind,
+      });
+    }
+
+    const hasControlCommand = core.channel.text.hasControlCommand(rawBody, cfg);
+    const commandGate = resolveControlCommandGate({
+      useAccessGroups,
+      authorizers: [],
+      allowTextCommands: true,
+      hasControlCommand,
+    });
+
+    if (commandGate.shouldBlock) {
+      logInboundDrop({
+        log: (msg) => log.debug?.(msg),
+        channel: "omadeus",
+        reason: "control command (unauthorized)",
+        target: senderId,
+      });
+      return;
+    }
+
+    let bodyForAgent = rawBody;
+    const createIntent = parseChannelTaskCreateIntent(rawBody);
+    if (createIntent) {
+      try {
+        const memberReferenceId =
+          typeof selectedMemberReferenceId === "number"
+            ? selectedMemberReferenceId
+            : inbound.fromReferenceId;
+        const created = await createNugget(outboundDeps.apiOpts, {
+          title: createIntent.title,
+          description: createIntent.description,
+          kind: createIntent.kind,
+          priority: createIntent.priority,
+          stage: "Triage",
+          memberReferenceId,
+          clientId: 1,
+          folderId: 1,
+        });
+        const createdLabel =
+          typeof created["number"] === "number"
+            ? `N${created["number"]}`
+            : String(created["id"] ?? "created");
+        const recurring = parseRecurringScheduleIntent(rawBody);
+        if (recurring && typeof created["number"] === "number") {
+          const cronExpr = recurring.everyMinutes === 60 ? "0 * * * *" : `*/${recurring.everyMinutes} * * * *`;
+          const taskRoomId = resolveTaskChannelRoomId(created);
+          const taskTarget = taskRoomId ? `room:${taskRoomId}` : `N${created["number"]}`;
+          bodyForAgent =
+            `${rawBody}\n\n` +
+            `[Omadeus create] Created ${createIntent.kind} ${createdLabel}.\n` +
+            `[Scheduling required] The user asked for recurring execution.\n` +
+            `You MUST use the cron tool now (no simulation) to add a job with:\n` +
+            `- schedule.kind: "cron"\n` +
+            `- schedule.expr: "${cronExpr}"\n` +
+            `- payload.kind: "agentTurn"\n` +
+            `- payload.message: "${createIntent.description}"\n` +
+            `- payload.deliver: true\n` +
+            `- payload.channel: "omadeus"\n` +
+            `- payload.to: "${taskTarget}"\n` +
+            `- sessionTarget: "isolated"\n` +
+            `- delivery.mode: "announce"\n` +
+            `- delivery.channel: "omadeus"\n` +
+            `- delivery.to: "${taskTarget}"\n` +
+            `Do NOT deliver to the current selected channel; delivery must go only to the created task private channel target above.\n` +
+            `Then confirm cron job creation to the user.`;
+        } else {
+          bodyForAgent = `${rawBody}\n\n[Omadeus create] Created ${createIntent.kind} ${createdLabel}.`;
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        runtime.error?.(`omadeus channel-triggered task create failed: ${errorMessage}`);
+      }
+    }
+
+    const nuggetIntent = parseNuggetLookupIntent(rawBody);
+    if (nuggetIntent) {
+      try {
+        const nugget = await searchNuggetByNumber(outboundDeps.apiOpts, {
+          nuggetNumber: nuggetIntent.nuggetNumber,
+        });
+        bodyForAgent = appendNuggetLookupContextForAgent(
+          rawBody,
+          nuggetIntent.nuggetNumber,
+          nugget,
+        );
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        runtime.error?.(`omadeus nugget lookup failed: ${errorMessage}`);
+        bodyForAgent = appendNuggetLookupContextForAgent(
+          rawBody,
+          nuggetIntent.nuggetNumber,
+          null,
+          errorMessage,
+        );
+      }
+    }
+
+    const omadeusFrom = isDirectMessage ? `omadeus:${senderId}` : `omadeus:group:${roomId}`;
+    const omadeusTo = isDirectMessage ? `room:${roomId}` : `room:${roomId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "omadeus",
+      peer: {
+        kind: isDirectMessage ? "direct" : "group",
+        id: isDirectMessage ? senderId : roomId,
+      },
+    });
+
+    const preview = rawBody.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel = isDirectMessage
+      ? `Omadeus DM from ${senderName}`
+      : `Omadeus message in ${inbound.subscribableKind}/${inbound.roomName ?? roomId} from ${senderName}`;
+
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `omadeus:message:${roomId}:${inbound.timestamp}`,
+    });
+
+    const envelopeFrom = isDirectMessage ? senderName : (inbound.roomName ?? roomId);
+    const storePath = core.channel.session.resolveStorePath(
+      (cfg.session as Record<string, unknown> | undefined)?.store as string | undefined,
+      { agentId: route.agentId },
+    );
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+    const timestamp = inbound.timestamp ? new Date(inbound.timestamp) : undefined;
+    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+      storePath,
+      sessionKey: route.sessionKey,
+    });
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "Omadeus",
+      from: envelopeFrom,
+      timestamp,
+      previousTimestamp,
+      envelope: envelopeOptions,
+      body: rawBody,
+    });
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: bodyForAgent,
+      RawBody: rawBody,
+      CommandBody: rawBody.trim(),
+      BodyForCommands: rawBody.trim(),
+      /** Lets the message tool default `react` / `edit` to this Jaguar message id. */
+      MessageSid: String(inbound.messageId),
+      From: omadeusFrom,
+      To: omadeusTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: isDirectMessage ? "direct" : "group",
+      ConversationLabel: envelopeFrom,
+      GroupSubject: !isDirectMessage ? (inbound.roomName ?? inbound.subscribableKind) : undefined,
+      SenderName: senderName,
+      SenderId: senderId,
+      Provider: "omadeus" as const,
+      Surface: "omadeus" as const,
+      Timestamp: inbound.timestamp ?? Date.now(),
+      WasMentioned: isDirectMessage || inbound.isMention,
+      CommandAuthorized: commandGate.commandAuthorized,
+      OriginatingChannel: "omadeus" as const,
+      OriginatingTo: omadeusTo,
+    });
+
+    await core.channel.session.recordInboundSession({
+      storePath,
+      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      ctx: ctxPayload,
+      onRecordError: (err) => {
+        log.debug?.(`omadeus: failed updating session meta: ${String(err)}`);
+      },
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createOmadeusReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      accountId: route.accountId,
+      runtime,
+      log,
+      outboundDeps,
+      roomId,
+    });
+
+    log.info("dispatching to agent", { sessionKey: route.sessionKey });
+    try {
+      const { queuedFinal, counts } = await core.channel.reply.withReplyDispatcher({
+        dispatcher,
+        onSettled: () => {
+          markDispatchIdle();
+        },
+        run: () =>
+          core.channel.reply.dispatchReplyFromConfig({
+            ctx: ctxPayload,
+            cfg,
+            dispatcher,
+            replyOptions,
+          }),
+      });
+
+      log.info("dispatch complete", { queuedFinal, counts });
+      const finalCount = counts.final;
+      if (queuedFinal) {
+        log.debug?.(
+          `omadeus: delivered ${finalCount} repl${finalCount === 1 ? "y" : "ies"} to room ${roomId}`,
+        );
+      }
+    } catch (err) {
+      log.error("dispatch failed", { error: String(err) });
+      runtime.error?.(`omadeus dispatch failed: ${String(err)}`);
+    }
+  };
+
+  const inboundDebouncer = core.channel.debounce.createInboundDebouncer<OmadeusInboundMessage>({
+    debounceMs: inboundDebounceMs,
+    buildKey: (entry) => {
+      return `omadeus:${entry.roomId}:${entry.fromReferenceId}`;
+    },
+    shouldDebounce: (entry) => {
+      if (!entry.content.trim()) return false;
+      return !core.channel.text.hasControlCommand(entry.content, cfg);
+    },
+    onFlush: async (entries) => {
+      const last = entries.at(-1);
+      if (!last) return;
+
+      if (entries.length === 1) {
+        await handleMessageNow(last);
+        return;
+      }
+
+      // Combine debounced messages into a single inbound
+      const combinedContent = entries
+        .map((e) => e.content)
+        .filter(Boolean)
+        .join("\n");
+      if (!combinedContent.trim()) return;
+
+      await handleMessageNow({
+        ...last,
+        content: combinedContent,
+        isMention: entries.some((e) => e.isMention),
+      });
+    },
+    onError: (err) => {
+      runtime.error?.(`omadeus debounce flush failed: ${String(err)}`);
+    },
+  });
+
+  return async function handleOmadeusMessage(inbound: OmadeusInboundMessage) {
+    await inboundDebouncer.enqueue(inbound);
+  };
+}