@brantrusnak/openclaw-omadeus 1.0.0 → 1.0.2

package/src/inbound-policy.ts

@@ -0,0 +1,250 @@
+import {
+  type OmadeusChannelConfig,
+  type OmadeusInboundMessage,
+  type OmadeusInboundPolicy,
+  OMADEUS_INBOUND_ENTITY_KIND_SET,
+  type OmadeusSubscribableKind,
+} from "./types.js";
+
+/** Default inbound policy when `channels.omadeus.inbound` is absent. */
+export const DEFAULT_INBOUND_POLICY: Required<
+  Pick<OmadeusInboundPolicy, "direct" | "channels" | "entities">
+> & { version: number } = {
+  version: 1,
+  direct: { enabled: true, requireMention: "never" },
+  channels: { enabled: false, requireMention: "outsideAllowlist" },
+  entities: { enabled: false, requireMention: "always" },
+};
+
+export type InboundPolicyDecision =
+  | { allow: true }
+  | { allow: false; reason: string; details?: Record<string, unknown> };
+
+function mergePolicy(cfg: OmadeusChannelConfig | undefined) {
+  const inbound = cfg?.inbound;
+  const version = typeof inbound?.version === "number" && inbound.version >= 1 ? inbound.version : 1;
+  const direct = {
+    ...DEFAULT_INBOUND_POLICY.direct,
+    ...inbound?.direct,
+    requireMention: inbound?.direct?.requireMention ?? DEFAULT_INBOUND_POLICY.direct.requireMention,
+  };
+  const channels = {
+    ...DEFAULT_INBOUND_POLICY.channels,
+    ...inbound?.channels,
+    requireMention:
+      inbound?.channels?.requireMention ?? DEFAULT_INBOUND_POLICY.channels.requireMention,
+  };
+  const entities = {
+    ...DEFAULT_INBOUND_POLICY.entities,
+    ...inbound?.entities,
+    requireMention:
+      inbound?.entities?.requireMention ?? DEFAULT_INBOUND_POLICY.entities.requireMention,
+  };
+  return { version, direct, channels, entities };
+}
+
+function surfaceForKind(kind: OmadeusSubscribableKind): "direct" | "channel" | "entity" {
+  if (kind === "direct") return "direct";
+  if (kind === "channel") return "channel";
+  return "entity";
+}
+
+function senderAllowed(allowed: number[] | undefined, fromReferenceId: number): boolean {
+  if (!allowed || allowed.length === 0) return true;
+  return allowed.includes(fromReferenceId);
+}
+
+function channelGeoAllowed(params: {
+  roomId: number;
+  channelViewId?: number;
+  allowedRoomIds?: number[];
+  allowedChannelViewIds?: number[];
+}): { geoInAllowlist: boolean; details: Record<string, unknown> } {
+  const { roomId, channelViewId, allowedRoomIds = [], allowedChannelViewIds = [] } = params;
+  const hasRooms = allowedRoomIds.length > 0;
+  const hasViews = allowedChannelViewIds.length > 0;
+  let geoInAllowlist = true;
+  if (hasRooms && hasViews) {
+    geoInAllowlist =
+      allowedRoomIds.includes(roomId) ||
+      (channelViewId !== undefined && allowedChannelViewIds.includes(channelViewId));
+  } else if (hasRooms) {
+    geoInAllowlist = allowedRoomIds.includes(roomId);
+  } else if (hasViews) {
+    geoInAllowlist = channelViewId !== undefined && allowedChannelViewIds.includes(channelViewId);
+  }
+  return {
+    geoInAllowlist,
+    details: {
+      roomId,
+      channelViewId,
+      allowedRoomIds,
+      allowedChannelViewIds,
+      hasRooms,
+      hasViews,
+      geoInAllowlist,
+    },
+  };
+}
+
+function entityKindAllowed(kind: OmadeusSubscribableKind, allowedKinds?: string[]): boolean {
+  if (!allowedKinds || allowedKinds.length === 0) {
+    return OMADEUS_INBOUND_ENTITY_KIND_SET.has(String(kind));
+  }
+  return allowedKinds.includes(String(kind));
+}
+
+function entityRoomOk(roomId: number, allowedRoomIds?: number[]): boolean {
+  if (!allowedRoomIds || allowedRoomIds.length === 0) return true;
+  return allowedRoomIds.includes(roomId);
+}
+
+function mentionRequired(params: {
+  requireMention?: "never" | "always" | "outsideAllowlist";
+  inAllowlist: boolean;
+  isMention: boolean;
+}): boolean {
+  const requireMention = params.requireMention ?? "never";
+  const { inAllowlist, isMention } = params;
+  if (requireMention === "never") return false;
+  if (requireMention === "always") return !isMention;
+  // outsideAllowlist
+  if (inAllowlist) return false;
+  return !isMention;
+}
+
+/**
+ * Evaluate whether a normalized Jaguar inbound should be dispatched to OpenClaw.
+ * Callers must drop self-authored messages separately if they prefer logging there.
+ */
+export function evaluateOmadeusInboundPolicy(params: {
+  inbound: OmadeusInboundMessage;
+  omadeusCfg: OmadeusChannelConfig | undefined;
+  selfReferenceId: number;
+}): InboundPolicyDecision {
+  const { inbound, omadeusCfg, selfReferenceId } = params;
+
+  if (inbound.fromReferenceId === selfReferenceId) {
+    return {
+      allow: false,
+      reason: "self_message",
+      details: { fromReferenceId: inbound.fromReferenceId, selfReferenceId },
+    };
+  }
+
+  const policy = mergePolicy(omadeusCfg);
+  const surface = surfaceForKind(inbound.subscribableKind);
+
+  if (surface === "direct") {
+    if (!policy.direct.enabled) {
+      return { allow: false, reason: "direct_disabled", details: { surface } };
+    }
+    if (!senderAllowed(policy.direct.allowedSenderReferenceIds, inbound.fromReferenceId)) {
+      return {
+        allow: false,
+        reason: "direct_sender_not_allowed",
+        details: { fromReferenceId: inbound.fromReferenceId },
+      };
+    }
+    const req = policy.direct.requireMention ?? "never";
+    if (mentionRequired({ requireMention: req, inAllowlist: true, isMention: inbound.isMention })) {
+      return { allow: false, reason: "direct_mention_required", details: { requireMention: req } };
+    }
+    return { allow: true };
+  }
+
+  if (surface === "channel") {
+    if (!policy.channels.enabled) {
+      return { allow: false, reason: "channels_disabled", details: { surface } };
+    }
+    if (!senderAllowed(policy.channels.allowedSenderReferenceIds, inbound.fromReferenceId)) {
+      return {
+        allow: false,
+        reason: "channel_sender_not_allowed",
+        details: { fromReferenceId: inbound.fromReferenceId },
+      };
+    }
+    const rv = channelGeoAllowed({
+      roomId: inbound.roomId,
+      channelViewId: inbound.channelViewId,
+      allowedRoomIds: policy.channels.allowedRoomIds,
+      allowedChannelViewIds: policy.channels.allowedChannelViewIds,
+    });
+    const senderInList =
+      !policy.channels.allowedSenderReferenceIds ||
+      policy.channels.allowedSenderReferenceIds.length === 0 ||
+      policy.channels.allowedSenderReferenceIds.includes(inbound.fromReferenceId);
+    const inAllowlist = rv.geoInAllowlist && senderInList;
+    const channelMention =
+      policy.channels.requireMention ?? DEFAULT_INBOUND_POLICY.channels.requireMention;
+    if (
+      mentionRequired({
+        requireMention: channelMention,
+        inAllowlist,
+        isMention: inbound.isMention,
+      })
+    ) {
+      return {
+        allow: false,
+        reason: "channel_mention_required",
+        details: {
+          requireMention: channelMention,
+          inAllowlist,
+          isMention: inbound.isMention,
+        },
+      };
+    }
+    return { allow: true };
+  }
+
+  // entity
+  if (!policy.entities.enabled) {
+    return { allow: false, reason: "entities_disabled", details: { kind: inbound.subscribableKind } };
+  }
+  if (!entityKindAllowed(inbound.subscribableKind, policy.entities.allowedKinds)) {
+    return {
+      allow: false,
+      reason: "entity_kind_not_allowed",
+      details: { kind: inbound.subscribableKind, allowedKinds: policy.entities.allowedKinds },
+    };
+  }
+  if (!senderAllowed(policy.entities.allowedSenderReferenceIds, inbound.fromReferenceId)) {
+    return {
+      allow: false,
+      reason: "entity_sender_not_allowed",
+      details: { fromReferenceId: inbound.fromReferenceId },
+    };
+  }
+  if (!entityRoomOk(inbound.roomId, policy.entities.allowedRoomIds)) {
+    return {
+      allow: false,
+      reason: "entity_room_not_allowed",
+      details: { roomId: inbound.roomId, allowedRoomIds: policy.entities.allowedRoomIds },
+    };
+  }
+
+  const roomList = policy.entities.allowedRoomIds ?? [];
+  const inAllowlist =
+    roomList.length === 0 || roomList.includes(inbound.roomId);
+  const entityMention =
+    policy.entities.requireMention ?? DEFAULT_INBOUND_POLICY.entities.requireMention;
+  if (
+    mentionRequired({
+      requireMention: entityMention,
+      inAllowlist,
+      isMention: inbound.isMention,
+    })
+  ) {
+    return {
+      allow: false,
+      reason: "entity_mention_required",
+      details: {
+        requireMention: entityMention,
+        inAllowlist,
+        isMention: inbound.isMention,
+      },
+    };
+  }
+
+  return { allow: true };
+}

package/src/inbound.ts

@@ -56,6 +56,23 @@ function stripLeadingMention(body: string): string {
   return body.replace(/^\*\*@[^*]+\*\*\s*/, "").trim();
 }
 
+function readChannelViewId(metadata: unknown): number | undefined {
+  if (metadata === null || metadata === undefined || typeof metadata !== "object") {
+    return undefined;
+  }
+  const m = metadata as Record<string, unknown>;
+  for (const key of ["channelViewId", "channel_view_id", "viewId", "subscribableViewId"]) {
+    const v = m[key];
+    if (typeof v === "number" && Number.isFinite(v)) {
+      return v;
+    }
+    if (typeof v === "string" && /^\d+$/.test(v.trim())) {
+      return Number(v.trim());
+    }
+  }
+  return undefined;
+}
+
 /**
  * Determine whether a raw Jaguar socket payload is an OmadeusMessage.
  */
@@ -95,6 +112,8 @@ export function parseJaguarMessage(
 
   if (!content) return null;
 
+  const channelViewId = readChannelViewId(msg.metadata);
+
   return {
     messageId: msg.id,
     from: String(msg.senderReferenceId),
@@ -104,6 +123,7 @@ export function parseJaguarMessage(
     roomName: msg.roomName,
     subscribableType: msg.subscribableType,
     subscribableKind: msg.subscribableKind,
+    ...(channelViewId !== undefined ? { channelViewId } : {}),
     isMention: mentioned,
     timestamp: msg.createdAtTimestamp
       ? Math.floor(msg.createdAtTimestamp * 1000)

package/src/member-resolve.ts

@@ -0,0 +1,84 @@
+import { listOrganizationMembers } from "./api/auth.api.js";
+import type { OmadeusOrganizationMember } from "./types.js";
+import type { OmadeusApiOptions } from "./utils/http.util.js";
+
+function formatMemberLabel(m: OmadeusOrganizationMember): string {
+  const fullName = `${m.firstName ?? ""} ${m.lastName ?? ""}`.trim();
+  if (fullName) {
+    return fullName;
+  }
+  if (m.title?.trim()) {
+    return m.title.trim();
+  }
+  if (m.email?.trim()) {
+    return m.email.trim();
+  }
+  return `Member ${m.referenceId}`;
+}
+
+/**
+ * Resolves Omadeus `referenceId` → human-readable label for the current organization (session JWT).
+ * Used so agents do not echo raw ids like 210 to users.
+ */
+export async function buildReferenceIdNameMap(
+  apiOpts: OmadeusApiOptions,
+): Promise<Map<number, string>> {
+  const { organizationId } = apiOpts.tokenManager.getPayload();
+  const sessionToken = apiOpts.tokenManager.getToken();
+  const members = await listOrganizationMembers({
+    maestroUrl: apiOpts.maestroUrl,
+    sessionToken,
+    organizationId,
+  });
+  const map = new Map<number, string>();
+  for (const m of members) {
+    map.set(m.referenceId, formatMemberLabel(m));
+  }
+  return map;
+}
+
+/**
+ * Adds a `people` object mapping each `*ReferenceId` field in the nugget row to a display name.
+ * Keys match the source field names (e.g. `memberReferenceId: "Pat Example"`).
+ */
+export async function mergePeopleIntoNuggetAgentPayload(
+  apiOpts: OmadeusApiOptions,
+  fullRecord: Record<string, unknown>,
+  basePayload: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  let nameByRef: Map<number, string>;
+  try {
+    nameByRef = await buildReferenceIdNameMap(apiOpts);
+  } catch {
+    return { ...basePayload };
+  }
+  const people: Record<string, string> = {};
+  for (const [key, v] of Object.entries(fullRecord)) {
+    if (!/referenceid$/i.test(key)) {
+      continue;
+    }
+    const id =
+      typeof v === "number" && Number.isFinite(v)
+        ? v
+        : typeof v === "string" && /^\d+$/.test(v.trim())
+          ? Number(v.trim())
+          : NaN;
+    if (!Number.isFinite(id)) {
+      continue;
+    }
+    const name = nameByRef.get(id);
+    if (name) {
+      people[key] = name;
+    }
+  }
+  const out: Record<string, unknown> = { ...basePayload };
+  if (Object.keys(people).length > 0) {
+    out.people = people;
+    for (const key of Object.keys(people)) {
+      if (key in out) {
+        delete out[key];
+      }
+    }
+  }
+  return out;
+}

package/src/message-handler.ts

@@ -5,8 +5,9 @@ import {
   type OpenClawConfig,
   type RuntimeEnv,
 } from "../runtime-api.js";
-import { createNugget, resolveTaskChannelRoomId, searchNuggetByNumber } from "./api/nugget.api.js";
+import { createNugget, findNuggetByTaskChannelRoom, resolveTaskChannelRoomId, searchNuggetByNumber } from "./api/nugget.api.js";
 import {
+  appendNuggetContextForTaskOrNuggetRoom,
   appendNuggetLookupContextForAgent,
   parseChannelTaskCreateIntent,
   parseNuggetLookupIntent,
@@ -15,8 +16,12 @@ import {
 import type { OutboundDeps } from "./outbound.js";
 import { createOmadeusReplyDispatcher } from "./reply-dispatcher.js";
 import { getOmadeusChannelConfig } from "./config.js";
+import { evaluateOmadeusInboundPolicy } from "./inbound-policy.js";
 import { getOmadeusRuntime } from "./runtime.js";
-import type { OmadeusInboundMessage } from "./types.js";
+import {
+  type OmadeusInboundMessage,
+  OMADEUS_INBOUND_ENTITY_KIND_SET,
+} from "./types.js";
 
 type Log = {
   info: (msg: string, extra?: Record<string, unknown>) => void;
@@ -25,15 +30,50 @@ type Log = {
   debug?: (msg: string, extra?: Record<string, unknown>) => void;
 };
 
+const SK = "`subscribableKind`";
+
+/** Injected into BodyForAgent so the model uses Jaguar room kind, not invented OpenClaw `task/...` keys. */
+function buildOmadeusEntityRoomContextLine(kind: string): string {
+  if (kind === "task") {
+    return `This chat is an **Omadeus Task** room (${SK} \`task\`). If the user asks about the Task, its status, or says \"the task\", they mean **this** Omadeus Task / this thread — not an OpenClaw \"task\" or a \"session id\" for it.`;
+  }
+  if (kind === "nugget") {
+    return `This chat is an **Omadeus Nugget** room (${SK} \`nugget\`). If the user asks about the Nugget, its status, or colloquially says \"the task\", they mean **this** Omadeus Nugget / this thread — not an OpenClaw \"task\" or a \"session id\" for it. (Task and Nugget are different; infer from this room's ${SK}.)`;
+  }
+  const other: Record<string, string> = {
+    project: "Project",
+    release: "Release",
+    sprint: "Sprint",
+    summary: "Summary",
+    client: "Client",
+    folder: "Folder",
+  };
+  const label = other[kind] ?? kind;
+  return `This chat is an **Omadeus ${label}** room (${SK} \`${kind}\`). User questions refer to that Omadeus ${label} in this thread — not an OpenClaw \"session id\" for it.`;
+}
+
+function shouldSkipTaskRoomNuggetFetch(rawBody: string): boolean {
+  const t = rawBody.trim();
+  if (!t) {
+    return true;
+  }
+  if (/^(ok|k|thanks?|thank you|ty|sounds good|got it|yes|yep|no|nope)\s*!*\.?$/i.test(t)) {
+    return true;
+  }
+  return false;
+}
+
 export type OmadeusMessageHandlerDeps = {
   cfg: OpenClawConfig;
   runtime: RuntimeEnv;
   log: Log;
   outboundDeps: OutboundDeps;
+  /** Authenticated Omadeus user; used to drop self-authored messages and inbound policy. */
+  selfReferenceId: number;
 };
 
 export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
-  const { cfg, runtime, log, outboundDeps } = deps;
+  const { cfg, runtime, log, outboundDeps, selfReferenceId } = deps;
   const core = getOmadeusRuntime();
   const omadeusCfg = getOmadeusChannelConfig(cfg);
 
@@ -54,55 +94,26 @@ export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
       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", {
+    const policyDecision = evaluateOmadeusInboundPolicy({
+      inbound,
+      omadeusCfg,
+      selfReferenceId,
+    });
+    if (!policyDecision.allow) {
+      log.info("omadeus: dropped message by inbound policy", {
+        reason: policyDecision.reason,
+        ...(policyDecision.details ?? {}),
         roomId: inbound.roomId,
-        roomName: inbound.roomName,
         kind: inbound.subscribableKind,
+        fromReferenceId: inbound.fromReferenceId,
+        isMention: inbound.isMention,
       });
+      return;
     }
 
+    const useAccessGroups =
+      (cfg.commands as Record<string, unknown> | undefined)?.useAccessGroups !== false;
+
     const hasControlCommand = core.channel.text.hasControlCommand(rawBody, cfg);
     const commandGate = resolveControlCommandGate({
       useAccessGroups,
@@ -125,10 +136,7 @@ export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
     const createIntent = parseChannelTaskCreateIntent(rawBody);
     if (createIntent) {
       try {
-        const memberReferenceId =
-          typeof selectedMemberReferenceId === "number"
-            ? selectedMemberReferenceId
-            : inbound.fromReferenceId;
+        const memberReferenceId = inbound.fromReferenceId;
         const created = await createNugget(outboundDeps.apiOpts, {
           title: createIntent.title,
           description: createIntent.description,
@@ -181,18 +189,49 @@ export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
         const nugget = await searchNuggetByNumber(outboundDeps.apiOpts, {
           nuggetNumber: nuggetIntent.nuggetNumber,
         });
-        bodyForAgent = appendNuggetLookupContextForAgent(
+        bodyForAgent = await appendNuggetLookupContextForAgent(
           rawBody,
           nuggetIntent.nuggetNumber,
           nugget,
+          outboundDeps.apiOpts,
         );
       } catch (err) {
         const errorMessage = err instanceof Error ? err.message : String(err);
         runtime.error?.(`omadeus nugget lookup failed: ${errorMessage}`);
-        bodyForAgent = appendNuggetLookupContextForAgent(
+        bodyForAgent = await appendNuggetLookupContextForAgent(
           rawBody,
           nuggetIntent.nuggetNumber,
           null,
+          outboundDeps.apiOpts,
+          errorMessage,
+        );
+      }
+    }
+
+    const isTaskOrNuggetRoom =
+      !isDirectMessage && (inbound.subscribableKind === "task" || inbound.subscribableKind === "nugget");
+    if (isTaskOrNuggetRoom && !nuggetIntent && !createIntent && !shouldSkipTaskRoomNuggetFetch(rawBody)) {
+      try {
+        const nugget = await findNuggetByTaskChannelRoom(outboundDeps.apiOpts, {
+          roomId: inbound.roomId,
+          roomName: inbound.roomName,
+        });
+        bodyForAgent = await appendNuggetContextForTaskOrNuggetRoom(
+          bodyForAgent,
+          inbound.roomId,
+          inbound.roomName,
+          nugget,
+          outboundDeps.apiOpts,
+        );
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        runtime.error?.(`omadeus task room nugget lookup failed: ${errorMessage}`);
+        bodyForAgent = await appendNuggetContextForTaskOrNuggetRoom(
+          bodyForAgent,
+          inbound.roomId,
+          inbound.roomName,
+          null,
+          outboundDeps.apiOpts,
           errorMessage,
         );
       }
@@ -210,6 +249,13 @@ export function createOmadeusMessageHandler(deps: OmadeusMessageHandlerDeps) {
       },
     });
 
+    // Omadeus entity rooms (Jaguar subscribableKind): see OmadeusInboundEntityKind,
+    // OMADEUS_INBOUND_ENTITY_KINDS. Models conflate "task" with OpenClaw and invent `task/<title>` keys.
+    if (!isDirectMessage && OMADEUS_INBOUND_ENTITY_KIND_SET.has(String(inbound.subscribableKind))) {
+      const entityLine = buildOmadeusEntityRoomContextLine(String(inbound.subscribableKind));
+      bodyForAgent = `${bodyForAgent}\n\n[OpenClaw] ${entityLine} \`session_status\` is only for **OpenClaw** gateway session state (model/usage, etc.); for that, use this key or \`current\`: ${route.sessionKey} — never \`task/\` + a title as a session key.`;
+    }
+
     const preview = rawBody.replace(/\s+/g, " ").slice(0, 160);
     const inboundLabel = isDirectMessage
       ? `Omadeus DM from ${senderName}`