@desplega.ai/agent-swarm 2.4.4 → 2.4.5

package/src/http/pages-public.ts

@@ -13,7 +13,7 @@
  *     302-redirect to the SPA `/pages/:id` route (the JSON renderer lives
  *     in the SPA, not the API — step-6/7).
  *   - `auth_mode === 'authed'`: returns 401. step-4 narrows this to also
- *     accept a valid `page_session` cookie.
+ *     accept a valid `page_session_<id>` cookie.
  *   - `auth_mode === 'password'`: returns 401. step-5 narrows this to also
  *     accept `?key=` query param + HTTP Basic.
  *
@@ -33,7 +33,7 @@ import {
 import { type Page, PageSchema } from "../types";
 import { getAppUrl, getConfiguredAppUrls } from "../utils/constants";
 import { getNodeEnv } from "../utils/node-env";
-import { extractAndVerifyCookie, issuePageSessionCookie } from "../utils/page-session";
+import { extractAndVerifyCookie, pageSessionSetCookies } from "../utils/page-session";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { route } from "./route-def";
 
@@ -357,16 +357,15 @@ function buildCsp(): string {
 /**
  * Decide whether a page is reachable based on cookie alone. Public pages are
  * always reachable; authed AND password pages can ALSO pass via a valid
- * `page_session` cookie scoped to the same page id (the cookie is the proof
- * once the user has successfully unlocked once). For password pages, when
- * the cookie is absent/invalid the caller falls through to the `?key=` +
- * Basic-auth resolution path; for authed pages the caller surfaces 401.
+ * `page_session_<id>` cookie (or the legacy `page_session`) whose signed
+ * payload names this page (the cookie is the proof once the user has
+ * successfully unlocked once). For password pages, when the cookie is
+ * absent/invalid the caller falls through to the `?key=` + Basic-auth
+ * resolution path; for authed pages the caller surfaces 401.
  *
  * The caller passes the cookie payload (already verified by
- * `extractAndVerifyCookie`) — `null` when no cookie was sent or it failed
- * verification. Cross-page reuse (cookie for page A presented for page B)
- * surfaces as a distinct `403` so misconfigurations are debuggable, NOT a
- * generic 401.
+ * `extractAndVerifyCookie`, which ignores sessions for other pages) — `null`
+ * when no session for this page was sent or it failed verification.
  *
  * For password pages with no/bad cookie, returns `{ ok: false, status: 401,
  * needsPassword: true }` so the handler knows to try the password flow before
@@ -374,7 +373,7 @@ function buildCsp(): string {
  */
 type AccessResult =
   | { ok: true }
-  | { ok: false; status: 401 | 403; reason: string; needsPassword?: boolean };
+  | { ok: false; status: 401; reason: string; needsPassword?: boolean };
 
 function isAccessible(
   page: Page,
@@ -382,27 +381,9 @@ function isAccessible(
 ): AccessResult {
   if (page.authMode === "public") return { ok: true };
 
-  // Cookie-first path. A cookie scoped to a DIFFERENT page id is "stale" —
-  // for password mode we silently ignore it and fall through to the password
-  // flow so the user can recover via `?key=` / Basic without manual cookie
-  // clearing. For authed mode we surface 403 (the SPA's launch-retry path
-  // handles recovery; direct browser access to authed pages is rare).
-  if (cookiePayload) {
-    if (cookiePayload.pageId === page.id) return { ok: true };
-    if (page.authMode === "password") {
-      return {
-        ok: false,
-        status: 401,
-        reason: "password required",
-        needsPassword: true,
-      };
-    }
-    return {
-      ok: false,
-      status: 403,
-      reason: "page-session cookie scoped to a different page id",
-    };
-  }
+  // Cookie-first path. Sessions for other pages never reach here, so an open
+  // tab of page A no longer fails once page B is launched in the same browser.
+  if (cookiePayload?.pageId === page.id) return { ok: true };
 
   if (page.authMode === "authed") {
     return {
@@ -523,7 +504,7 @@ export async function handlePagesPublic(
   // Pull + verify the page-session cookie ONCE — `null` covers "no cookie",
   // "tampered signature", "expired", "malformed". The access decision below
   // discriminates per-authMode.
-  const cookiePayload = await extractAndVerifyCookie(req);
+  const cookiePayload = await extractAndVerifyCookie(req, page.id);
 
   const access = isAccessible(page, cookiePayload);
 
@@ -531,7 +512,7 @@ export async function handlePagesPublic(
   // password flow mints a fresh cookie inline. Empty string = no cookie to
   // attach. We thread this through the handler so the existing 200-response
   // paths below can opt-in without duplicating their branch logic.
-  let inlineSetCookie = "";
+  let inlineSetCookie: string[] = [];
 
   if (!access.ok) {
     // Password flow: cookie missing/invalid, try `?key=` then Basic.
@@ -547,7 +528,7 @@ export async function handlePagesPublic(
           matched = false;
         }
         if (matched) {
-          inlineSetCookie = await issuePageSessionCookie(page.id, {
+          inlineSetCookie = await pageSessionSetCookies(req, page.id, {
             dev: isLocalhostRequest(req),
           });
           // fall through to the regular 200 path below.
@@ -586,7 +567,7 @@ export async function handlePagesPublic(
     // that `respond()` writes via `res.writeHead()` — Node gives the latter
     // precedence, which is the value we want here anyway.
     res.setHeader("Cache-Control", "no-store");
-    if (inlineSetCookie) res.setHeader("Set-Cookie", inlineSetCookie);
+    if (inlineSetCookie.length > 0) res.setHeader("Set-Cookie", inlineSetCookie);
     publicPageJsonRoute.respond(res, 200, {
       id: page.id,
       version: 1, // edit-counter is API-internal; SPA reads via /api/pages/:id/versions
@@ -602,13 +583,13 @@ export async function handlePagesPublic(
 
   // SVG stays byte-for-byte intact, including when ?print=1 is supplied.
   if (page.contentType === "image/svg+xml") {
-    const headers: Record<string, string> = {
+    const headers: Record<string, string | string[]> = {
       "Content-Type": "image/svg+xml",
       "Cache-Control": page.authMode === "public" ? "public, max-age=1800" : "private, no-store",
       "X-Content-Type-Options": "nosniff",
       "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
     };
-    if (inlineSetCookie) headers["Set-Cookie"] = inlineSetCookie;
+    if (inlineSetCookie.length > 0) headers["Set-Cookie"] = inlineSetCookie;
     res.writeHead(200, headers);
     res.end(page.body);
     await bumpViewCount(page.id);
@@ -625,20 +606,22 @@ export async function handlePagesPublic(
   // `/p/:id` — render either HTML directly or 302→SPA for JSON.
   if (page.contentType === "application/json") {
     if (wantsPrint) {
-      const headers: Record<string, string> = {
+      const headers: Record<string, string | string[]> = {
         "Content-Type": "text/html; charset=utf-8",
         "Cache-Control": "no-store",
         "Content-Security-Policy": buildCsp(),
         "X-Content-Type-Options": "nosniff",
       };
-      if (inlineSetCookie) headers["Set-Cookie"] = inlineSetCookie;
+      if (inlineSetCookie.length > 0) headers["Set-Cookie"] = inlineSetCookie;
       res.writeHead(200, headers);
       res.end(printableJsonPageHtml(page));
       await bumpViewCount(page.id);
       return true;
     }
-    const headers: Record<string, string> = { Location: `${getAppBaseUrl()}/pages/${page.id}` };
-    if (inlineSetCookie) headers["Set-Cookie"] = inlineSetCookie;
+    const headers: Record<string, string | string[]> = {
+      Location: `${getAppBaseUrl()}/pages/${page.id}`,
+    };
+    if (inlineSetCookie.length > 0) headers["Set-Cookie"] = inlineSetCookie;
     res.writeHead(302, headers);
     res.end();
     // 302 redirects are intentionally NOT counted — they're a stop-over for
@@ -656,14 +639,14 @@ export async function handlePagesPublic(
     injectBrowserSdk(page.body, feedback ? feedbackKeyGuardScript() : "") +
     (wantsPrint ? PRINT_AUTOTRIGGER_SCRIPT : "") +
     (feedback ? feedbackOverlayScripts(page.id) : "");
-  const headers: Record<string, string> = {
+  const headers: Record<string, string | string[]> = {
     "Content-Type": "text/html; charset=utf-8",
     "Cache-Control": "no-store",
     "Content-Security-Policy": buildCsp(),
     // Defence-in-depth: prevent MIME sniffing and clickjacking outside the SPA.
     "X-Content-Type-Options": "nosniff",
   };
-  if (inlineSetCookie) headers["Set-Cookie"] = inlineSetCookie;
+  if (inlineSetCookie.length > 0) headers["Set-Cookie"] = inlineSetCookie;
   res.writeHead(200, headers);
   res.end(html);
   await bumpViewCount(page.id);

package/src/http/pages.ts

@@ -36,7 +36,7 @@ import {
 } from "../types";
 import { getAppUrl, getPublicMcpBaseUrl } from "../utils/constants";
 import { getNodeEnv } from "../utils/node-env";
-import { issuePageSessionCookie } from "../utils/page-session";
+import { pageSessionSetCookies } from "../utils/page-session";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
@@ -175,7 +175,7 @@ const resolvePageRoute = route({
  *     `?key=` query / HTTP Basic on `/p/:id` directly (step-5). Bearer-side
  *     issuance would bypass the password check entirely.
  *
- * Response: 204 No Content + `Set-Cookie: page_session=<signed>; HttpOnly; ...`.
+ * Response: 204 No Content + `Set-Cookie: page_session_<id>=<signed>; HttpOnly; ...`.
  */
 const launchPageRoute = route({
   method: "post",
@@ -981,13 +981,13 @@ export async function handlePages(
         : auth?.kind === "operator"
           ? { name: `guest-${randomUUID().slice(0, 8)}`, op: true as const }
           : undefined;
-    const cookie = await issuePageSessionCookie(page.id, {
+    const cookies = await pageSessionSetCookies(req, page.id, {
       dev: isDevRequest(req),
       ...identity,
     });
 
     applyLaunchCors(req, res);
-    res.setHeader("Set-Cookie", cookie);
+    res.setHeader("Set-Cookie", cookies);
     res.writeHead(204);
     res.end();
     return true;

package/src/http/script-runs.ts

@@ -101,6 +101,7 @@ const agentTaskBodySchema = z.object({
   routingNote: z.string().max(200).optional(),
   tags: z.array(z.string()).optional(),
   priority: z.number().int().min(0).max(100).optional(),
+  dependsOn: z.array(z.uuid()).optional(),
   offerMode: z.boolean().optional(),
   dir: z.string().min(1).optional(),
   vcsRepo: z.string().min(1).optional(),
@@ -655,6 +656,7 @@ export async function handleScriptRuns(
                 : undefined,
             tags: parsed.body.tags,
             priority: parsed.body.priority,
+            dependsOn: parsed.body.dependsOn,
             offeredTo: parsed.body.offerMode ? parsed.body.agentId : undefined,
             taskType: "script-run-step",
             source: "mcp",

package/src/http/users.ts

@@ -550,7 +550,18 @@ const deleteIdentityRoute = route({
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-const UNMAPPED_KINDS = ["slack", "github", "gitlab", "azure-devops", "linear", "kapso"] as const;
+const UNMAPPED_KINDS = [
+  "slack",
+  "github",
+  "gitlab",
+  "azure-devops",
+  "linear",
+  "kapso",
+  // Chat SDK adapters record unknown senders under the adapter name.
+  "telegram",
+  "discord",
+  "teams",
+] as const;
 
 /**
  * Group the two-key-per-identity kv entries (`<externalId>:meta` json +

package/src/integrations/chat-sdk/adapters.ts

@@ -63,9 +63,13 @@ export async function loadAdapter(
     case "telegram": {
       const { createTelegramAdapter } = await import("@chat-adapter/telegram");
       // Explicit `false` blocks the TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS env fallback.
-      return createTelegramAdapter({ ...base, allowUnverifiedWebhooks: false } as Parameters<
-        typeof createTelegramAdapter
-      >[0]);
+      // Explicit `true` makes a reply to the bot a mention whatever
+      // TELEGRAM_MENTION_ON_REPLY says.
+      return createTelegramAdapter({
+        ...base,
+        allowUnverifiedWebhooks: false,
+        mentionOnReply: true,
+      } as Parameters<typeof createTelegramAdapter>[0]);
     }
     case "slack": {
       const { createSlackAdapter } = await import("@chat-adapter/slack");

package/src/integrations/chat-sdk/attachments.ts

@@ -9,7 +9,9 @@
  * row. The task is created in `draft` while its uploads run, with its lease
  * renewed, so no worker can claim it before its attachments exist. Every file
  * also stays in the task text as a `[File: ...]` line. Only a fetch failure is
- * flagged there; upload and record failures are logged.
+ * flagged there; upload and record failures are logged. Audio files (voice
+ * notes) get their transcript in the task text when transcription is
+ * configured, and keep the audio attached.
  */
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -21,12 +23,28 @@ import { providerPath } from "@/fs/provider";
 import { getFileStorageProvider } from "@/fs/registry";
 import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import type { AgentTask, CreateTaskOptions } from "@/types";
+import { transcribeAudioNotes } from "@/utils/transcription";
 import { errorMessage } from "./logger";
 
 /** How often a draft's lease is renewed while its uploads run; the sweep waits 5 minutes. */
 const DRAFT_LEASE_REFRESH_MS = 60_000;
 /** A file a user sent the bot, like one uploaded from the dashboard composer. */
-const SHARED_FILE_INTENT = "user-upload";
+export const SHARED_FILE_INTENT = "user-upload";
+
+const MB = 1024 * 1024;
+/**
+ * Per-file inbound cap by adapter. A Telegram bot can download at most 20 MB
+ * through `getFile`; a larger file fails at Telegram before our own cap.
+ * Other adapters use the task attachment cap.
+ */
+const CHAT_INBOUND_FILE_LIMITS: Record<string, number> = { telegram: 20 * MB };
+
+export function chatInboundFileLimit(adapter: string): number {
+  return Math.min(
+    CHAT_INBOUND_FILE_LIMITS[adapter] ?? MAX_TASK_ATTACHMENT_BYTES,
+    MAX_TASK_ATTACHMENT_BYTES,
+  );
+}
 
 /**
  * One attachment of a buffered chat message. `id` is `<messageId>-<n>` with
@@ -43,7 +61,8 @@ export interface ChatFile {
   attachment: Attachment;
 }
 
-export type ChatFileFailure = { file: ChatFile; reason: string };
+/** `tooLarge` marks a file over the inbound cap; the user gets a reply naming it. */
+export type ChatFileFailure = { file: ChatFile; reason: string; tooLarge?: boolean };
 
 export type FetchedChatFile = { file: ChatFile; path: string; sizeBytes: number; sha256: string };
 
@@ -55,7 +74,7 @@ export type InboundChatFiles = {
   [Symbol.asyncDispose](): Promise<void>;
 };
 
-function formatFileSize(bytes: number): string {
+export function formatFileSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -81,20 +100,71 @@ export function toChatFiles(
 
 /**
  * `[File: <name> (<mime>, <size>) id=<id>]` per file, followed by
- * `(not attached: <reason>)` when the file never reached the task.
+ * `(not attached: <reason>)` when the file never reached the task, and by the
+ * file's note (a voice-note transcript) on the next line.
  */
-export function buildChatAttachmentText(files: ChatFile[], failed: ChatFileFailure[] = []): string {
+export function buildChatAttachmentText(
+  files: ChatFile[],
+  failed: ChatFileFailure[] = [],
+  notes: Map<string, string> = new Map(),
+): string {
   const reasons = new Map(failed.map((f) => [f.file.id, f.reason]));
   return files
     .map((f) => {
       const size = typeof f.size === "number" ? formatFileSize(f.size) : "unknown size";
       const line = `[File: ${f.name} (${f.mimeType ?? "unknown type"}, ${size}) id=${f.id}]`;
       const reason = reasons.get(f.id);
-      return reason ? `${line} (not attached: ${reason})` : line;
+      const note = notes.get(f.id);
+      return [reason ? `${line} (not attached: ${reason})` : line, note].filter(Boolean).join("\n");
     })
     .join("\n");
 }
 
+/**
+ * A sender-chosen file name as an inline code span, so the bot's reply shows it
+ * as literal text and never renders a link, image or heading from it. Backslash
+ * escapes are not enough: the Chat SDK parser still autolinks bare URLs.
+ */
+function markdownLiteral(value: string): string {
+  const text = value.replace(/[\r\n]+/g, " ");
+  const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(longestRun + 1);
+  // CommonMark strips one space from each end of a padded span.
+  const pad = /^[` ]|[` ]$/.test(text) ? " " : "";
+  return `${fence}${pad}${text}${pad}${fence}`;
+}
+
+/** The reply posted to the thread when files were over the inbound cap. */
+export function formatTooLargeReply(failed: ChatFileFailure[]): string {
+  const lines = failed.map((f) => `- ${markdownLiteral(f.file.name)}: ${f.reason}`);
+  return [
+    `Too large to read, so the swarm did not get ${failed.length === 1 ? "this file" : "these files"}:`,
+    ...lines,
+    "Send a smaller file or a link.",
+  ].join("\n");
+}
+
+/**
+ * Transcribe every fetched audio file. Returns one task-text note per file:
+ * the transcript, the failure, or (when no provider is configured) a line
+ * saying so. Never throws.
+ */
+export async function transcribeChatAudio(
+  fetched: FetchedChatFile[],
+): Promise<Map<string, string>> {
+  return transcribeAudioNotes(
+    fetched
+      .filter(({ file }) => file.attachment.type === "audio")
+      .map(({ file, path }) => ({
+        key: file.id,
+        name: file.name,
+        data: Bun.file(path),
+        mimeType: file.mimeType,
+      })),
+    "[chat-sdk]",
+  );
+}
+
 async function readAttachment(attachment: Attachment): Promise<Uint8Array> {
   if (attachment.data instanceof Blob) return new Uint8Array(await attachment.data.arrayBuffer());
   if (attachment.data) return new Uint8Array(attachment.data);
@@ -119,17 +189,25 @@ export async function fetchChatFiles(files: ChatFile[]): Promise<InboundChatFile
   };
   if (files.length === 0) return result;
 
-  const limit = `larger than the ${MAX_TASK_ATTACHMENT_BYTES / (1024 * 1024)} MB limit`;
+  const tooLarge = (file: ChatFile, size: number): ChatFileFailure => {
+    const limit = chatInboundFileLimit(file.adapter);
+    const platform = file.adapter.charAt(0).toUpperCase() + file.adapter.slice(1);
+    return {
+      file,
+      reason: `too large (${formatFileSize(size)}, the limit for files sent to the ${platform} bot is ${formatFileSize(limit)})`,
+      tooLarge: true,
+    };
+  };
   dir = await mkdtemp(join(tmpdir(), "chat-files-"));
   for (const [index, file] of files.entries()) {
-    if (typeof file.size === "number" && file.size > MAX_TASK_ATTACHMENT_BYTES) {
-      result.failed.push({ file, reason: limit });
+    if (typeof file.size === "number" && file.size > chatInboundFileLimit(file.adapter)) {
+      result.failed.push(tooLarge(file, file.size));
       continue;
     }
     try {
       const bytes = await readAttachment(file.attachment);
-      if (bytes.byteLength > MAX_TASK_ATTACHMENT_BYTES) {
-        result.failed.push({ file, reason: limit });
+      if (bytes.byteLength > chatInboundFileLimit(file.adapter)) {
+        result.failed.push(tooLarge(file, bytes.byteLength));
         continue;
       }
       const path = join(dir, String(index));

package/src/integrations/chat-sdk/facts.ts

@@ -0,0 +1,120 @@
+import type { Message, Thread } from "chat";
+
+/** Why a message counts as meant for the swarm. `none`: it reached the router unaddressed. */
+export type ChatAddressedReason =
+  | "dm"
+  | "mention"
+  | "reply-to-bot"
+  | "requester-follow-up"
+  | "none";
+
+/**
+ * Facts about one inbound message that only core can read: the chat it came
+ * from (Telegram `message.raw.chat`) and whether it answers the bot.
+ */
+export interface ChatMessageFacts {
+  /** Platform chat type, such as Telegram `private`, `group` or `supergroup`. */
+  chatType?: string;
+  isForum?: boolean;
+  /** Group or channel title. */
+  title?: string;
+  /** Forum topic: `"<name>"` when the update carries it, else `#<thread id>`. */
+  topic?: string;
+  /** The sender as people know them: `Name (@username)`. */
+  from: string;
+  /** The message replies to one of the bot's own messages. */
+  replyToBot: boolean;
+  /** Start of the message it replies to. */
+  replyToSnippet?: string;
+}
+
+const SNIPPET_MAX = 80;
+
+interface TelegramRawMessage {
+  message_id?: number;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  chat?: { type?: string; title?: string; is_forum?: boolean };
+  from?: { first_name?: string; last_name?: string; username?: string };
+  reply_to_message?: {
+    message_id?: number;
+    from?: { id?: number | string };
+    text?: string;
+    caption?: string;
+    forum_topic_created?: { name?: string };
+  };
+}
+
+function snippet(text: string | undefined): string | undefined {
+  const flat = text?.replace(/\s+/g, " ").trim();
+  if (!flat) return undefined;
+  return flat.length > SNIPPET_MAX ? `${flat.slice(0, SNIPPET_MAX)}...` : flat;
+}
+
+function personLabel(name: string | undefined, username: string | undefined, fallback: string) {
+  if (name && username && name !== username) return `${name} (@${username})`;
+  if (username) return `@${username}`;
+  return name || fallback;
+}
+
+function telegramFacts(raw: TelegramRawMessage, message: Message, botUserId?: string) {
+  const reply = raw.reply_to_message;
+  // In a forum topic every plain message replies to the topic's creation
+  // message, so that reply is the topic, not an answer to anyone.
+  const replyIsTopicRoot =
+    reply !== undefined &&
+    (reply.forum_topic_created !== undefined ||
+      (raw.is_topic_message === true && reply.message_id === raw.message_thread_id));
+  const realReply = reply && !replyIsTopicRoot ? reply : undefined;
+  const topicName = replyIsTopicRoot ? reply?.forum_topic_created?.name : undefined;
+  const name = [raw.from?.first_name, raw.from?.last_name].filter(Boolean).join(" ").trim();
+  return {
+    chatType: raw.chat?.type,
+    isForum: raw.chat?.is_forum === true ? true : undefined,
+    title: raw.chat?.title,
+    topic:
+      raw.is_topic_message === true && raw.message_thread_id !== undefined
+        ? topicName
+          ? `"${topicName}"`
+          : `#${raw.message_thread_id}`
+        : undefined,
+    from: personLabel(name || undefined, raw.from?.username, message.author.userId),
+    replyToBot:
+      realReply?.from?.id !== undefined &&
+      botUserId !== undefined &&
+      String(realReply.from.id) === botUserId,
+    replyToSnippet: snippet(realReply?.text ?? realReply?.caption),
+  } satisfies ChatMessageFacts;
+}
+
+/** Read the chat facts of one message. Telegram reads the raw update; other adapters the SDK message. */
+export function readChatMessageFacts(thread: Thread, message: Message): ChatMessageFacts {
+  const raw = message.raw as TelegramRawMessage | undefined;
+  if (thread.adapter.name === "telegram" && raw && typeof raw === "object") {
+    return telegramFacts(raw, message, thread.adapter.botUserId);
+  }
+  const { fullName, userName, userId } = message.author;
+  return {
+    chatType: thread.isDM ? "dm" : undefined,
+    from: personLabel(fullName || undefined, userName || undefined, userId),
+    replyToBot: message.replyTo?.author.isMe === true,
+    replyToSnippet: snippet(message.replyTo?.text),
+  };
+}
+
+/** One line of facts for the task header: `telegram · supergroup "Life" · from: ... · addressed: ...`. */
+export function formatChatHeaderFacts(
+  adapter: string,
+  facts: ChatMessageFacts,
+  addressed: ChatAddressedReason,
+): string {
+  // Title, topic and sender are user-set: one line each, so none can forge a header line.
+  const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+  const parts = [adapter];
+  if (facts.chatType)
+    parts.push(facts.title ? `${facts.chatType} "${oneLine(facts.title)}"` : facts.chatType);
+  if (facts.isForum) parts.push(facts.topic ? `forum topic ${oneLine(facts.topic)}` : "forum");
+  parts.push(`from: ${oneLine(facts.from)}`, `addressed: ${addressed}`);
+  if (facts.replyToSnippet) parts.push(`reply-to: "${facts.replyToSnippet}"`);
+  return parts.join(" · ");
+}