kalshi-trading-bot-cli 2.1.0

package/src/gateway/config.ts

@@ -0,0 +1,244 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { normalizeE164 } from './utils.js';
+import { appPath } from '../utils/paths.js';
+
+const DEFAULT_GATEWAY_PATH = appPath('gateway.json');
+const DmPolicySchema = z.enum(['pairing', 'allowlist', 'open', 'disabled']);
+const GroupPolicySchema = z.enum(['open', 'allowlist', 'disabled']);
+const ReconnectSchema = z.object({
+  initialMs: z.number().optional(),
+  maxMs: z.number().optional(),
+  factor: z.number().optional(),
+  jitter: z.number().optional(),
+  maxAttempts: z.number().optional(),
+});
+
+const WhatsAppAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional().default(true),
+  authDir: z.string().optional(),
+  allowFrom: z.array(z.string()).optional().default([]),
+  dmPolicy: DmPolicySchema.optional(),
+  groupPolicy: GroupPolicySchema.optional(),
+  groupAllowFrom: z.array(z.string()).optional().default([]),
+  sendReadReceipts: z.boolean().optional().default(true),
+});
+
+const HeartbeatConfigSchema = z
+  .object({
+    enabled: z.boolean().optional().default(false),
+    intervalMinutes: z.number().min(5).optional().default(10),
+    // default to NYSE market hours: 9:30 AM - 4:00 PM ET, Mon-Fri
+    activeHours: z
+      .object({
+        start: z.string().optional().default('09:30'),
+        end: z.string().optional().default('16:00'),
+        timezone: z.string().optional().default('America/New_York'),
+        daysOfWeek: z.array(z.number().min(0).max(6)).optional().default([1, 2, 3, 4, 5]),
+      })
+      .optional(),
+    model: z.string().optional(),
+    modelProvider: z.string().optional(),
+    maxIterations: z.number().optional().default(6),
+  })
+  .optional();
+
+const AlertsConfigSchema = z
+  .object({
+    minEdgeForAlert: z.number().optional().default(0.05),
+    channels: z.array(z.string()).optional().default(['terminal']),
+    whatsappTarget: z.string().optional(),
+  })
+  .optional();
+
+const GatewayConfigSchema = z.object({
+  gateway: z
+    .object({
+      accountId: z.string().optional(),
+      logLevel: z.enum(['silent', 'error', 'info', 'debug']).optional(),
+      heartbeatSeconds: z.number().optional(),
+      reconnect: ReconnectSchema.optional(),
+      heartbeat: HeartbeatConfigSchema,
+      alerts: AlertsConfigSchema,
+    })
+    .optional(),
+  channels: z
+    .object({
+      whatsapp: z
+        .object({
+          enabled: z.boolean().optional(),
+          accounts: z.record(z.string(), WhatsAppAccountSchema).optional(),
+          allowFrom: z.array(z.string()).optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  bindings: z
+    .array(
+      z.object({
+        agentId: z.string(),
+        match: z.object({
+          channel: z.string(),
+          accountId: z.string().optional(),
+          peerId: z.string().optional(),
+          peerKind: z.enum(['direct', 'group']).optional(),
+        }),
+      }),
+    )
+    .optional()
+    .default([]),
+});
+
+export type AlertsConfig = {
+  minEdgeForAlert: number;
+  channels: string[];
+  whatsappTarget?: string;
+};
+
+export type GatewayConfig = {
+  gateway: {
+    accountId: string;
+    logLevel: 'silent' | 'error' | 'info' | 'debug';
+    heartbeatSeconds?: number;
+    reconnect?: {
+      initialMs?: number;
+      maxMs?: number;
+      factor?: number;
+      jitter?: number;
+      maxAttempts?: number;
+    };
+    heartbeat?: {
+      enabled: boolean;
+      intervalMinutes: number;
+      activeHours?: { start: string; end: string; timezone?: string; daysOfWeek?: number[] };
+      model?: string;
+      modelProvider?: string;
+      maxIterations: number;
+    };
+    alerts?: AlertsConfig;
+  };
+  channels: {
+    whatsapp: {
+      enabled: boolean;
+      accounts: Record<string, z.infer<typeof WhatsAppAccountSchema>>;
+      allowFrom: string[];
+    };
+  };
+  bindings: Array<{
+    agentId: string;
+    match: {
+      channel: string;
+      accountId?: string;
+      peerId?: string;
+      peerKind?: 'direct' | 'group';
+    };
+  }>;
+};
+export type WhatsAppAccountConfig = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  authDir: string;
+  allowFrom: string[];
+  dmPolicy: 'pairing' | 'allowlist' | 'open' | 'disabled';
+  groupPolicy: 'open' | 'allowlist' | 'disabled';
+  groupAllowFrom: string[];
+  sendReadReceipts: boolean;
+};
+
+export function getGatewayConfigPath(overridePath?: string): string {
+  return overridePath ?? process.env.APP_GATEWAY_CONFIG ?? DEFAULT_GATEWAY_PATH;
+}
+
+export function loadGatewayConfig(overridePath?: string): GatewayConfig {
+  const path = getGatewayConfigPath(overridePath);
+  if (!existsSync(path)) {
+    return {
+      gateway: { accountId: 'default', logLevel: 'info' },
+      channels: { whatsapp: { enabled: true, accounts: {}, allowFrom: [] } },
+      bindings: [],
+    };
+  }
+  const raw = readFileSync(path, 'utf8');
+  const parsed = GatewayConfigSchema.parse(JSON.parse(raw));
+  return {
+    ...parsed,
+    gateway: {
+      accountId: parsed.gateway?.accountId ?? 'default',
+      logLevel: parsed.gateway?.logLevel ?? 'info',
+      heartbeatSeconds: parsed.gateway?.heartbeatSeconds,
+      reconnect: parsed.gateway?.reconnect,
+      heartbeat: parsed.gateway?.heartbeat
+        ? {
+            enabled: parsed.gateway.heartbeat.enabled ?? false,
+            intervalMinutes: parsed.gateway.heartbeat.intervalMinutes ?? 30,
+            activeHours: parsed.gateway.heartbeat.activeHours,
+            model: parsed.gateway.heartbeat.model,
+            modelProvider: parsed.gateway.heartbeat.modelProvider,
+            maxIterations: parsed.gateway.heartbeat.maxIterations ?? 6,
+          }
+        : undefined,
+      alerts: parsed.gateway?.alerts
+        ? {
+            minEdgeForAlert: parsed.gateway.alerts.minEdgeForAlert ?? 0.05,
+            channels: parsed.gateway.alerts.channels ?? ['terminal'],
+            whatsappTarget: parsed.gateway.alerts.whatsappTarget,
+          }
+        : undefined,
+    },
+    channels: {
+      whatsapp: {
+        enabled: parsed.channels?.whatsapp?.enabled ?? true,
+        accounts: parsed.channels?.whatsapp?.accounts ?? {},
+        allowFrom: parsed.channels?.whatsapp?.allowFrom ?? [],
+      },
+    },
+    bindings: parsed.bindings ?? [],
+  };
+}
+
+export function saveGatewayConfig(config: GatewayConfig, overridePath?: string): void {
+  const path = getGatewayConfigPath(overridePath);
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(config, null, 2), 'utf8');
+}
+
+export function listWhatsAppAccountIds(cfg: GatewayConfig): string[] {
+  const accounts = cfg.channels.whatsapp.accounts ?? {};
+  const ids = Object.keys(accounts);
+  return ids.length > 0 ? ids : [cfg.gateway.accountId];
+}
+
+export function resolveWhatsAppAccount(
+  cfg: GatewayConfig,
+  accountId: string,
+): WhatsAppAccountConfig {
+  const account = cfg.channels.whatsapp.accounts?.[accountId] ?? {};
+  const authDir = account.authDir ?? appPath('credentials', 'whatsapp', accountId);
+  const rawAllowFrom = account.allowFrom ?? cfg.channels.whatsapp.allowFrom ?? [];
+  const allowFrom = Array.from(
+    new Set(
+      rawAllowFrom
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => (entry === '*' ? '*' : normalizeE164(entry))),
+    ),
+  );
+  return {
+    accountId,
+    enabled: account.enabled ?? true,
+    name: account.name,
+    authDir,
+    allowFrom,
+    dmPolicy: account.dmPolicy ?? 'pairing',
+    groupPolicy: account.groupPolicy ?? 'disabled',
+    groupAllowFrom: account.groupAllowFrom ?? [],
+    sendReadReceipts: account.sendReadReceipts ?? true,
+  };
+}
+

package/src/gateway/extension-points.ts

@@ -0,0 +1,17 @@
+/**
+ * Future channel extension points:
+ *
+ * 1. Implement a channel plugin that satisfies `ChannelPlugin<TConfig, TAccount>`.
+ * 2. Provide inbound message normalization into gateway `InboundContext`.
+ * 3. Reuse `resolveRoute()` + `runAgentForMessage()` without changing gateway orchestration.
+ * 4. Register the plugin in gateway bootstrap next to WhatsApp.
+ *
+ * This keeps Layer 1 channel transport isolated from agent execution.
+ */
+export const GATEWAY_EXTENSION_POINTS = [
+  'ChannelPlugin lifecycle (start/stop/status)',
+  'InboundContext normalization',
+  'Outbound delivery adapter',
+  'Route/session metadata integration',
+] as const;
+

package/src/gateway/gateway.ts

@@ -0,0 +1,301 @@
+import { createChannelManager } from './channels/manager.js';
+import { createWhatsAppPlugin } from './channels/whatsapp/plugin.js';
+import {
+  assertOutboundAllowed,
+  sendComposing,
+  sendMessageWhatsApp,
+  type WhatsAppInboundMessage,
+} from './channels/whatsapp/index.js';
+import { resolveRoute } from './routing/resolve-route.js';
+import { resolveSessionStorePath, upsertSessionMeta } from './sessions/store.js';
+import { loadGatewayConfig, type GatewayConfig } from './config.js';
+import { runAgentForMessage } from './agent-runner.js';
+import { cleanMarkdownForWhatsApp } from './utils.js';
+import { startHeartbeatRunner } from './heartbeat/index.js';
+import {
+  isBotMentioned,
+  recordGroupMessage,
+  getAndClearGroupHistory,
+  formatGroupHistoryContext,
+  noteGroupMember,
+  formatGroupMembersList,
+} from './group/index.js';
+import { AlertRouter, formatAlertForWhatsApp, formatAlertForTerminal } from './alerts/index.js';
+import { parseCommand } from './commands/parser.js';
+import { handleCommand } from './commands/handler.js';
+import type { GroupContext } from '../agent/prompts.js';
+import { appendFileSync } from 'node:fs';
+import { appPath } from '../utils/paths.js';
+import { getSetting } from '../utils/config.js';
+
+const LOG_PATH = appPath('gateway-debug.log');
+function debugLog(msg: string) {
+  appendFileSync(LOG_PATH, `${new Date().toISOString()} ${msg}\n`);
+}
+
+export type GatewayService = {
+  stop: () => Promise<void>;
+  snapshot: () => Record<string, { accountId: string; running: boolean; connected?: boolean }>;
+};
+
+function elide(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + '...';
+}
+
+async function handleInbound(cfg: GatewayConfig, inbound: WhatsAppInboundMessage, alertRouter: AlertRouter): Promise<void> {
+  const bodyPreview = elide(inbound.body.replace(/\n/g, ' '), 50);
+  const isGroup = inbound.chatType === 'group';
+  console.log(`Inbound message ${inbound.from} (${inbound.chatType}, ${inbound.body.length} chars): "${bodyPreview}"`);
+  debugLog(`[gateway] handleInbound from=${inbound.from} isGroup=${isGroup} body="${inbound.body.slice(0, 30)}..."`);
+
+  // --- Group-specific: track member, check mention gating ---
+  if (isGroup) {
+    noteGroupMember(inbound.chatId, inbound.senderId, inbound.senderName);
+
+    const mentioned = isBotMentioned({
+      mentionedJids: inbound.mentionedJids,
+      selfJid: inbound.selfJid,
+      selfLid: inbound.selfLid,
+      selfE164: inbound.selfE164,
+      body: inbound.body,
+    });
+    debugLog(`[gateway] group mention check: mentioned=${mentioned}`);
+
+    if (!mentioned) {
+      // Buffer the message for future context but don't reply
+      recordGroupMessage(inbound.chatId, {
+        senderName: inbound.senderName ?? inbound.senderId,
+        senderId: inbound.senderId,
+        body: inbound.body,
+        timestamp: inbound.timestamp ?? Date.now(),
+      });
+      debugLog(`[gateway] group message buffered (no mention), skipping reply`);
+      return;
+    }
+  }
+
+  // --- Routing: use chatId for groups (group JID), senderId for DMs ---
+  const peerId = isGroup ? inbound.chatId : inbound.senderId;
+  const route = resolveRoute({
+    cfg,
+    channel: 'whatsapp',
+    accountId: inbound.accountId,
+    peer: { kind: inbound.chatType, id: peerId },
+  });
+
+  const storePath = resolveSessionStorePath(route.agentId);
+  upsertSessionMeta({
+    storePath,
+    sessionKey: route.sessionKey,
+    channel: 'whatsapp',
+    to: inbound.from,
+    accountId: route.accountId,
+    agentId: route.agentId,
+  });
+
+  // --- Command interception: parse message as command before falling through to agent ---
+  const intent = parseCommand(inbound.body);
+  if (intent.type !== 'none') {
+    debugLog(`[gateway] command intercepted: ${intent.type}`);
+    try {
+      const reply = await handleCommand(intent, alertRouter, route.sessionKey);
+      if (reply) {
+        const outboundTarget = isGroup ? inbound.chatId : inbound.replyToJid;
+        try {
+          assertOutboundAllowed({ to: outboundTarget, accountId: inbound.accountId });
+        } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
+          debugLog(`[gateway] command outbound BLOCKED: ${msg}`);
+          return;
+        }
+        if (isGroup) {
+          await inbound.reply(reply);
+        } else {
+          await sendMessageWhatsApp({ to: inbound.replyToJid, body: reply, accountId: inbound.accountId });
+        }
+        console.log(`Command '${intent.type}' replied (${reply.length} chars)`);
+        debugLog(`[gateway] command reply sent`);
+        return;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(`Command error: ${msg}`);
+      debugLog(`[gateway] command ERROR: ${msg}`);
+    }
+  }
+
+  // Start typing indicator loop to keep it alive during long agent runs
+  const TYPING_INTERVAL_MS = 5000; // Refresh every 5 seconds
+  let typingTimer: ReturnType<typeof setInterval> | undefined;
+
+  const startTypingLoop = async () => {
+    // For groups, use inbound.sendComposing directly (bypasses outbound strict checks)
+    if (isGroup) {
+      await inbound.sendComposing();
+      typingTimer = setInterval(() => { void inbound.sendComposing(); }, TYPING_INTERVAL_MS);
+    } else {
+      await sendComposing({ to: inbound.replyToJid, accountId: inbound.accountId });
+      typingTimer = setInterval(() => {
+        void sendComposing({ to: inbound.replyToJid, accountId: inbound.accountId });
+      }, TYPING_INTERVAL_MS);
+    }
+  };
+
+  const stopTypingLoop = () => {
+    if (typingTimer) {
+      clearInterval(typingTimer);
+      typingTimer = undefined;
+    }
+  };
+
+  try {
+    // Defense-in-depth: verify outbound destination is allowed before any messaging
+    // For groups, use chatId (the group JID); for DMs, use replyToJid
+    const outboundTarget = isGroup ? inbound.chatId : inbound.replyToJid;
+    try {
+      assertOutboundAllowed({ to: outboundTarget, accountId: inbound.accountId });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      debugLog(`[gateway] outbound BLOCKED: ${msg}`);
+      console.log(msg);
+      return;
+    }
+
+    await startTypingLoop();
+
+    // --- Build query: for groups, include buffered history context ---
+    let query = inbound.body;
+    let groupContext: GroupContext | undefined;
+
+    if (isGroup) {
+      const history = getAndClearGroupHistory(inbound.chatId);
+      query = formatGroupHistoryContext({
+        history,
+        currentSenderName: inbound.senderName ?? inbound.senderId,
+        currentSenderId: inbound.senderId,
+        currentBody: inbound.body,
+      });
+      debugLog(`[gateway] group query with ${history.length} history entries`);
+
+      const membersList = formatGroupMembersList({
+        groupId: inbound.chatId,
+        participants: inbound.groupParticipants,
+      });
+      groupContext = {
+        groupName: inbound.groupSubject,
+        membersList: membersList || undefined,
+        activationMode: 'mention',
+      };
+    }
+
+    console.log(`Processing message with agent...`);
+    debugLog(`[gateway] running agent for session=${route.sessionKey}`);
+    const startedAt = Date.now();
+    const model = getSetting('modelId', 'gpt-5.4') as string;
+    const modelProvider = getSetting('provider', 'openai') as string;
+    const answer = await runAgentForMessage({
+      sessionKey: route.sessionKey,
+      query,
+      model,
+      modelProvider,
+      channel: 'whatsapp',
+      groupContext,
+    });
+    const durationMs = Date.now() - startedAt;
+    debugLog(`[gateway] agent answer length=${answer.length}`);
+
+    // Stop typing loop before sending reply
+    stopTypingLoop();
+
+    if (answer.trim()) {
+      const cleanedAnswer = cleanMarkdownForWhatsApp(answer);
+
+      if (isGroup) {
+        // For groups, use inbound.reply() directly (bypasses outbound strict E.164 checks)
+        debugLog(`[gateway] sending group reply to ${inbound.chatId}`);
+        await inbound.reply(cleanedAnswer);
+      } else {
+        debugLog(`[gateway] sending reply to ${inbound.replyToJid}`);
+        await sendMessageWhatsApp({
+          to: inbound.replyToJid,
+          body: cleanedAnswer,
+          accountId: inbound.accountId,
+        });
+      }
+      console.log(`Sent reply (${answer.length} chars, ${durationMs}ms)`);
+      debugLog(`[gateway] reply sent`);
+    } else {
+      console.log(`Agent returned empty response (${durationMs}ms)`);
+      debugLog(`[gateway] empty answer, not sending`);
+    }
+  } catch (err) {
+    stopTypingLoop();
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(`Error: ${msg}`);
+    debugLog(`[gateway] ERROR: ${msg}`);
+  }
+}
+
+export async function startGateway(params: { configPath?: string } = {}): Promise<GatewayService> {
+  const cfg = loadGatewayConfig(params.configPath);
+
+  // --- Alert Router setup ---
+  const alertRouter = new AlertRouter();
+
+  // Terminal handler
+  alertRouter.registerChannel('terminal', async (alert) => {
+    console.log(formatAlertForTerminal(alert));
+  });
+
+  // WhatsApp handler
+  alertRouter.registerChannel('whatsapp', async (alert, target) => {
+    if (!target) return;
+    const formatted = formatAlertForWhatsApp(alert);
+    try {
+      await sendMessageWhatsApp({
+        to: target,
+        body: formatted,
+        accountId: cfg.gateway.accountId,
+      });
+
+      // Set pending approval for edge alerts
+      if (alert.alertType === 'EDGE_DETECTED') {
+        alertRouter.setPending(target, {
+          ticker: alert.ticker,
+          alertId: crypto.randomUUID(),
+          edge: alert.edge,
+          createdAt: Date.now(),
+          sessionKey: target,
+        });
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(`[AlertRouter] WhatsApp send failed: ${msg}`);
+    }
+  });
+
+  const plugin = createWhatsAppPlugin({
+    loadConfig: () => loadGatewayConfig(params.configPath),
+    onMessage: async (inbound) => {
+      const current = loadGatewayConfig(params.configPath);
+      await handleInbound(current, inbound, alertRouter);
+    },
+  });
+  const manager = createChannelManager({
+    plugin,
+    loadConfig: () => loadGatewayConfig(params.configPath),
+  });
+  await manager.startAll();
+
+  const heartbeat = startHeartbeatRunner({ configPath: params.configPath });
+
+  return {
+    stop: async () => {
+      heartbeat.stop();
+      await manager.stopAll();
+    },
+    snapshot: () => manager.getSnapshot(),
+  };
+}
+

package/src/gateway/group/history-buffer.ts

@@ -0,0 +1,75 @@
+/**
+ * In-memory buffer for group messages between bot replies.
+ * Records messages in each group and provides them as context when the bot is mentioned.
+ */
+
+export type GroupHistoryEntry = {
+  senderName: string;
+  senderId: string;
+  body: string;
+  timestamp: number;
+};
+
+const MAX_ENTRIES_PER_GROUP = 50;
+const MAX_GROUPS = 200;
+
+const buffers = new Map<string, GroupHistoryEntry[]>();
+
+/**
+ * Record a group message into the history buffer.
+ */
+export function recordGroupMessage(groupId: string, entry: GroupHistoryEntry): void {
+  let entries = buffers.get(groupId);
+  if (!entries) {
+    // LRU eviction: if at capacity, remove the oldest-accessed group
+    if (buffers.size >= MAX_GROUPS) {
+      const oldestKey = buffers.keys().next().value as string;
+      buffers.delete(oldestKey);
+    }
+    entries = [];
+    buffers.set(groupId, entries);
+  }
+
+  entries.push(entry);
+
+  // Trim to max entries
+  if (entries.length > MAX_ENTRIES_PER_GROUP) {
+    entries.splice(0, entries.length - MAX_ENTRIES_PER_GROUP);
+  }
+}
+
+/**
+ * Get all buffered history for a group and clear it.
+ */
+export function getAndClearGroupHistory(groupId: string): GroupHistoryEntry[] {
+  const entries = buffers.get(groupId) ?? [];
+  buffers.delete(groupId);
+  return entries;
+}
+
+/**
+ * Format group history entries and the current message into a context block
+ * for the agent's system prompt.
+ */
+export function formatGroupHistoryContext(params: {
+  history: GroupHistoryEntry[];
+  currentSenderName: string;
+  currentSenderId: string;
+  currentBody: string;
+}): string {
+  const { history, currentSenderName, currentSenderId, currentBody } = params;
+  const parts: string[] = [];
+
+  if (history.length > 0) {
+    parts.push('[Group messages since your last reply - for context]');
+    for (const entry of history) {
+      parts.push(`${entry.senderName} (${entry.senderId}): ${entry.body}`);
+    }
+    parts.push('');
+  }
+
+  parts.push('[Current message - respond to this]');
+  parts.push(`${currentSenderName} (${currentSenderId}): ${currentBody}`);
+
+  return parts.join('\n');
+}

package/src/gateway/group/index.ts

@@ -0,0 +1,8 @@
+export { isBotMentioned } from './mention-detection.js';
+export {
+  recordGroupMessage,
+  getAndClearGroupHistory,
+  formatGroupHistoryContext,
+  type GroupHistoryEntry,
+} from './history-buffer.js';
+export { noteGroupMember, formatGroupMembersList } from './member-tracker.js';

package/src/gateway/group/member-tracker.ts

@@ -0,0 +1,60 @@
+/**
+ * Track group member display names from messages.
+ * Maps e164 phone numbers to display names per group.
+ */
+
+// groupId → Map<e164, displayName>
+const rosters = new Map<string, Map<string, string>>();
+
+/**
+ * Record a group member's display name from an incoming message.
+ */
+export function noteGroupMember(groupId: string, senderId: string, displayName?: string): void {
+  if (!displayName) return;
+
+  let roster = rosters.get(groupId);
+  if (!roster) {
+    roster = new Map();
+    rosters.set(groupId, roster);
+  }
+  roster.set(senderId, displayName);
+}
+
+/**
+ * Format a human-readable list of group members.
+ * Combines API-provided participants with observed display names from the roster.
+ */
+export function formatGroupMembersList(params: {
+  groupId: string;
+  participants?: string[];
+}): string {
+  const { groupId, participants } = params;
+  const roster = rosters.get(groupId);
+
+  if (!participants?.length && !roster?.size) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  const seen = new Set<string>();
+
+  // Roster entries (have display names)
+  if (roster) {
+    for (const [id, name] of roster) {
+      lines.push(`- ${name} (${id})`);
+      seen.add(id);
+    }
+  }
+
+  // Participants from group metadata (fill in any not already in roster)
+  if (participants) {
+    for (const p of participants) {
+      if (p && !seen.has(p)) {
+        lines.push(`- ${p}`);
+        seen.add(p);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}