@desplega.ai/agent-swarm 1.172.0 → 2.0.0

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

@@ -0,0 +1,243 @@
+import type { Lock, Message, QueueEntry, SerializedMessage, StateAdapter } from "chat";
+import { getDbClient } from "@/be/db";
+
+/**
+ * Chat SDK `StateAdapter` backed by the dedicated `chat_*` tables (migration
+ * 213). Every method is one statement or one short transaction through the
+ * async DB seam, so each operation is atomic by construction.
+ *
+ * Expiry columns hold epoch milliseconds. A `ttlMs` of 0 or undefined means no
+ * expiry. Queue entries are not filtered by `expiresAt` here: the Chat core
+ * drops expired entries itself on dequeue.
+ */
+
+function encode(value: unknown): string {
+  return JSON.stringify(value ?? null);
+}
+
+function decode<T>(value: string): T {
+  return JSON.parse(value) as T;
+}
+
+function expiresAtFor(ttlMs: number | undefined, now: number): number | null {
+  return ttlMs ? now + ttlMs : null;
+}
+
+export class SqliteChatState implements StateAdapter {
+  async connect(): Promise<void> {}
+
+  /**
+   * No-op on purpose. The memory adapter clears subscriptions on disconnect
+   * because it is memory. A durable store keeps "we own this thread" across
+   * restarts, and locks expire by TTL.
+   */
+  async disconnect(): Promise<void> {}
+
+  async subscribe(threadId: string): Promise<void> {
+    await getDbClient().run("INSERT OR IGNORE INTO chat_subscriptions (thread_id) VALUES (?)", [
+      threadId,
+    ]);
+  }
+
+  async unsubscribe(threadId: string): Promise<void> {
+    await getDbClient().run("DELETE FROM chat_subscriptions WHERE thread_id = ?", [threadId]);
+  }
+
+  async isSubscribed(threadId: string): Promise<boolean> {
+    const row = await getDbClient().get<{ one: number }>(
+      "SELECT 1 AS one FROM chat_subscriptions WHERE thread_id = ?",
+      [threadId],
+    );
+    return row !== null;
+  }
+
+  async acquireLock(threadId: string, ttlMs: number): Promise<Lock | null> {
+    const now = Date.now();
+    const lock: Lock = { threadId, token: crypto.randomUUID(), expiresAt: now + ttlMs };
+    const result = await getDbClient().run(
+      `INSERT INTO chat_locks (thread_id, token, expires_at) VALUES (?, ?, ?)
+       ON CONFLICT(thread_id) DO UPDATE SET
+         token = excluded.token,
+         expires_at = excluded.expires_at
+       WHERE chat_locks.expires_at <= ?`,
+      [threadId, lock.token, lock.expiresAt, now],
+    );
+    return result.changes > 0 ? lock : null;
+  }
+
+  async extendLock(lock: Lock, ttlMs: number): Promise<boolean> {
+    const now = Date.now();
+    const result = await getDbClient().run(
+      "UPDATE chat_locks SET expires_at = ? WHERE thread_id = ? AND token = ? AND expires_at > ?",
+      [now + ttlMs, lock.threadId, lock.token, now],
+    );
+    return result.changes > 0;
+  }
+
+  async releaseLock(lock: Lock): Promise<void> {
+    await getDbClient().run("DELETE FROM chat_locks WHERE thread_id = ? AND token = ?", [
+      lock.threadId,
+      lock.token,
+    ]);
+  }
+
+  async forceReleaseLock(threadId: string): Promise<void> {
+    await getDbClient().run("DELETE FROM chat_locks WHERE thread_id = ?", [threadId]);
+  }
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const now = Date.now();
+    const row = await getDbClient().get<{ value: string; expires_at: number | null }>(
+      "SELECT value, expires_at FROM chat_state_kv WHERE key = ?",
+      [key],
+    );
+    if (!row) return null;
+    if (row.expires_at !== null && row.expires_at <= now) {
+      await getDbClient().run("DELETE FROM chat_state_kv WHERE key = ? AND expires_at <= ?", [
+        key,
+        now,
+      ]);
+      return null;
+    }
+    return decode<T>(row.value);
+  }
+
+  async set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> {
+    await getDbClient().run(
+      `INSERT INTO chat_state_kv (key, value, expires_at) VALUES (?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`,
+      [key, encode(value), expiresAtFor(ttlMs, Date.now())],
+    );
+  }
+
+  async setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean> {
+    const now = Date.now();
+    const result = await getDbClient().run(
+      `INSERT INTO chat_state_kv (key, value, expires_at) VALUES (?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at
+       WHERE chat_state_kv.expires_at IS NOT NULL AND chat_state_kv.expires_at <= ?`,
+      [key, encode(value), expiresAtFor(ttlMs, now), now],
+    );
+    return result.changes > 0;
+  }
+
+  async delete(key: string): Promise<void> {
+    await getDbClient().run("DELETE FROM chat_state_kv WHERE key = ?", [key]);
+  }
+
+  async appendToList(
+    key: string,
+    value: unknown,
+    options?: { maxLength?: number; ttlMs?: number },
+  ): Promise<void> {
+    const now = Date.now();
+    const expiresAt = expiresAtFor(options?.ttlMs, now);
+    await getDbClient().transaction(async (tx) => {
+      // An expired list starts over, like the memory adapter.
+      await tx.run(
+        "DELETE FROM chat_lists WHERE key = ? AND expires_at IS NOT NULL AND expires_at <= ?",
+        [key, now],
+      );
+      await tx.run(
+        `INSERT INTO chat_lists (key, seq, value, expires_at)
+         VALUES (?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM chat_lists WHERE key = ?), ?, ?)`,
+        [key, key, encode(value), expiresAt],
+      );
+      if (options?.maxLength && options.maxLength > 0) {
+        await tx.run(
+          `DELETE FROM chat_lists WHERE key = ? AND seq NOT IN (
+             SELECT seq FROM chat_lists WHERE key = ? ORDER BY seq DESC LIMIT ?
+           )`,
+          [key, key, options.maxLength],
+        );
+      }
+      await tx.run("UPDATE chat_lists SET expires_at = ? WHERE key = ?", [expiresAt, key]);
+    });
+  }
+
+  async getList<T = unknown>(key: string): Promise<T[]> {
+    const rows = await getDbClient().query<{ value: string }>(
+      `SELECT value FROM chat_lists
+       WHERE key = ? AND (expires_at IS NULL OR expires_at > ?)
+       ORDER BY seq ASC`,
+      [key, Date.now()],
+    );
+    return rows.map((row) => decode<T>(row.value));
+  }
+
+  async enqueue(threadId: string, entry: QueueEntry, maxSize: number): Promise<number> {
+    return await getDbClient().transaction(async (tx) => {
+      await tx.run("INSERT INTO chat_queue (thread_id, entry) VALUES (?, ?)", [
+        threadId,
+        encode(entry),
+      ]);
+      await tx.run(
+        `DELETE FROM chat_queue WHERE thread_id = ? AND id NOT IN (
+           SELECT id FROM chat_queue WHERE thread_id = ? ORDER BY id DESC LIMIT ?
+         )`,
+        [threadId, threadId, Math.max(maxSize, 0)],
+      );
+      const row = await tx.get<{ depth: number }>(
+        "SELECT COUNT(*) AS depth FROM chat_queue WHERE thread_id = ?",
+        [threadId],
+      );
+      return row?.depth ?? 0;
+    });
+  }
+
+  async dequeue(threadId: string): Promise<QueueEntry | null> {
+    return await getDbClient().transaction(async (tx) => {
+      const row = await tx.get<{ id: number; entry: string }>(
+        "SELECT id, entry FROM chat_queue WHERE thread_id = ? ORDER BY id ASC LIMIT 1",
+        [threadId],
+      );
+      if (!row) return null;
+      await tx.run("DELETE FROM chat_queue WHERE id = ?", [row.id]);
+      return decode<QueueEntry>(row.entry);
+    });
+  }
+
+  async queueDepth(threadId: string): Promise<number> {
+    const row = await getDbClient().get<{ depth: number }>(
+      "SELECT COUNT(*) AS depth FROM chat_queue WHERE thread_id = ?",
+      [threadId],
+    );
+    return row?.depth ?? 0;
+  }
+}
+
+/**
+ * Delete expired state rows. Called from the Phase 3 watcher tick; exported
+ * now for tests.
+ */
+export async function sweepExpired(now: number = Date.now()): Promise<void> {
+  await getDbClient().transaction(async (tx) => {
+    await tx.run("DELETE FROM chat_state_kv WHERE expires_at IS NOT NULL AND expires_at <= ?", [
+      now,
+    ]);
+    await tx.run("DELETE FROM chat_lists WHERE expires_at IS NOT NULL AND expires_at <= ?", [now]);
+    await tx.run("DELETE FROM chat_locks WHERE expires_at <= ?", [now]);
+  });
+}
+
+/**
+ * Key prefix of the SDK `ThreadHistoryCache` (chat 4.41): the per-thread
+ * message list for adapters with `persistThreadHistory` (Telegram, WhatsApp).
+ * Pinned by `chat-sdk-commands.test.ts` against the real SDK.
+ */
+export const SDK_THREAD_HISTORY_PREFIX = "msg-history:";
+
+/**
+ * The thread history the SDK persisted here, oldest first. The adapters that
+ * persist it answer `fetchMessages` from process memory, and the SDK reads this
+ * store only when that memory is empty. After a restart the memory holds just
+ * the newest message, so callers merge both sources themselves.
+ */
+export async function readPersistedThreadHistory(threadId: string): Promise<Message[]> {
+  const rows = await new SqliteChatState().getList<SerializedMessage>(
+    `${SDK_THREAD_HISTORY_PREFIX}${threadId}`,
+  );
+  if (rows.length === 0) return [];
+  const { Message: MessageClass } = await import("chat");
+  return rows.map((row) => MessageClass.fromJSON(row));
+}

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

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { getPublicMcpBaseUrl } from "@/utils/constants";
+import { isEnvFlagEnabled } from "@/utils/env-flag";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { resolveAdapterApiUrl } from "./adapters";
+import { CHAT_SDK_ADAPTER_NAMES, type ChatSdkAdapterName, getChatSdkConfig } from "./config";
+import { fetchDiscordGuilds } from "./discord-api";
+import { getChatSdkHealth } from "./runtime";
+import { isAdapterEntryEnabled } from "./schema";
+import { callTelegramBotApi, TelegramBotApiError } from "./telegram-api";
+
+/**
+ * Read-only Chat SDK status for the dashboard card, and the Telegram
+ * register-webhook action. Never returns secret values: configured state comes
+ * from adapter names and the non-secret `mode` field only.
+ */
+
+export const ChatSdkStatusSchema = z.object({
+  enabled: z.boolean(),
+  slackClash: z.boolean(),
+  /** Config problem that stops every adapter from starting (bad JSON, missing `$config` row). */
+  error: z.string().optional(),
+  adapters: z.array(
+    z.object({
+      name: z.enum(CHAT_SDK_ADAPTER_NAMES),
+      configured: z.boolean(),
+      /** False when the entry carries `enabled: false`: configured and kept, not started. */
+      enabled: z.boolean(),
+      /** `incomplete`: present in `CHAT_SDK_ADAPTERS` with a missing field or an unresolvable `$config`; `error` names it. */
+      health: z.enum(["ok", "error", "disabled", "incomplete"]),
+      error: z.string().optional(),
+      webhookUrl: z.string(),
+      mode: z.string().optional(),
+      gateway: z
+        .object({
+          state: z.enum(["running", "backoff", "stopped"]),
+          since: z.string(),
+          restarts: z.number(),
+        })
+        .optional(),
+      /** Discord only, while the Gateway runs: the servers the bot was invited to. */
+      guilds: z.object({ count: z.number(), names: z.array(z.string()) }).optional(),
+    }),
+  ),
+});
+
+export type ChatSdkStatus = z.infer<typeof ChatSdkStatusSchema>;
+export type ChatSdkAdapterStatus = ChatSdkStatus["adapters"][number];
+
+/** Schema defaults, repeated here because the raw JSON may omit `mode`. */
+const DEFAULT_MODES: Partial<Record<ChatSdkAdapterName, string>> = {
+  telegram: "webhook",
+  slack: "webhook",
+};
+
+const NOT_RUNNING =
+  "The adapter is starting, or the last configuration save is still applying. Refresh in a few seconds.";
+
+const SLACK_CLASH_CAUSE =
+  "the Slack adapter conflicts with the built-in Slack integration (set SLACK_DISABLE=true)";
+
+/** Bound on error text in the status payload. Adapter and parser errors can be long. */
+const MAX_STATUS_ERROR_CHARS = 300;
+
+function statusError(message: string): string {
+  return scrubSecrets(message).slice(0, MAX_STATUS_ERROR_CHARS);
+}
+
+/**
+ * The raw `CHAT_SDK_ADAPTERS` object, without validation or `$config`
+ * resolution. Lets the card show which adapters an operator configured even
+ * while the config fails to resolve. Empty on invalid JSON.
+ */
+function readRawAdapters(): Partial<Record<ChatSdkAdapterName, Record<string, unknown>>> {
+  const raw = process.env.CHAT_SDK_ADAPTERS?.trim();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: Partial<Record<ChatSdkAdapterName, Record<string, unknown>>> = {};
+    for (const name of CHAT_SDK_ADAPTER_NAMES) {
+      const value = (parsed as Record<string, unknown>)[name];
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        out[name] = value as Record<string, unknown>;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+export function chatSdkWebhookUrl(name: ChatSdkAdapterName): string {
+  return `${getPublicMcpBaseUrl()}/api/integrations/chat/${name}/webhook`;
+}
+
+/**
+ * The Discord bot's servers, only while its Gateway runs (a bot that is in no
+ * server is the usual "it does not answer" cause). The token comes from the
+ * resolved config, never from the status payload.
+ */
+async function discordGuildsFor(
+  config: Awaited<ReturnType<typeof getChatSdkConfig>>,
+  health: ReturnType<typeof getChatSdkHealth>["discord"],
+): Promise<ChatSdkAdapterStatus["guilds"]> {
+  if (health?.status !== "ok" || health.gateway?.state !== "running") return undefined;
+  const raw = config.adapters.discord?.botToken;
+  const token = typeof raw === "function" ? await (raw as () => Promise<unknown>)() : raw;
+  if (typeof token !== "string" || token.length === 0) return undefined;
+  return fetchDiscordGuilds(token);
+}
+
+export async function getChatSdkStatus(): Promise<ChatSdkStatus> {
+  const config = await getChatSdkConfig();
+  const raw = readRawAdapters();
+  const runtimeHealth = getChatSdkHealth();
+  const slackClash = raw.slack !== undefined && !isEnvFlagEnabled("SLACK_DISABLE", false);
+  // A config error or a Slack clash stops `startChatSdk` before any adapter.
+  const blockedCause =
+    config.error ?? (config.enabled && slackClash ? SLACK_CLASH_CAUSE : undefined);
+  const discordGuilds = await discordGuildsFor(config, runtimeHealth.discord);
+  const adapters = CHAT_SDK_ADAPTER_NAMES.map((name): ChatSdkAdapterStatus => {
+    const configured = raw[name] !== undefined;
+    const enabled = isAdapterEntryEnabled(raw[name]);
+    const current = runtimeHealth[name];
+    const incomplete = config.incomplete?.[name];
+    const rawMode = raw[name]?.mode;
+    const mode =
+      typeof rawMode === "string" ? rawMode : configured ? DEFAULT_MODES[name] : undefined;
+    let health: ChatSdkAdapterStatus["health"] = "disabled";
+    let error: string | undefined;
+    if (current) {
+      health = current.status;
+      // A Discord Gateway in backoff keeps health `ok` (the webhook still
+      // works); its last warning says why the listener keeps failing.
+      const showWarning = current.status === "error" || current.gateway?.state === "backoff";
+      error = current.error ?? (showWarning ? current.lastWarning : undefined);
+    } else if (incomplete) {
+      // Saved with a missing field, or a `$config` row that does not exist.
+      health = "incomplete";
+      error = incomplete;
+    } else if (configured && !enabled) {
+      error = "Turned off on the card. The configuration is kept.";
+    } else if (config.enabled && configured) {
+      error = blockedCause ? `Not started: ${blockedCause}` : NOT_RUNNING;
+    }
+    return {
+      name,
+      configured,
+      enabled,
+      health,
+      ...(error ? { error: statusError(error) } : {}),
+      webhookUrl: chatSdkWebhookUrl(name),
+      ...(mode ? { mode } : {}),
+      ...(current?.gateway ? { gateway: current.gateway } : {}),
+      ...(name === "discord" && discordGuilds ? { guilds: discordGuilds } : {}),
+    };
+  });
+  return {
+    enabled: config.enabled,
+    slackClash,
+    ...(config.error ? { error: statusError(config.error) } : {}),
+    adapters,
+  };
+}
+
+/** `getWebhookInfo` result as Telegram returns it (subset; unknown keys pass through). */
+export type TelegramWebhookInfo = Record<string, unknown> & { url: string };
+
+export class ChatSdkActionError extends Error {
+  constructor(
+    message: string,
+    readonly status: 400 | 502,
+  ) {
+    super(message);
+    this.name = "ChatSdkActionError";
+  }
+}
+
+async function callBotApi(
+  baseUrl: string,
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<unknown> {
+  try {
+    return await callTelegramBotApi(baseUrl, token, method, body);
+  } catch (error) {
+    if (error instanceof TelegramBotApiError) throw new ChatSdkActionError(error.message, 502);
+    throw error;
+  }
+}
+
+/**
+ * Point the Telegram bot at this swarm's public webhook URL with the
+ * configured secret token, then return `getWebhookInfo`. The Bot API base is
+ * the one the adapter uses (`resolveAdapterApiUrl`), so tests and local QA hit
+ * the fake Bot API.
+ */
+export async function registerTelegramWebhook(): Promise<{
+  webhookUrl: string;
+  webhookInfo: TelegramWebhookInfo;
+}> {
+  const config = await getChatSdkConfig();
+  if (!config.enabled) {
+    throw new ChatSdkActionError(
+      "The Chat SDK channel is disabled (CHAT_SDK_ENABLED is not true). Enable it and restart the API first",
+      400,
+    );
+  }
+  if (config.error) throw new ChatSdkActionError(statusError(config.error), 400);
+  const telegram = config.adapters.telegram;
+  if (!telegram) {
+    throw new ChatSdkActionError("Telegram is not configured in CHAT_SDK_ADAPTERS", 400);
+  }
+  if (telegram.mode !== "webhook") {
+    throw new ChatSdkActionError(
+      "Telegram runs in polling mode; a registered webhook would stop polling",
+      400,
+    );
+  }
+  const secretToken = telegram.secretToken;
+  if (typeof secretToken !== "string" || secretToken.length === 0) {
+    throw new ChatSdkActionError("Telegram webhook mode needs a secretToken", 400);
+  }
+  const rawToken = telegram.botToken;
+  const token =
+    typeof rawToken === "function" ? await (rawToken as () => Promise<string>)() : rawToken;
+  if (typeof token !== "string" || token.length === 0) {
+    throw new ChatSdkActionError("Telegram botToken is empty", 400);
+  }
+  const baseUrl = resolveAdapterApiUrl("telegram");
+  const webhookUrl = chatSdkWebhookUrl("telegram");
+  await callBotApi(baseUrl, token, "setWebhook", { url: webhookUrl, secret_token: secretToken });
+  const info = await callBotApi(baseUrl, token, "getWebhookInfo", {});
+  if (
+    info === null ||
+    typeof info !== "object" ||
+    typeof (info as { url?: unknown }).url !== "string"
+  ) {
+    throw new ChatSdkActionError("Telegram getWebhookInfo returned an unexpected result", 502);
+  }
+  return { webhookUrl, webhookInfo: info as TelegramWebhookInfo };
+}

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

@@ -0,0 +1,58 @@
+import { getLatestLeadTaskByContextKey } from "@/be/db";
+import { requestSteering, SteeringRequestError } from "@/be/steering";
+import type { AgentTask, SteerResult } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { isSteeringEnabled } from "@/utils/steering-enabled";
+
+export interface ChatThreadSteeringResult {
+  task: AgentTask;
+  result: SteerResult;
+}
+
+/**
+ * Steer the lead's in-progress task on this thread with a new message. Same
+ * rule as the Slack default (`SLACK_THREAD_STEERING=lead`, queue mode) as
+ * constants: `isSteeringEnabled()` is the only switch. Returns null when the
+ * caller should buffer the message into a follow-up task instead.
+ */
+export async function requestChatThreadSteering(args: {
+  contextKey: string;
+  message: string;
+}): Promise<ChatThreadSteeringResult | null> {
+  if (!isSteeringEnabled()) return null;
+
+  const task = await getLatestLeadTaskByContextKey(args.contextKey, "chat");
+  if (!task || task.status !== "in_progress") return null;
+
+  try {
+    const result = await requestSteering({
+      taskId: task.id,
+      message: args.message,
+      mode: "queue",
+      onUnsupported: "degrade",
+      source: "chat",
+      createdByKind: "user",
+    });
+    return { task, result };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const what = error instanceof SteeringRequestError ? "was refused" : "failed";
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] Steering task ${task.id} ${what} (${detail}); creating a follow-up task`,
+      ),
+    );
+    return null;
+  }
+}
+
+/** Thread acknowledgement for the steering outcome. Constants, not prompts. */
+export function formatChatSteeringAck(result: SteerResult): string {
+  if (result.outcome === "promoted") return "_Your message was queued as a follow-up task._";
+  if (result.degradedFrom) {
+    return "_Interrupt steering is unavailable for this task, so your message was queued._";
+  }
+  return result.outcome === "steered"
+    ? "_Your message was sent to the active task._"
+    : "_Your message was queued for the active task._";
+}

package/src/integrations/chat-sdk/teams-origin.ts

@@ -0,0 +1,77 @@
+import { readApiUrlOverrides } from "./config";
+
+/**
+ * Bot Framework Connector hosts for Teams: public cloud, GCC, GCC High, DoD
+ * and the China cloud. The same set as `TRUSTED_CONNECTOR_HOSTS` in
+ * `@chat-adapter/teams` (its standalone connector API), minus the loopback
+ * Emulator exception. The adapter's own send path does not check the host.
+ */
+const TRUSTED_TEAMS_SERVICE_HOSTS = new Set([
+  "smba.trafficmanager.net",
+  "smba.infra.gcc.teams.microsoft.com",
+  "smba.infra.gov.teams.microsoft.us",
+  "smba.infra.dod.teams.microsoft.us",
+  "msteams.botframework.azure.cn",
+]);
+
+/** A Teams service URL that is not a Bot Framework host. Nothing was sent. */
+export class UntrustedTeamsServiceUrlError extends Error {
+  constructor(detail: string) {
+    super(`Refusing to send the Teams bot token: ${detail}`);
+    this.name = "UntrustedTeamsServiceUrlError";
+  }
+}
+
+function originOf(value: string): string | undefined {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The Teams adapter sends the bot token to the service URL of the target
+ * conversation. Trusted: https on a Bot Framework host, or the origin of the
+ * env-only `CHAT_SDK_API_URL_OVERRIDES.teams` (tests and emulators). Every
+ * other origin, loopback included, is refused.
+ */
+export function isTrustedTeamsServiceUrl(serviceUrl: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(serviceUrl);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:" && TRUSTED_TEAMS_SERVICE_HOSTS.has(url.hostname.toLowerCase())) {
+    return true;
+  }
+  const override = readApiUrlOverrides().teams;
+  return override !== undefined && originOf(override) === url.origin;
+}
+
+/**
+ * Throw `UntrustedTeamsServiceUrlError` unless the Teams thread or channel id
+ * (`teams:<base64url conversation>:<base64url serviceUrl>[:<type>]`) carries a
+ * trusted service URL. Call it before every Teams call that takes an id from
+ * outside the adapter. Ids of other adapters pass.
+ */
+export function assertTrustedChatTarget(id: string): void {
+  const parts = id.split(":");
+  if (parts[0] !== "teams") return;
+  const encoded = parts[2];
+  if ((parts.length !== 3 && parts.length !== 4) || !encoded) {
+    throw new UntrustedTeamsServiceUrlError("the Teams id is malformed");
+  }
+  assertTrustedTeamsServiceUrl(Buffer.from(encoded, "base64url").toString("utf-8"));
+}
+
+export function assertTrustedTeamsServiceUrl(serviceUrl: string): void {
+  if (isTrustedTeamsServiceUrl(serviceUrl)) return;
+  const origin = originOf(serviceUrl);
+  throw new UntrustedTeamsServiceUrlError(
+    origin && origin !== "null"
+      ? `${origin} is not a Microsoft Bot Framework service host`
+      : "the service URL is not a valid URL",
+  );
+}

package/src/integrations/chat-sdk/telegram-api.ts

@@ -0,0 +1,56 @@
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { errorMessage } from "./logger";
+
+const TELEGRAM_TIMEOUT_MS = 10_000;
+
+/** A Bot API call that did not return `ok: true`. The message never carries the token. */
+export class TelegramBotApiError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TelegramBotApiError";
+  }
+}
+
+/**
+ * One Telegram Bot API call. Shared by the register-webhook action and the
+ * command registration at adapter start, so both hit the same base URL
+ * (`resolveAdapterApiUrl`) and scrub the token out of every error.
+ */
+export async function callTelegramBotApi(
+  baseUrl: string,
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<unknown> {
+  let response: Response;
+  try {
+    response = await fetch(`${baseUrl.replace(/\/+$/, "")}/bot${token}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TELEGRAM_TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      throw new TelegramBotApiError(
+        `Telegram ${method} failed: no response from the Bot API within ${TELEGRAM_TIMEOUT_MS / 1000} s`,
+      );
+    }
+    // Fetch errors can echo the URL, which carries the bot token.
+    throw new TelegramBotApiError(
+      `Telegram ${method} failed: ${scrubSecrets(errorMessage(error).replaceAll(token, "[REDACTED]"))}`,
+    );
+  }
+  const payload = (await response.json().catch(() => null)) as {
+    ok?: boolean;
+    result?: unknown;
+    description?: string;
+  } | null;
+  if (!response.ok || !payload?.ok) {
+    const description = payload?.description ?? `HTTP ${response.status}`;
+    throw new TelegramBotApiError(
+      `Telegram ${method} failed: ${scrubSecrets(description.replaceAll(token, "[REDACTED]"))}`,
+    );
+  }
+  return payload.result;
+}

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

@@ -0,0 +1,16 @@
+import { registerTemplate } from "@/prompts/registry";
+
+registerTemplate({
+  eventType: "chat.message.thread_context",
+  header: "",
+  defaultBody: `<thread_context>
+{{thread_messages}}
+</thread_context>`,
+  variables: [
+    {
+      name: "thread_messages",
+      description: "Formatted Chat SDK thread messages (user: text pairs)",
+    },
+  ],
+  category: "system",
+});