@xmanrui/dsh-im 4.38.2 → 4.39.0

package/src/channels/shared/context-enhancement.mjs

@@ -16,6 +16,8 @@ export const INJECTED_CONTEXT_TAGS = Object.freeze({
   guidanceClose: '</dsh_im_source_guidance>',
   replyOpen: '<dsh_im_reply_to>',
   replyClose: '</dsh_im_reply_to>',
+  contextOpen: '<dsh_im_context>',
+  contextClose: '</dsh_im_context>',
 });
 
 /** Separator the producer joins prefix blocks with, and the splitter consumes. */

package/src/channels/shared/conversation/ambient-provider.mjs

@@ -0,0 +1,115 @@
+/**
+ * Ambient context: the inferred-relation half of the context engine.
+ *
+ * Explicit relations (reply, thread root, bot-event binding) never need this
+ * module; it exists for the case where nobody replied, nobody opened a thread,
+ * yet a human reading the room obviously groups the messages anyway — a sender
+ * firing a burst of short messages right before addressing the bot. The
+ * provider reads the channel's bounded room history record (no second store),
+ * and a burst is a trailing same-sender run whose consecutive entries stay
+ * within `burstGapMs`; anything older or broken by the gap falls back to the
+ * bounded recent window. Entries the record already marked as injected are
+ * never re-offered, so ambient context is consumed at most once per entry.
+ */
+
+function boundedInt(value, min, max, fallback) {
+  if (!Number.isSafeInteger(value) || value <= 0) return fallback;
+  return Math.min(Math.max(value, min), max);
+}
+
+export const DEFAULT_AMBIENT_BURST_GAP_MS = 90_000;
+export const DEFAULT_AMBIENT_WINDOW_MS = 180_000;
+export const DEFAULT_AMBIENT_RECENT_COUNT = 20;
+export const DEFAULT_AMBIENT_MAX_CONTEXT_CHARS = 8_000;
+
+export class WindowAmbientProvider {
+  #store;
+  #burstGapMs;
+  #windowMs;
+  #recentCount;
+  #maxContextChars;
+
+  constructor({
+    store,
+    burstGapMs = DEFAULT_AMBIENT_BURST_GAP_MS,
+    recentWindowMs = DEFAULT_AMBIENT_WINDOW_MS,
+    recentCount = DEFAULT_AMBIENT_RECENT_COUNT,
+    maxContextChars = DEFAULT_AMBIENT_MAX_CONTEXT_CHARS,
+  } = {}) {
+    this.#store = store && typeof store.search === 'function' ? store : null;
+    this.#burstGapMs = boundedInt(burstGapMs, 5_000, 3_600_000, DEFAULT_AMBIENT_BURST_GAP_MS);
+    this.#windowMs = boundedInt(recentWindowMs, 10_000, 86_400_000, DEFAULT_AMBIENT_WINDOW_MS);
+    this.#recentCount = boundedInt(recentCount, 1, 200, DEFAULT_AMBIENT_RECENT_COUNT);
+    this.#maxContextChars = boundedInt(maxContextChars, 200, 200_000, DEFAULT_AMBIENT_MAX_CONTEXT_CHARS);
+  }
+
+  /**
+   * Collect the ambient entries that may accompany one triggered message.
+   * @param {{roomId: string, senderId: string, threadId?: string|null, now?: number}} query
+   *   — the optional `threadId` keeps the window inside one message list: the
+   *   room's mainline (`null`) or the named thread, matching what members read
+   *   in the current conversation.
+   * @returns {{burst: object[], recent: object[]}} both chronological; already-consumed and
+   *   non-human entries are excluded, and the recent list never repeats a burst entry.
+   */
+  query({ roomId, senderId, threadId = null, now = Date.now() } = {}) {
+    if (!this.#store || !roomId || typeof senderId !== 'string' || !senderId) {
+      return { burst: [], recent: [] };
+    }
+    const wantedThread = typeof threadId === 'string' && threadId ? threadId : null;
+    const span = Math.max(this.#windowMs, this.#burstGapMs);
+    // The record answers newest-first; one extra slice covers the burst run on
+    // top of the recent budget before anything is filtered out.
+    const fetched = this.#store.search({
+      roomId,
+      from: now - span,
+      to: now,
+      limit: Math.min(500, Math.max(this.#recentCount * 4, 60)),
+    });
+    // The record keeps arrival order, which a replayed or seeded batch can leave
+    // out of timestamp order; the gap walk and the recency budgets need true time order.
+    const chronological = [...(Array.isArray(fetched) ? fetched : [])].sort((left, right) => left.ts - right.ts);
+    // The record's own notion of un-consumed human speech is the pending list;
+    // `search` answers over all retained entries, so intersect with it instead of
+    // trusting the per-entry flag, which is only the record's rendering of it.
+    const pendingIds = typeof this.#store.pending === 'function'
+      ? new Set(this.#store.pending({ roomId, limit: 5_000 }).map((entry) => entry.eventId))
+      : null;
+    const candidates = chronological.filter((entry) => entry.kind === 'human'
+      && entry.injected !== true
+      && (entry.threadId ?? null) === wantedThread
+      && (pendingIds === null || pendingIds.has(entry.eventId)));
+    const burst = [];
+    for (let index = candidates.length - 1; index >= 0; index -= 1) {
+      const entry = candidates[index];
+      if (entry.sender !== senderId) break;
+      const later = burst[burst.length - 1];
+      if (later && later.ts - entry.ts > this.#burstGapMs) break;
+      burst.push(entry);
+    }
+    burst.reverse();
+    const burstIds = new Set(burst.map((entry) => entry.eventId));
+    const recent = [];
+    let used = 0;
+    for (let index = candidates.length - 1; index >= 0 && recent.length < this.#recentCount; index -= 1) {
+      const entry = candidates[index];
+      if (burstIds.has(entry.eventId)) continue;
+      const cost = entry.text.length + (entry.name ? entry.name.length + 2 : 1);
+      if (used + cost > this.#maxContextChars) break;
+      used += cost;
+      recent.unshift(entry);
+    }
+    return { burst, recent };
+  }
+
+  /**
+   * Mark the offered entries as consumed so they are not offered again.
+   * @param {{roomId: string, entries: object[]}} consumed
+   * @returns {Promise<number>} the number newly marked; 0 when the record cannot mark.
+   */
+  async markConsumed({ roomId, entries } = {}) {
+    if (!this.#store || typeof this.#store.markInjected !== 'function') return 0;
+    if (!roomId || !Array.isArray(entries) || entries.length === 0) return 0;
+    return await this.#store.markInjected(roomId, entries.map((entry) => entry.eventId));
+  }
+}

package/src/channels/shared/conversation/context-builder.mjs

@@ -0,0 +1,148 @@
+/**
+ * Assembly of the collected context entries into injected context blocks that
+ * ride along with the triggering prompt.
+ *
+ * Each entry becomes one `<dsh_im_context>` block of the shared injected
+ * context grammar, so the Host's `agent/pre-step` listener splits every entry
+ * back out into its own plugin-sourced context message beside the untouched
+ * user text: what the human asked stays exactly what the human typed, and the
+ * collected material is separated by `source`, never spliced into the question.
+ * Entries sharing one event id merge into a single block whose `collector`
+ * names every role that hit the event (e.g. `thread-root+reply`), so the same
+ * message is never presented twice under two headings.
+ */
+
+import { INJECTED_CONTEXT_SEPARATOR, INJECTED_CONTEXT_TAGS } from '../context-enhancement.mjs';
+import { CONTEXT_NOTE } from '../injected-context.mjs';
+
+/**
+ * @typedef {Object} ContextEntry
+ * @property {'thread-root'|'reply'|'ambient-burst'|'ambient-recent'|string} collector
+ * @property {string} roomId
+ * @property {?string} eventId
+ * @property {?string} sender
+ * @property {?string} name
+ * @property {?number} ts
+ * @property {string} text
+ */
+
+const COLLECTOR_MAX = 64;
+const ROOM_MAX = 256;
+const EVENT_MAX = 256;
+const SENDER_MAX = 300;
+const CONTENT_MAX = 8_000;
+
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f]/gu;
+
+function cleanField(value, limit) {
+  if (typeof value !== 'string') return undefined;
+  const cleaned = value.replace(CONTROL_CHARACTERS, '').trim();
+  if (!cleaned) return undefined;
+  return cleaned.length <= limit ? cleaned : cleaned.slice(0, limit);
+}
+
+function cleanContent(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\r\n?/gu, '\n').replace(CONTROL_CHARACTERS, '');
+  if (!normalized.trim()) return undefined;
+  return normalized.length <= CONTENT_MAX ? normalized : normalized.slice(0, CONTENT_MAX);
+}
+
+/**
+ * Merge entries that point at the same event into one entry, keeping the first
+ * occurrence's position, room, sender and stamp and naming every collector that
+ * referenced the event in first-seen order. Entries without an event id pass
+ * through unmerged; their collected text alone is what identifies them.
+ *
+ * @param {ContextEntry[]} entries
+ * @returns {ContextEntry[]} merged entries in assembly order
+ */
+export function dedupeContextEntries(entries) {
+  if (!Array.isArray(entries)) return [];
+  const merged = [];
+  const byEvent = new Map();
+  for (const entry of entries) {
+    const eventId = cleanField(entry?.eventId, EVENT_MAX);
+    if (eventId === undefined) {
+      merged.push({ ...entry });
+      continue;
+    }
+    const existing = byEvent.get(eventId);
+    if (existing === undefined) {
+      const copy = { ...entry, collector: cleanField(entry?.collector, COLLECTOR_MAX) ?? '' };
+      byEvent.set(eventId, copy);
+      merged.push(copy);
+      continue;
+    }
+    const collector = cleanField(entry?.collector, COLLECTOR_MAX);
+    if (collector !== undefined) {
+      existing.collector = existing.collector ? `${existing.collector}+${collector}` : collector;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Render one entry as a well-formed injected context block. The body is a
+ * plain object drawn from the block schema with `<>&` escaped, so the closing
+ * tag cannot be forged from collected values and the Host recognizes exactly
+ * the blocks this producer wrote.
+ *
+ * @param {ContextEntry} entry
+ * @returns {string} the block, or '' when the entry carries no renderable content.
+ */
+export function contextBlockFor(entry) {
+  const content = cleanContent(entry?.text);
+  if (content === undefined) return '';
+  const body = {
+    note: CONTEXT_NOTE,
+    collector: cleanField(entry?.collector, COLLECTOR_MAX) ?? '?',
+    ...(cleanField(entry?.roomId, ROOM_MAX) !== undefined ? { room: cleanField(entry.roomId, ROOM_MAX) } : {}),
+    ...(cleanField(entry?.eventId, EVENT_MAX) !== undefined ? { event: cleanField(entry.eventId, EVENT_MAX) } : {}),
+    ...(() => {
+      const sender = cleanField(entry?.sender ?? entry?.name, SENDER_MAX);
+      return sender === undefined ? {} : { sender };
+    })(),
+    ...(Number.isSafeInteger(entry?.ts) && entry.ts > 0 ? { ts: entry.ts } : {}),
+    content,
+  };
+  const json = JSON.stringify(body).replace(/[<>&]/gu, (character) => ({
+    '<': '\\u003c',
+    '>': '\\u003e',
+    '&': '\\u0026',
+  })[character]);
+  return `${INJECTED_CONTEXT_TAGS.contextOpen}${json}${INJECTED_CONTEXT_TAGS.contextClose}`;
+}
+
+/**
+ * Render the whole block set: entries merge by event id, empty entries drop
+ * out, and the surviving blocks join in the order the collectors supplied
+ * (explicit collectors before ambient). Joined with the protocol separator the
+ * Host's splitter consumes, so the user text that follows is all the human
+ * actually wrote.
+ *
+ * @param {ContextEntry[]} entries
+ * @returns {string} the joined blocks, or '' when there is nothing to say.
+ */
+export function renderContextEntries(entries) {
+  const blocks = [];
+  for (const entry of dedupeContextEntries(entries)) {
+    const block = contextBlockFor(entry);
+    if (block) blocks.push(block);
+  }
+  return blocks.join(INJECTED_CONTEXT_SEPARATOR);
+}
+
+/**
+ * Prepend the rendered blocks to the triggering prompt text, mirroring the
+ * enhancement producer's prefix pattern exactly so the splitter consumes the
+ * blocks and leaves the question verbatim.
+ *
+ * @param {{block: string, promptText: ?string}} parts
+ * @returns {string}
+ */
+export function composeContextPrompt({ block, promptText } = {}) {
+  const text = typeof promptText === 'string' ? promptText : '';
+  if (typeof block !== 'string' || !block) return text;
+  return `${block}\n\n${text}`;
+}

package/src/channels/shared/conversation/reply-context.mjs

@@ -0,0 +1,95 @@
+/**
+ * Explicit-relation context: the reply ancestor chain.
+ *
+ * A reply is a fact the platform states, not a guess, so it never consults the
+ * ambient record: the channel injects a `fetch` that resolves one event id to
+ * its text (Matrix: CS API single-event lookup, Feishu: OpenAPI message get).
+ * The walk is depth-bounded and loop-guarded because reply relations are
+ * user-authored data; a cyclic chain terminates on the first repeat instead of
+ * spinning. The result is oldest-first so the prompt reads cause before effect.
+ */
+
+/**
+ * @typedef {Object} ReplyChainNode
+ * @property {string} eventId
+ * @property {string} sender
+ * @property {string} name           Display name when the channel knows one.
+ * @property {string} text
+ * @property {?number} ts
+ */
+
+/**
+ * A tiny most-recent-used cache for single-event lookups so a burst of replies
+ * into one chain does not refetch shared ancestors. Insertion order is the LRU
+ * order; reading refreshes recency.
+ * @param {number} [capacity=256]
+ */
+export function createEventLru(capacity = 256) {
+  const cap = Number.isSafeInteger(capacity) && capacity > 0 ? capacity : 256;
+  const entries = new Map();
+  return {
+    get size() {
+      return entries.size;
+    },
+    get(key) {
+      if (!entries.has(key)) return undefined;
+      const value = entries.get(key);
+      entries.delete(key);
+      entries.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      if (entries.has(key)) entries.delete(key);
+      entries.set(key, value);
+      while (entries.size > cap) {
+        const oldest = entries.keys().next().value;
+        entries.delete(oldest);
+      }
+      return value;
+    },
+    delete(key) {
+      return entries.delete(key);
+    },
+    clear() {
+      entries.clear();
+    },
+  };
+}
+
+/**
+ * Walk `startReplyTo` upward through the reply relations the platform reports.
+ * @param {Object} input
+ * @param {(eventId: string) => Promise<{sender?: string, name?: string, text: string, replyTo?: ?string, ts?: ?number}|null>} input.fetch
+ *   Resolves one event, or null when it is gone, undecryptable, or not a message.
+ * @param {?string} input.startReplyTo The reply target of the triggering message.
+ * @param {number} [input.maxDepth=5]
+ * @returns {Promise<ReplyChainNode[]>} oldest ancestor first; empty when there is no chain.
+ */
+export async function resolveReplyChain({ fetch, startReplyTo, maxDepth = 5 } = {}) {
+  const chain = [];
+  if (typeof fetch !== 'function') return chain;
+  const depth = Number.isSafeInteger(maxDepth) && maxDepth > 0 ? Math.min(maxDepth, 10) : 5;
+  const visited = new Set();
+  let cursor = typeof startReplyTo === 'string' && startReplyTo ? startReplyTo : null;
+  while (cursor && !visited.has(cursor) && chain.length < depth) {
+    visited.add(cursor);
+    let event = null;
+    try {
+      event = await fetch(cursor);
+    } catch {
+      // A channel lookup failure leaves the chain exactly as far as it reached;
+      // a partial explicit context still beats dropping the whole turn's context.
+      event = null;
+    }
+    if (!event || typeof event.text !== 'string' || !event.text) break;
+    chain.push({
+      eventId: cursor,
+      sender: typeof event.sender === 'string' ? event.sender : '',
+      name: typeof event.name === 'string' ? event.name : '',
+      text: event.text,
+      ts: Number.isSafeInteger(event.ts) && event.ts > 0 ? event.ts : null,
+    });
+    cursor = typeof event.replyTo === 'string' && event.replyTo ? event.replyTo : null;
+  }
+  return chain.reverse();
+}

package/src/channels/shared/conversation/root-context.mjs

@@ -0,0 +1,101 @@
+/**
+ * One-consumption registry for conversation roots (Feishu topic roots, Matrix
+ * thread roots): the first message of a thread is context for that thread's AI
+ * conversation, but it must not be re-fed on every turn.
+ *
+ * The contract mirrors the behavior shipped for Feishu topics in CHANGELOG
+ * 4.24.1: the root rides along only until one turn using it completes
+ * successfully — commands, rejected messages, and failed lookups or requests
+ * never consume it — and a cleared, switched, or rebuilt session receives it
+ * again. Anchors persist through the conversation state store's extension
+ * mechanism so a restart does not re-inject; a state without that mechanism
+ * (tests, older stores) falls back to an in-process table.
+ */
+
+export class RootContextRegistry {
+  #state;
+  // Same shape as the persisted anchor table so every accessor reads one kind of value.
+  #fallback = Object.create(null);
+
+  constructor({ state = null } = {}) {
+    this.#state = state;
+  }
+
+  /** The live anchor table, creating it inside the persisted state when possible. */
+  #table(create = false) {
+    const extension = typeof this.#state?.extensionState === 'function' ? this.#state.extensionState() : null;
+    if (extension && typeof extension === 'object') {
+      if (extension.rootAnchors && typeof extension.rootAnchors === 'object') return extension.rootAnchors;
+      if (create) extension.rootAnchors = Object.create(null);
+      return extension ? extension.rootAnchors ?? null : null;
+    }
+    return this.#fallback;
+  }
+
+  #persist() {
+    if (typeof this.#state?.persist === 'function') return this.#state.persist();
+    return undefined;
+  }
+
+  /**
+   * @param {{sessionId: ?string, rootId: ?string}|null} anchor
+   */
+  anchorFor(routeKey) {
+    const anchor = this.#table(false)?.[routeKey];
+    if (!anchor || typeof anchor !== 'object') return null;
+    return Object.freeze({
+      sessionId: typeof anchor.sessionId === 'string' && anchor.sessionId ? anchor.sessionId : null,
+      rootId: typeof anchor.rootId === 'string' && anchor.rootId ? anchor.rootId : null,
+    });
+  }
+
+  /**
+   * Whether the root context should ride along on the next prompt.
+   * @param {{routeKey: string, sessionId: ?string, rootId: ?string}} request
+   * @returns {{inject: boolean, reason: string}}
+   */
+  plan({ routeKey, sessionId = null, rootId = null } = {}) {
+    if (!routeKey || typeof rootId !== 'string' || !rootId) {
+      return Object.freeze({ inject: false, reason: 'no-root' });
+    }
+    const anchor = this.anchorFor(routeKey);
+    const effectiveSessionId = typeof sessionId === 'string' && sessionId ? sessionId : null;
+    if (!anchor) return Object.freeze({ inject: true, reason: 'fresh' });
+    if (anchor.rootId !== rootId) return Object.freeze({ inject: true, reason: 'root-changed' });
+    if (anchor.sessionId !== effectiveSessionId) return Object.freeze({ inject: true, reason: 'session-changed' });
+    return Object.freeze({ inject: false, reason: 'consumed' });
+  }
+
+  /** Record a successful consumption; only call this after the turn succeeded. */
+  async markInjected({ routeKey, sessionId = null, rootId } = {}) {
+    if (!routeKey || typeof rootId !== 'string' || !rootId) return false;
+    const table = this.#table(true);
+    if (!table) return false;
+    table[routeKey] = {
+      sessionId: typeof sessionId === 'string' && sessionId ? sessionId : null,
+      rootId,
+      at: new Date().toISOString(),
+    };
+    await this.#persist();
+    return true;
+  }
+
+  /** Drop one route's anchor so the next successful turn re-receives the root (a cleared session). */
+  async clearRoute(routeKey) {
+    const table = this.#table(false);
+    if (!table || !(routeKey in table)) return false;
+    delete table[routeKey];
+    await this.#persist();
+    return true;
+  }
+
+  /** Drop every anchor (a full reset of the conversation state). */
+  async clearAll() {
+    const table = this.#table(false);
+    if (table) {
+      for (const key of Object.keys(table)) delete table[key];
+      await this.#persist();
+    }
+    for (const key of Object.keys(this.#fallback)) delete this.#fallback[key];
+  }
+}

package/src/channels/shared/conversation/route.mjs

@@ -0,0 +1,71 @@
+/**
+ * Channel-neutral conversation routes plus the single generator of the
+ * conversation session keys stored in a channel's state file.
+ *
+ * The codecs encode the established on-disk shapes so adopting this module
+ * never rewrites an existing key: Matrix keeps `direct:dm:<lower user id>`
+ * and `group:room:<roomId>[$<thread root>]` (event ids themselves begin with
+ * `$`, so a thread key reads with a `$$` run on disk); Feishu group chats keep
+ * `group:<chatId>` and `group:<chatId>:thread:<threadId>`. Feishu p2p keys
+ * are produced by the channel's own `conversationKey` helper until the parity
+ * cutover moves them here; the codec therefore refuses to encode a Feishu dm
+ * route instead of inventing a second shape.
+ */
+
+/**
+ * @typedef {Object} ConversationRoute
+ * @property {string} channel          Codec selector ('matrix', 'feishu', ...).
+ * @property {?string} botId           Bot identity for namespacing; null when the channel key is not bot-scoped.
+ * @property {string} chatId           Room / chat id: Matrix `room_id`, Feishu `chat_id`.
+ * @property {?string} senderId        Sender identity, required by dm routes.
+ * @property {?string} threadId        Server-side thread root (Matrix event id, Feishu thread_id); null on main-feed routes.
+ * @property {'dm'|'group'|'thread'} scope
+ */
+
+const MATRIX_CODEC = Object.freeze({
+  dm: (route) => `direct:dm:${String(route.senderId ?? '').trim().toLowerCase()}`,
+  group: (route) => `group:room:${route.chatId}${route.threadId ? `$${route.threadId}` : ''}`,
+});
+
+const FEISHU_CODEC = Object.freeze({
+  dm: null,
+  group: (route) => (route.threadId ? `group:${route.chatId}:thread:${route.threadId}` : `group:${route.chatId}`),
+});
+
+const CODECS = Object.freeze({ matrix: MATRIX_CODEC, feishu: FEISHU_CODEC });
+
+/**
+ * Build one frozen conversation route from the channel-neutral parts.
+ * @param {Object} parts - route parts; `kind` accepts 'direct'|'dm'|'group'.
+ * @returns {ConversationRoute}
+ */
+export function buildConversationRoute({ channel, botId = null, chatId, senderId = null, threadId = null, kind = 'group' } = {}) {
+  if (typeof channel !== 'string' || !channel) throw new TypeError('A conversation route requires a channel');
+  if (typeof chatId !== 'string' || !chatId) throw new TypeError('A conversation route requires a chat id');
+  const scope = kind === 'direct' || kind === 'dm'
+    ? 'dm'
+    : (typeof threadId === 'string' && threadId ? 'thread' : 'group');
+  return Object.freeze({
+    channel,
+    botId: typeof botId === 'string' && botId ? botId : null,
+    chatId,
+    senderId: typeof senderId === 'string' && senderId ? senderId : null,
+    threadId: scope === 'thread' ? threadId : null,
+    scope,
+  });
+}
+
+/**
+ * The one place conversation session keys are produced.
+ * @param {ConversationRoute} route
+ * @returns {string} the durable conversation key, e.g. `group:room:!a:x.org$$root:y.org`.
+ */
+export function encodeConversationRouteKey(route) {
+  const codec = CODECS[route?.channel];
+  if (!codec) throw new TypeError(`No conversation key codec is registered for channel "${route?.channel ?? '?'}"`);
+  const encode = codec[route.scope === 'dm' ? 'dm' : 'group'];
+  if (typeof encode !== 'function') {
+    throw new TypeError(`Channel "${route.channel}" cannot encode a ${route.scope} route`);
+  }
+  return encode(route);
+}

package/src/channels/shared/conversation/semantic-message.mjs

@@ -0,0 +1,75 @@
+/**
+ * The Semantic Message contract every channel adapter normalizes toward.
+ *
+ * CONTEXT.md separates what must stay platform-neutral (this shape and the
+ * conversation route) from the native channel action (cards, edits, reactions,
+ * threads as delivery targets). Only the former lives here; anything a channel
+ * produces through its own API stays in the channel directory. The shape is a
+ * duck-typed contract: existing channel-normalized messages already satisfy it
+ * field by field, so adapters may adopt `createSemanticMessage` incrementally.
+ */
+
+/**
+ * @typedef {Object} MessageRef
+ * @property {string} id              Platform event/message id.
+ * @property {?string} sender         Author identity of the referenced message.
+ * @property {?number} timestamp      Origin ms when known.
+ */
+
+/**
+ * @typedef {Object} SemanticMessage
+ * @property {string} id
+ * @property {string} channel
+ * @property {?string} botId
+ * @property {string} chatId          Room / chat id.
+ * @property {?string} threadId       Thread root when the message lives in one.
+ * @property {{id: string, name?: string}} sender
+ * @property {number} timestamp       Origin ms; ingestion time when the platform hides it.
+ * @property {string} content         Model-facing text, verbatim framing is producer-owned.
+ * @property {?MessageRef} replyTo
+ * @property {{mentionedBot: boolean, repliedToBot: boolean, commandLike: boolean}} trigger
+ * @property {'dm'|'group'} kind
+ */
+
+function clean(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * Validate and freeze one semantic message. Throws on identity-bearing fields;
+ * optional fields normalize to null instead of throwing so an adapter can
+ * forward a best-effort projection.
+ * @param {Object} fields
+ * @returns {SemanticMessage}
+ */
+export function createSemanticMessage({
+  id, channel, botId = null, chatId, threadId = null,
+  sender = {}, timestamp, content = '', replyTo = null, trigger = {}, kind = 'group',
+} = {}) {
+  if (typeof id !== 'string' || !id) throw new TypeError('A semantic message requires an id');
+  if (typeof channel !== 'string' || !channel) throw new TypeError('A semantic message requires a channel');
+  if (typeof chatId !== 'string' || !chatId) throw new TypeError('A semantic message requires a chat id');
+  const senderId = clean(sender?.id);
+  if (!senderId) throw new TypeError('A semantic message requires a sender id');
+  const senderName = clean(sender?.name);
+  const replyId = clean(replyTo?.id);
+  return Object.freeze({
+    id,
+    channel,
+    botId: clean(botId),
+    chatId,
+    threadId: clean(threadId),
+    sender: Object.freeze(senderName ? { id: senderId, name: senderName } : { id: senderId }),
+    timestamp: Number.isSafeInteger(timestamp) && timestamp > 0 ? timestamp : Date.now(),
+    content: typeof content === 'string' ? content : '',
+    replyTo: replyId
+      ? Object.freeze({ id: replyId, sender: clean(replyTo?.sender), timestamp: Number.isSafeInteger(replyTo?.timestamp) && replyTo.timestamp > 0 ? replyTo.timestamp : null })
+      : null,
+    trigger: Object.freeze({
+      mentionedBot: trigger?.mentionedBot === true,
+      repliedToBot: trigger?.repliedToBot === true,
+      commandLike: trigger?.commandLike === true,
+    }),
+    kind: kind === 'direct' || kind === 'dm' ? 'dm' : 'group',
+  });
+}