@brantrusnak/openclaw-omadeus 1.0.2 → 1.0.3

package/dist/src/inbound-policy.js

@@ -0,0 +1,205 @@
+import { OMADEUS_INBOUND_ENTITY_KIND_SET } from "./types.js";
+//#region src/inbound-policy.ts
+/** Default inbound policy when `channels.omadeus.inbound` is absent. */
+const DEFAULT_INBOUND_POLICY = {
+	version: 1,
+	direct: {
+		enabled: true,
+		requireMention: "never"
+	},
+	channels: {
+		enabled: false,
+		requireMention: "outsideAllowlist"
+	},
+	entities: {
+		enabled: false,
+		requireMention: "always"
+	}
+};
+function mergePolicy(cfg) {
+	const inbound = cfg?.inbound;
+	return {
+		version: typeof inbound?.version === "number" && inbound.version >= 1 ? inbound.version : 1,
+		direct: {
+			...DEFAULT_INBOUND_POLICY.direct,
+			...inbound?.direct,
+			requireMention: inbound?.direct?.requireMention ?? DEFAULT_INBOUND_POLICY.direct.requireMention
+		},
+		channels: {
+			...DEFAULT_INBOUND_POLICY.channels,
+			...inbound?.channels,
+			requireMention: inbound?.channels?.requireMention ?? DEFAULT_INBOUND_POLICY.channels.requireMention
+		},
+		entities: {
+			...DEFAULT_INBOUND_POLICY.entities,
+			...inbound?.entities,
+			requireMention: inbound?.entities?.requireMention ?? DEFAULT_INBOUND_POLICY.entities.requireMention
+		}
+	};
+}
+function surfaceForKind(kind) {
+	if (kind === "direct") return "direct";
+	if (kind === "channel") return "channel";
+	return "entity";
+}
+function senderAllowed(allowed, fromReferenceId) {
+	if (!allowed || allowed.length === 0) return true;
+	return allowed.includes(fromReferenceId);
+}
+function channelGeoAllowed(params) {
+	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 !== void 0 && allowedChannelViewIds.includes(channelViewId);
+	else if (hasRooms) geoInAllowlist = allowedRoomIds.includes(roomId);
+	else if (hasViews) geoInAllowlist = channelViewId !== void 0 && allowedChannelViewIds.includes(channelViewId);
+	return {
+		geoInAllowlist,
+		details: {
+			roomId,
+			channelViewId,
+			allowedRoomIds,
+			allowedChannelViewIds,
+			hasRooms,
+			hasViews,
+			geoInAllowlist
+		}
+	};
+}
+function entityKindAllowed(kind, allowedKinds) {
+	if (!allowedKinds || allowedKinds.length === 0) return OMADEUS_INBOUND_ENTITY_KIND_SET.has(String(kind));
+	return allowedKinds.includes(String(kind));
+}
+function entityRoomOk(roomId, allowedRoomIds) {
+	if (!allowedRoomIds || allowedRoomIds.length === 0) return true;
+	return allowedRoomIds.includes(roomId);
+}
+function mentionRequired(params) {
+	const requireMention = params.requireMention ?? "never";
+	const { inAllowlist, isMention } = params;
+	if (requireMention === "never") return false;
+	if (requireMention === "always") return !isMention;
+	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.
+*/
+function evaluateOmadeusInboundPolicy(params) {
+	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 };
+	}
+	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 };
+}
+//#endregion
+export { evaluateOmadeusInboundPolicy };

package/dist/src/inbound.js

@@ -0,0 +1,97 @@
+//#region src/inbound.ts
+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) {
+	if (!raw) return null;
+	try {
+		return JSON.parse(raw);
+	} 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, selfReferenceId) {
+	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) {
+	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) {
+	return body.replace(/^\*\*@[^*]+\*\*\s*/, "").trim();
+}
+function readChannelViewId(metadata) {
+	if (metadata === null || metadata === void 0 || typeof metadata !== "object") return;
+	const m = metadata;
+	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());
+	}
+}
+/**
+* Determine whether a raw Jaguar socket payload is an OmadeusMessage.
+*/
+function isOmadeusMessage(data) {
+	if (typeof data !== "object" || data === null) return false;
+	const obj = data;
+	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
+*/
+function parseJaguarMessage(msg, opts, log) {
+	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 mentioned = isBotMentioned(parseDetails(msg.details), opts.selfReferenceId) || hasMentionPrefixInBody(body);
+	const content = mentioned ? stripLeadingMention(body) : body;
+	if (!content) return null;
+	const channelViewId = readChannelViewId(msg.metadata);
+	return {
+		messageId: msg.id,
+		from: String(msg.senderReferenceId),
+		fromReferenceId: msg.senderReferenceId,
+		content,
+		roomId: msg.roomId,
+		roomName: msg.roomName,
+		subscribableType: msg.subscribableType,
+		subscribableKind: msg.subscribableKind,
+		...channelViewId !== void 0 ? { channelViewId } : {},
+		isMention: mentioned,
+		timestamp: msg.createdAtTimestamp ? Math.floor(msg.createdAtTimestamp * 1e3) : Date.now()
+	};
+}
+//#endregion
+export { isOmadeusMessage, parseJaguarMessage };

package/dist/src/member-resolve.js

@@ -0,0 +1,53 @@
+import { listOrganizationMembers } from "./api/auth.api.js";
+//#region src/member-resolve.ts
+function formatMemberLabel(m) {
+	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.
+*/
+async function buildReferenceIdNameMap(apiOpts) {
+	const { organizationId } = apiOpts.tokenManager.getPayload();
+	const sessionToken = apiOpts.tokenManager.getToken();
+	const members = await listOrganizationMembers({
+		maestroUrl: apiOpts.maestroUrl,
+		sessionToken,
+		organizationId
+	});
+	const map = /* @__PURE__ */ new Map();
+	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"`).
+*/
+async function mergePeopleIntoNuggetAgentPayload(apiOpts, fullRecord, basePayload) {
+	let nameByRef;
+	try {
+		nameByRef = await buildReferenceIdNameMap(apiOpts);
+	} catch {
+		return { ...basePayload };
+	}
+	const people = {};
+	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 = { ...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;
+}
+//#endregion
+export { formatMemberLabel, mergePeopleIntoNuggetAgentPayload };

package/dist/src/message-handler.js

@@ -0,0 +1,262 @@
+import { logInboundDrop, resolveControlCommandGate } from "../runtime-api.js";
+import { createNugget, findNuggetByTaskChannelRoom, resolveTaskChannelRoomId, searchNuggetByNumber } from "./api/nugget.api.js";
+import { getOmadeusChannelConfig } from "./config.js";
+import { appendNuggetContextForTaskOrNuggetRoom, appendNuggetLookupContextForAgent, parseChannelTaskCreateIntent, parseNuggetLookupIntent, parseRecurringScheduleIntent } from "./nugget-lookup.js";
+import { getOmadeusRuntime } from "./runtime.js";
+import { createOmadeusReplyDispatcher } from "./reply-dispatcher.js";
+import { OMADEUS_INBOUND_ENTITY_KIND_SET } from "./types.js";
+import { evaluateOmadeusInboundPolicy } from "./inbound-policy.js";
+//#region src/message-handler.ts
+const SK = "`subscribableKind`";
+/** Injected into BodyForAgent so the model uses Jaguar room kind, not invented OpenClaw `task/...` keys. */
+function buildOmadeusEntityRoomContextLine(kind) {
+	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 label = {
+		project: "Project",
+		release: "Release",
+		sprint: "Sprint",
+		summary: "Summary",
+		client: "Client",
+		folder: "Folder"
+	}[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) {
+	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;
+}
+function createOmadeusMessageHandler(deps) {
+	const { cfg, runtime, log, outboundDeps, selfReferenceId } = deps;
+	const core = getOmadeusRuntime();
+	const omadeusCfg = getOmadeusChannelConfig(cfg);
+	const inboundDebounceMs = core.channel.debounce.resolveInboundDebounceMs({
+		cfg,
+		channel: "omadeus"
+	});
+	const handleMessageNow = async (inbound) => {
+		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 policyDecision = evaluateOmadeusInboundPolicy({
+			inbound,
+			omadeusCfg,
+			selfReferenceId
+		});
+		if (!policyDecision.allow) {
+			log.info("omadeus: dropped message by inbound policy", {
+				reason: policyDecision.reason,
+				...policyDecision.details ?? {},
+				roomId: inbound.roomId,
+				kind: inbound.subscribableKind,
+				fromReferenceId: inbound.fromReferenceId,
+				isMention: inbound.isMention
+			});
+			return;
+		}
+		const commandGate = resolveControlCommandGate({
+			useAccessGroups: cfg.commands?.useAccessGroups !== false,
+			authorizers: [],
+			allowTextCommands: true,
+			hasControlCommand: core.channel.text.hasControlCommand(rawBody, cfg)
+		});
+		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 = 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.\nYou 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}"\nDo NOT deliver to the current selected channel; delivery must go only to the created task private channel target above.\nThen 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 = 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 = await appendNuggetLookupContextForAgent(rawBody, nuggetIntent.nuggetNumber, null, outboundDeps.apiOpts, errorMessage);
+		}
+		if (!isDirectMessage && (inbound.subscribableKind === "task" || inbound.subscribableKind === "nugget") && !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);
+		}
+		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
+			}
+		});
+		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}` : `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?.store, { agentId: route.agentId });
+		const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+		const timestamp = inbound.timestamp ? new Date(inbound.timestamp) : void 0;
+		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 : void 0,
+			SenderName: senderName,
+			SenderId: senderId,
+			Provider: "omadeus",
+			Surface: "omadeus",
+			Timestamp: inbound.timestamp ?? Date.now(),
+			WasMentioned: isDirectMessage || inbound.isMention,
+			CommandAuthorized: commandGate.commandAuthorized,
+			OriginatingChannel: "omadeus",
+			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({
+		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;
+			}
+			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) {
+		await inboundDebouncer.enqueue(inbound);
+	};
+}
+//#endregion
+export { createOmadeusMessageHandler };