@brantrusnak/openclaw-omadeus 1.0.0 → 1.0.2

package/src/nugget-lookup.ts

@@ -1,3 +1,7 @@
+import { readNuggetNumber } from "./api/nugget.api.js";
+import { mergePeopleIntoNuggetAgentPayload } from "./member-resolve.js";
+import type { OmadeusApiOptions } from "./utils/http.util.js";
+
 export type NuggetLookupIntent = {
   /** Display nugget number from `N###` (maps to API `number`, not internal `id`). */
   nuggetNumber: number;
@@ -150,6 +154,13 @@ const NUGGET_FIELDS_FOR_AGENT = [
   "releaseNumber",
   "publicRoomId",
   "privateRoomId",
+  "memberReferenceId",
+  "assigneeReferenceId",
+  "ownerReferenceId",
+  "memberFirstName",
+  "memberLastName",
+  "assigneeFirstName",
+  "assigneeLastName",
 ] as const;
 
 export function pickNuggetFieldsForAgent(record: Record<string, unknown>): Record<string, unknown> {
@@ -162,16 +173,31 @@ export function pickNuggetFieldsForAgent(record: Record<string, unknown>): Recor
   return out;
 }
 
+/**
+ * Picked Dolphin fields + `people` map (referenceId → display name) for the organization.
+ */
+export async function buildNuggetAgentDataPayload(
+  apiOpts: OmadeusApiOptions,
+  fullRecord: Record<string, unknown> | null,
+): Promise<Record<string, unknown> | null> {
+  if (!fullRecord) {
+    return null;
+  }
+  const base = pickNuggetFieldsForAgent(fullRecord);
+  return mergePeopleIntoNuggetAgentPayload(apiOpts, fullRecord, base);
+}
+
 /**
  * Augments the user message so the agent receives Dolphin nugget/task data and can reply with a summary.
  * On miss or API error, the agent still gets instructions to respond helpfully.
  */
-export function appendNuggetLookupContextForAgent(
+export async function appendNuggetLookupContextForAgent(
   rawBody: string,
   nuggetNumber: number,
   record: Record<string, unknown> | null,
+  apiOpts: OmadeusApiOptions,
   fetchError?: string,
-): string {
+): Promise<string> {
   const header = `[Omadeus nugget/task N${nuggetNumber}]`;
 
   if (fetchError) {
@@ -188,9 +214,46 @@ export function appendNuggetLookupContextForAgent(
     );
   }
 
-  const payload = pickNuggetFieldsForAgent(record);
+  const payload = (await buildNuggetAgentDataPayload(apiOpts, record)) ?? pickNuggetFieldsForAgent(record);
+  return (
+    `${rawBody}\n\n${header} Data from Omadeus (summarize for someone tracking this work — status, ownership, timeline, project; plain language. **For assignees and anyone in \`people\` / \`*FirstName\` fields, use those names; never read raw *ReferenceId numbers to the user as a person.**):\n` +
+    `${JSON.stringify(payload, null, 2)}`
+  );
+}
+
+/**
+ * Enriches a Task or Nugget **Jaguar room** with Dolphin data matched by this chat's `roomId`, so the
+ * agent can answer "status" without a bare `N###` in the message.
+ */
+export async function appendNuggetContextForTaskOrNuggetRoom(
+  rawBody: string,
+  roomId: number,
+  roomName: string | null,
+  record: Record<string, unknown> | null,
+  apiOpts: OmadeusApiOptions,
+  fetchError?: string,
+): Promise<string> {
+  const roomLabel = roomName?.trim() ? `room ${roomId} ("${roomName.trim()}")` : `room ${roomId}`;
+
+  if (fetchError) {
+    return (
+      `${rawBody}\n\n[Omadeus, this task/nugget ${roomLabel}] Lookup failed: ${fetchError}.\n` +
+      `Answer from this thread. Do not tell the user to "use the Omadeus platform" or similar — give a direct reply or a concrete next step.`
+    );
+  }
+
+  if (!record) {
+    return (
+      `${rawBody}\n\n[Omadeus, this task/nugget ${roomLabel}] No Dolphin row matched this room id in search yet.\n` +
+      `Answer from the conversation; be honest if you cannot see live fields. Do not hand-wave to "the platform".`
+    );
+  }
+
+  const n = readNuggetNumber(record);
+  const nLabel = n !== undefined ? `N${n}` : "nugget";
+  const payload = (await buildNuggetAgentDataPayload(apiOpts, record)) ?? pickNuggetFieldsForAgent(record);
   return (
-    `${rawBody}\n\n${header} Data from Omadeus (summarize for someone tracking this work — status, ownership, timeline, project; plain language):\n` +
+    `${rawBody}\n\n[Omadeus ${nLabel} for this chat room] The following is live task/nugget data — **answer the user with this** (stage, status, title, who, due date; plain language. **For assignee/owner, use \`people\` and name fields; never recite *ReferenceId numbers (e.g. 210) as a person's name.**). \`task/...\` in the UI is not an OpenClaw session key.\n` +
     `${JSON.stringify(payload, null, 2)}`
   );
 }

package/src/onboarding.ts

@@ -1,25 +1,58 @@
 import type { ChannelSetupWizard, OpenClawConfig, WizardPrompter } from "openclaw/plugin-sdk/setup";
-import { DEFAULT_ACCOUNT_ID, formatDocsLink } from "openclaw/plugin-sdk/setup";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
 import {
-  listMemberChannelViews,
   listOrganizationMembers,
   listOrganizations,
 } from "./api/auth.api.js";
+import { listMemberChannelViews } from "./api/channel.api.js";
 import { authenticate } from "./auth.js";
 import { getOmadeusChannelConfig, resolveOmadeusAccount } from "./config.js";
 import { OMADEUS_CAS_URL, OMADEUS_MAESTRO_URL } from "./defaults.js";
 import type {
   OmadeusChannelConfig,
   OmadeusChannelView,
+  OmadeusInboundEntityKind,
   OmadeusOrganizationMember,
 } from "./types.js";
 
 const channel = "omadeus" as const;
+const DONE = "__done__";
+const ALL_ENTITY_KINDS: OmadeusInboundEntityKind[] = [
+  "task",
+  "nugget",
+  "project",
+  "release",
+  "sprint",
+  "summary",
+  "client",
+  "folder",
+];
 
 type CoreConfig = OpenClawConfig & {
   channels?: { omadeus?: OmadeusChannelConfig };
 };
 
+type SelectOption = {
+  value: string;
+  label: string;
+  hint?: string;
+};
+
+type MultiSelectPrompter = {
+  multiSelect?: (args: {
+    message: string;
+    options: SelectOption[];
+    initialValues?: string[];
+    initialValue?: string[];
+  }) => Promise<string[]>;
+  multiselect?: (args: {
+    message: string;
+    options: SelectOption[];
+    initialValues?: string[];
+    initialValue?: string[];
+  }) => Promise<string[]>;
+};
+
 function getOmadeusSection(cfg: OpenClawConfig): OmadeusChannelConfig | undefined {
   return getOmadeusChannelConfig(cfg as CoreConfig);
 }
@@ -34,7 +67,6 @@ async function noteOmadeusAuthHelp(prompter: WizardPrompter): Promise<void> {
       `CAS URL: ${OMADEUS_CAS_URL}`,
       `Maestro URL: ${OMADEUS_MAESTRO_URL}`,
       "Env vars supported: OMADEUS_EMAIL, OMADEUS_PASSWORD, OMADEUS_ORGANIZATION_ID.",
-      `Docs: ${formatDocsLink("/channels/omadeus", "omadeus")}`,
     ].join("\n"),
     "Omadeus setup",
   );
@@ -97,14 +129,9 @@ async function promptChannelSelection(params: {
   maestroUrl: string;
   sessionToken: string;
   memberReferenceId: number;
-  existing?: OmadeusChannelConfig;
-}): Promise<{
-  selectedChannelViewId: number;
-  selectedChannelTitle: string;
-  selectedChannelPrivateRoomId?: number;
-  selectedChannelPublicRoomId?: number;
-}> {
-  const { prompter, maestroUrl, sessionToken, memberReferenceId, existing } = params;
+  existingChannelViewIds?: number[];
+}): Promise<OmadeusChannelView[]> {
+  const { prompter, maestroUrl, sessionToken, memberReferenceId, existingChannelViewIds } = params;
   const channels = await listMemberChannelViews({
     maestroUrl,
     sessionToken,
@@ -115,31 +142,26 @@ async function promptChannelSelection(params: {
   if (channels.length === 0) {
     throw new Error("No channels found for this account.");
   }
-  const selected = await prompter.select({
-    message: "Which channel to use?",
+  const selected = await promptMultiSelect({
+    prompter,
+    message: "Which channels should OpenClaw listen to?",
     options: channels.map((item) => ({
       value: String(item.id),
       label: item.title || `Channel ${item.id}`,
+      hint: [item.privateRoomId ? `private:${item.privateRoomId}` : undefined, item.publicRoomId ? `public:${item.publicRoomId}` : undefined]
+        .filter(Boolean)
+        .join(" | "),
     })),
-    initialValue:
-      existing?.selectedChannelViewId !== undefined
-        ? String(existing.selectedChannelViewId)
-        : String(channels[0]!.id),
+    initialValues:
+      existingChannelViewIds && existingChannelViewIds.length > 0
+        ? existingChannelViewIds.map(String)
+        : [String(channels[0]!.id)],
   });
-  const chosen = channels.find((item) => String(item.id) === String(selected));
-  if (!chosen) {
-    throw new Error("Selected channel was not found.");
+  const chosen = channels.filter((item) => selected.includes(String(item.id)));
+  if (chosen.length === 0) {
+    throw new Error("At least one channel must be selected.");
   }
-  return {
-    selectedChannelViewId: chosen.id,
-    selectedChannelTitle: chosen.title,
-    ...(typeof chosen.privateRoomId === "number"
-      ? { selectedChannelPrivateRoomId: chosen.privateRoomId }
-      : {}),
-    ...(typeof chosen.publicRoomId === "number"
-      ? { selectedChannelPublicRoomId: chosen.publicRoomId }
-      : {}),
-  };
+  return chosen;
 }
 
 function memberLabel(member: OmadeusOrganizationMember): string {
@@ -162,93 +184,129 @@ function memberHint(member: OmadeusOrganizationMember): string | undefined {
   return parts.length > 0 ? parts.join(" | ") : undefined;
 }
 
-function filterMembersByQuery(
-  members: OmadeusOrganizationMember[],
-  query: string,
-): OmadeusOrganizationMember[] {
-  const q = query.trim().toLowerCase();
-  if (!q) {
-    return members;
+async function promptMultiSelect(params: {
+  prompter: WizardPrompter;
+  message: string;
+  options: SelectOption[];
+  initialValues?: string[];
+}): Promise<string[]> {
+  const multi = params.prompter as unknown as MultiSelectPrompter;
+  const runMulti = multi.multiSelect ?? multi.multiselect;
+  if (runMulti) {
+    return runMulti({
+      message: params.message,
+      options: params.options,
+      initialValues: params.initialValues,
+      initialValue: params.initialValues,
+    });
+  }
+
+  const selected = new Set(params.initialValues ?? []);
+  while (true) {
+    const next = await params.prompter.select({
+      message: `${params.message} (${selected.size} selected)`,
+      options: [
+        { value: DONE, label: selected.size > 0 ? "Done" : "Done (select none)" },
+        ...params.options.map((option) => ({
+          ...option,
+          label: selected.has(option.value) ? `[selected] ${option.label}` : option.label,
+        })),
+      ],
+      initialValue: DONE,
+    });
+    const value = String(next);
+    if (value === DONE) {
+      return [...selected];
+    }
+    if (selected.has(value)) {
+      selected.delete(value);
+    } else {
+      selected.add(value);
+    }
   }
-  return members.filter((member) => {
-    const fields = [
-      String(member.referenceId),
-      member.title ?? "",
-      member.firstName ?? "",
-      member.lastName ?? "",
-      member.email ?? "",
-    ].map((value) => value.toLowerCase());
-    return fields.some((value) => value.includes(q));
-  });
 }
 
-async function promptMemberSelection(params: {
-  prompter: WizardPrompter;
+async function loadSelectableMembers(params: {
   maestroUrl: string;
   sessionToken: string;
   organizationId: number;
-  existingMemberReferenceId?: number;
-  fallbackMemberReferenceId?: number;
-}): Promise<{ memberReferenceId: number; memberTitle: string }> {
-  const {
-    prompter,
-    maestroUrl,
-    sessionToken,
-    organizationId,
-    existingMemberReferenceId,
-    fallbackMemberReferenceId,
-  } = params;
-
-  const members = (
+  excludeReferenceIds?: number[];
+}): Promise<OmadeusOrganizationMember[]> {
+  const excluded = new Set(params.excludeReferenceIds ?? []);
+  return (
     await listOrganizationMembers({
-      maestroUrl,
-      sessionToken,
-      organizationId,
+      maestroUrl: params.maestroUrl,
+      sessionToken: params.sessionToken,
+      organizationId: params.organizationId,
     })
   )
-    .filter((member) => member.isSystem !== true)
+    .filter((member) => member.isSystem !== true && !excluded.has(member.referenceId))
     .sort((a, b) => memberLabel(a).localeCompare(memberLabel(b)));
+}
 
+function memberOptions(members: OmadeusOrganizationMember[]): SelectOption[] {
+  return members.map((member) => ({
+    value: String(member.referenceId),
+    label: memberLabel(member),
+    hint: memberHint(member),
+  }));
+}
+
+function readReferenceIds(values: string[]): number[] {
+  return values
+    .map((value) => Number(value))
+    .filter((value) => Number.isInteger(value) && value > 0);
+}
+
+async function promptSenderAllowlist(params: {
+  prompter: WizardPrompter;
+  message: string;
+  members: OmadeusOrganizationMember[];
+  existingReferenceIds?: number[];
+}): Promise<number[] | undefined> {
+  const { prompter, message, members, existingReferenceIds } = params;
   if (members.length === 0) {
     throw new Error("No organization members found.");
   }
 
-  while (true) {
-    const query = String(
-      await prompter.text({
-        message: "Search member to listen to (name/title/email/referenceId, optional)",
-        placeholder: "e.g. John Doe",
-      }),
-    );
-    const filtered = filterMembersByQuery(members, query).slice(0, 100);
-    if (filtered.length === 0) {
-      await prompter.note("No members matched that search. Try another query.", "Omadeus member");
-      continue;
-    }
-
-    const defaultRef = existingMemberReferenceId ?? fallbackMemberReferenceId;
-    const selected = await prompter.select({
-      message: "Which member should OpenClaw listen to?",
-      options: filtered.map((member) => ({
-        value: String(member.referenceId),
-        label: memberLabel(member),
-        hint: memberHint(member),
-      })),
-      initialValue:
-        defaultRef !== undefined && filtered.some((member) => member.referenceId === defaultRef)
-          ? String(defaultRef)
-          : String(filtered[0]!.referenceId),
-    });
-    const chosen = filtered.find((member) => String(member.referenceId) === String(selected));
-    if (!chosen) {
-      await prompter.note("Could not resolve selected member. Please retry.", "Omadeus member");
-      continue;
-    }
-    return {
-      memberReferenceId: chosen.referenceId,
-      memberTitle: memberLabel(chosen),
-    };
+  const mode = await prompter.select({
+    message,
+    options: [
+      { value: "all", label: "All users", hint: "No sender allowlist" },
+      { value: "specific", label: "Specific users", hint: "Select one or more users" },
+    ],
+    initialValue: existingReferenceIds && existingReferenceIds.length > 0 ? "specific" : "all",
+  });
+  if (String(mode) === "all") {
+    return undefined;
   }
+
+  const selected = await promptMultiSelect({
+    prompter,
+    message: `${message} (specific users)`,
+    options: memberOptions(members),
+    initialValues: existingReferenceIds?.map(String),
+  });
+  return readReferenceIds(selected);
+}
+
+async function promptEntityKindSelection(params: {
+  prompter: WizardPrompter;
+  existingKinds?: OmadeusInboundEntityKind[];
+}): Promise<OmadeusInboundEntityKind[]> {
+  const selected = await promptMultiSelect({
+    prompter: params.prompter,
+    message: "Which entity room types should OpenClaw listen to?",
+    options: ALL_ENTITY_KINDS.map((kind) => ({
+      value: kind,
+      label: kind,
+    })),
+    initialValues:
+      params.existingKinds && params.existingKinds.length > 0
+        ? params.existingKinds
+        : ALL_ENTITY_KINDS,
+  });
+  return ALL_ENTITY_KINDS.filter((kind) => selected.includes(kind));
 }
 
 export const omadeusSetupWizard: ChannelSetupWizard = {
@@ -372,26 +430,79 @@ export const omadeusSetupWizard: ChannelSetupWizard = {
       throw new Error("Authentication is required to list channels.");
     }
 
-    const selectedMember = await promptMemberSelection({
-      prompter,
+    if (typeof selfReferenceId !== "number") {
+      throw new Error("Authentication did not return an Omadeus member reference ID.");
+    }
+
+    const members = await loadSelectableMembers({
       maestroUrl,
       sessionToken,
       organizationId,
-      existingMemberReferenceId: section.selectedMemberReferenceId,
-      fallbackMemberReferenceId: selfReferenceId,
+      excludeReferenceIds: [selfReferenceId],
+    });
+    const existingInbound = section.inbound;
+
+    const directSenderIds = await promptSenderAllowlist({
+      prompter,
+      message: "Which users can DM OpenClaw directly?",
+      members,
+      existingReferenceIds: existingInbound?.direct?.allowedSenderReferenceIds,
     });
 
-    const selectedChannel = await promptChannelSelection({
+    const selectedChannels = await promptChannelSelection({
       prompter,
       maestroUrl,
       sessionToken,
-      memberReferenceId: selectedMember.memberReferenceId,
-      existing: section,
+      memberReferenceId: selfReferenceId,
+      existingChannelViewIds: existingInbound?.channels?.allowedChannelViewIds,
     });
 
+    const channelSenderIds = await promptSenderAllowlist({
+      prompter,
+      message: "Which users can trigger OpenClaw from allowed channels?",
+      members,
+      existingReferenceIds: existingInbound?.channels?.allowedSenderReferenceIds,
+    });
+
+    const entityKinds = await promptEntityKindSelection({
+      prompter,
+      existingKinds: existingInbound?.entities?.allowedKinds,
+    });
+
+    const entitySenderIds =
+      entityKinds.length > 0
+        ? await promptSenderAllowlist({
+            prompter,
+            message: "Which users can trigger OpenClaw from entity rooms?",
+            members,
+            existingReferenceIds: existingInbound?.entities?.allowedSenderReferenceIds,
+          })
+        : undefined;
+
+    const channelRoomIds = selectedChannels
+      .flatMap((selectedChannel) => [
+        selectedChannel.publicRoomId,
+        selectedChannel.privateRoomId,
+      ])
+      .filter((id): id is number => typeof id === "number");
+    const channelViewIds = selectedChannels.map((selectedChannel) => selectedChannel.id);
+    const channelTitles = selectedChannels
+      .map((selectedChannel) => selectedChannel.title || `Channel ${selectedChannel.id}`)
+      .join(", ");
+
+    const senderSummary = (ids: number[] | undefined) =>
+      ids && ids.length > 0 ? ids.join(", ") : "all users";
+    const entityKindSummary =
+      entityKinds.length > 0 ? entityKinds.join(", ") : "none (entity rooms disabled)";
+
     await prompter.note(
-      `Omadeus will process only "${selectedChannel.selectedChannelTitle}" for member ${selectedMember.memberTitle} (${selectedMember.memberReferenceId}), plus task private-chat mentions.`,
-      "Omadeus channel scope",
+      [
+        `Inbound policy (Jaguar chat):`,
+        `- Direct messages: enabled for ${senderSummary(directSenderIds)} (no @mention required).`,
+        `- Channels "${channelTitles}": rooms ${channelRoomIds.join(", ") || "(no room ids)"} from ${senderSummary(channelSenderIds)}; @mention not required in those rooms.`,
+        `- Entity rooms (${entityKindSummary}): ${senderSummary(entitySenderIds)}; @mention required.`,
+      ].join("\n"),
+      "Omadeus inbound policy",
     );
 
     next = {
@@ -399,7 +510,6 @@ export const omadeusSetupWizard: ChannelSetupWizard = {
       channels: {
         ...next.channels,
         omadeus: {
-          ...getOmadeusSection(next),
           enabled: true,
           casUrl,
           maestroUrl,
@@ -407,15 +517,27 @@ export const omadeusSetupWizard: ChannelSetupWizard = {
           password,
           organizationId,
           ...(sessionToken ? { sessionToken } : {}),
-          selectedMemberReferenceId: selectedMember.memberReferenceId,
-          selectedChannelViewId: selectedChannel.selectedChannelViewId,
-          selectedChannelTitle: selectedChannel.selectedChannelTitle,
-          ...(selectedChannel.selectedChannelPrivateRoomId !== undefined
-            ? { selectedChannelPrivateRoomId: selectedChannel.selectedChannelPrivateRoomId }
-            : {}),
-          ...(selectedChannel.selectedChannelPublicRoomId !== undefined
-            ? { selectedChannelPublicRoomId: selectedChannel.selectedChannelPublicRoomId }
-            : {}),
+          inbound: {
+            version: 1,
+            direct: {
+              enabled: true,
+              ...(directSenderIds ? { allowedSenderReferenceIds: directSenderIds } : {}),
+              requireMention: "never",
+            },
+            channels: {
+              enabled: true,
+              allowedRoomIds: channelRoomIds,
+              allowedChannelViewIds: channelViewIds,
+              ...(channelSenderIds ? { allowedSenderReferenceIds: channelSenderIds } : {}),
+              requireMention: "outsideAllowlist",
+            },
+            entities: {
+              enabled: entityKinds.length > 0,
+              allowedKinds: entityKinds,
+              ...(entitySenderIds ? { allowedSenderReferenceIds: entitySenderIds } : {}),
+              requireMention: "always",
+            },
+          },
         },
       },
     };

package/src/types.ts

@@ -2,6 +2,63 @@
 // Omadeus config shape (stored under channels.omadeus in OpenClaw config)
 // ---------------------------------------------------------------------------
 
+export type OmadeusInboundMentionPolicy = "never" | "always" | "outsideAllowlist";
+
+export type OmadeusInboundDirectPolicy = {
+  enabled: boolean;
+  allowedSenderReferenceIds?: number[];
+  requireMention?: "never" | "always";
+};
+
+export type OmadeusInboundChannelsPolicy = {
+  enabled: boolean;
+  allowedRoomIds?: number[];
+  allowedChannelViewIds?: number[];
+  allowedSenderReferenceIds?: number[];
+  requireMention?: OmadeusInboundMentionPolicy;
+};
+
+/** Jaguar `subscribableKind` values treated as entity chat (not DM, not channel). */
+export type OmadeusInboundEntityKind =
+  | "task"
+  | "nugget"
+  | "project"
+  | "release"
+  | "sprint"
+  | "summary"
+  | "client"
+  | "folder";
+
+/** Jaguar entity chats (`subscribableKind`) — DMs and channel rooms use other values. */
+export const OMADEUS_INBOUND_ENTITY_KINDS: readonly OmadeusInboundEntityKind[] = [
+  "task",
+  "nugget",
+  "project",
+  "release",
+  "sprint",
+  "summary",
+  "client",
+  "folder",
+];
+
+export const OMADEUS_INBOUND_ENTITY_KIND_SET: ReadonlySet<string> = new Set(OMADEUS_INBOUND_ENTITY_KINDS);
+
+export type OmadeusInboundEntitiesPolicy = {
+  enabled: boolean;
+  allowedKinds?: OmadeusInboundEntityKind[];
+  allowedRoomIds?: number[];
+  allowedSenderReferenceIds?: number[];
+  requireMention?: OmadeusInboundMentionPolicy;
+};
+
+/** Jaguar chat ingress policy (DMs, channel rooms, entity rooms). */
+export type OmadeusInboundPolicy = {
+  version?: number;
+  direct?: OmadeusInboundDirectPolicy;
+  channels?: OmadeusInboundChannelsPolicy;
+  entities?: OmadeusInboundEntitiesPolicy;
+};
+
 export type OmadeusChannelConfig = {
   enabled?: boolean;
   casUrl?: string;
@@ -11,13 +68,8 @@ export type OmadeusChannelConfig = {
   organizationId?: number;
   /** Cached Omadeus session JWT obtained during onboarding/startup. */
   sessionToken?: string;
-  /** Selected member reference ID (account) used by onboarding. */
-  selectedMemberReferenceId?: number;
-  /** Selected channel metadata used for inbound filtering. */
-  selectedChannelViewId?: number;
-  selectedChannelTitle?: string;
-  selectedChannelPrivateRoomId?: number;
-  selectedChannelPublicRoomId?: number;
+  /** Jaguar chat ingress allowlists and mention rules. */
+  inbound?: OmadeusInboundPolicy;
 };
 
 export type ResolvedOmadeusAccount = {
@@ -101,6 +153,13 @@ export type OmadeusJwtPayload = {
 // Jaguar socket message (chat — DMs, nugget rooms, task rooms, etc.)
 // ---------------------------------------------------------------------------
 
+/**
+ * Omadeus subscribable **type** on Jaguar chat payloads (room context).
+ *
+ * - **direct** — DM from a user.
+ * - **channel** — message in a channel room.
+ * - **nugget** … **folder** — entity-associated chat (tasks, work items, hierarchy).
+ */
 export type OmadeusSubscribableType =
   | "direct"
   | "channel"
@@ -112,6 +171,15 @@ export type OmadeusSubscribableType =
   | "client"
   | "folder"
   | (string & {});
+
+/**
+ * Omadeus subscribable **kind** on Jaguar chat payloads (same coarse buckets as `OmadeusSubscribableType`;
+ * routing uses `subscribableKind` in the plugin).
+ *
+ * - **direct** — DM from a user.
+ * - **channel** — message in a channel room.
+ * - **task**, **nugget**, **project**, **release**, **sprint**, **summary**, **client**, **folder** — entity chat.
+ */
 export type OmadeusSubscribableKind =
   | "task"
   | "direct"
@@ -181,6 +249,8 @@ export type OmadeusInboundMessage = {
   roomName: string | null;
   subscribableType: OmadeusSubscribableType;
   subscribableKind: OmadeusSubscribableKind;
+  /** When present, used with `inbound.channels.allowedChannelViewIds`. */
+  channelViewId?: number;
   isMention: boolean;
   timestamp: number;
 };