@desplega.ai/agent-swarm 1.173.0 → 2.0.0

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",
+});

package/src/integrations/chat-sdk/test-hooks.ts

@@ -0,0 +1,37 @@
+/**
+ * Test-only seams for the Chat SDK adapters. Production code never calls
+ * `setChatSdkTestHooks`, so every hook is unset in a running API. The
+ * operator schema rejects `webhookVerifier`, and this module is the only
+ * other way to set one.
+ */
+export interface ChatSdkTestHooks {
+  /**
+   * Replaces the Bot Framework JWT check of the Teams adapter. Tests cannot
+   * mint a Microsoft-signed token, so they inject `() => true`.
+   */
+  teamsWebhookVerifier?: (request: Request, body: string) => boolean | Promise<boolean>;
+  /**
+   * Bot token factory for the Teams adapter, so an outbound send needs no
+   * MSAL call to login.microsoftonline.com.
+   */
+  teamsToken?: () => string;
+  /**
+   * Skips the Discord Gateway loop. The loop logs in through `discord.js`
+   * against the real Discord API, which `apiUrl` does not redirect.
+   */
+  disableDiscordGateway?: boolean;
+  /** Typing keepalive interval, shortened so a test sees several renewals. */
+  typingIntervalMs?: number;
+  /** Typing keepalive hard cap, shortened so a test can reach it. */
+  typingMaxMs?: number;
+}
+
+let hooks: ChatSdkTestHooks = {};
+
+export function setChatSdkTestHooks(next: ChatSdkTestHooks): void {
+  hooks = { ...next };
+}
+
+export function getChatSdkTestHooks(): Readonly<ChatSdkTestHooks> {
+  return hooks;
+}

package/src/integrations/chat-sdk/thread-buffer.ts

@@ -0,0 +1,100 @@
+import type { Attachment } from "chat";
+import { type AdditiveBuffer, createAdditiveBuffer } from "@/tasks/additive-buffer";
+import { trackBackground } from "./background";
+import { flushChatThread } from "./inbound";
+import { stopTypingKeepalive } from "./typing";
+
+/** One inbound message waiting in its thread's buffer. */
+export interface ChatBufferedMessage {
+  messageId: string;
+  channelId: string;
+  /** Mention-stripped text. */
+  text: string;
+  userId: string;
+  userName?: string;
+  botMentioned: boolean;
+  isDirectMessage: boolean;
+  attachments: Attachment[];
+}
+
+const DEFAULT_BUFFER_MS = 10_000;
+
+function configuredBufferMs(): number {
+  const value = Number(process.env.CHAT_SDK_BUFFER_MS);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_BUFFER_MS;
+}
+
+let buffer: AdditiveBuffer<ChatBufferedMessage> | undefined;
+let bufferMs = 0;
+/** Set while shutdown flushes every waiting thread; those flushes keep `dependsOn`. */
+let draining = false;
+/**
+ * Tail of each thread's flush chain. The additive buffer clears a key before
+ * it awaits `onFlush`, so a second flush of one thread can start while the
+ * first still routes, downloads files or creates its task. Chaining keeps the
+ * task order (and `dependsOn`) of one thread; different threads run in parallel.
+ */
+const flushChains = new Map<string, Promise<void>>();
+
+/** Run `work` after every earlier flush of `threadId`. A failed flush does not block the next one. */
+function runInThreadOrder(threadId: string, work: () => Promise<void>): Promise<void> {
+  const previous = flushChains.get(threadId) ?? Promise.resolve();
+  const run = previous.then(work);
+  const tail = run.catch(() => {});
+  flushChains.set(threadId, tail);
+  void tail.then(() => {
+    if (flushChains.get(threadId) === tail) flushChains.delete(threadId);
+  });
+  return run;
+}
+
+/**
+ * Keyed by the raw SDK `thread.id` (`<adapter>:<platform id>`, colons
+ * included); the key is never split. A changed `CHAT_SDK_BUFFER_MS` applies
+ * once no thread is waiting on the old timer.
+ */
+function getBuffer(): AdditiveBuffer<ChatBufferedMessage> {
+  const ms = configuredBufferMs();
+  if (!buffer || (ms !== bufferMs && buffer.keys().length === 0)) {
+    bufferMs = ms;
+    buffer = createAdditiveBuffer<ChatBufferedMessage>({
+      timeoutMs: ms,
+      label: "chat",
+      onFlush: async (items, threadId, reason) => {
+        // Read now: `draining` can change while this flush waits in the chain.
+        const immediate = reason === "manual" && !draining;
+        // Tracked so shutdown drains timer-driven flushes before the DB closes.
+        const work = runInThreadOrder(threadId, () => flushChatThread(threadId, items, immediate));
+        trackBackground(work);
+        // A failed flush created no task, so no relay will stop the indicator.
+        await work.catch(() => stopTypingKeepalive(threadId));
+      },
+    });
+  }
+  return buffer;
+}
+
+/** Add a message to its thread's buffer and reset the debounce timer. */
+export function bufferChatMessage(threadId: string, item: ChatBufferedMessage): void {
+  getBuffer().enqueue(threadId, item);
+}
+
+/** Flush now with no `dependsOn` (the `!now` command). */
+export async function instantFlushChat(threadId: string): Promise<void> {
+  await getBuffer().instantFlush(threadId);
+}
+
+export function isChatThreadBuffered(threadId: string): boolean {
+  return buffer?.isBuffered(threadId) ?? false;
+}
+
+/** Shutdown: turn every waiting thread into its task instead of dropping it. */
+export async function flushAllChatBuffers(): Promise<void> {
+  if (!buffer) return;
+  draining = true;
+  try {
+    for (const threadId of buffer.keys()) await buffer.instantFlush(threadId);
+  } finally {
+    draining = false;
+  }
+}

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

@@ -0,0 +1,65 @@
+import { errorMessage } from "./logger";
+import { getChatInstance, isChatSdkStopping } from "./runtime";
+import { assertTrustedChatTarget } from "./teams-origin";
+import { getChatSdkTestHooks } from "./test-hooks";
+
+/** Telegram shows one typing action for about 5 s, so renew it before that. */
+const TYPING_INTERVAL_MS = 4_000;
+/** Hard cap: a task that never relays must not show typing forever. */
+const TYPING_MAX_MS = 15 * 60 * 1000;
+
+const keepalives = new Map<string, ReturnType<typeof setInterval>>();
+
+/**
+ * Show the typing indicator in `threadId` until `stopTypingKeepalive`, the
+ * hard cap, or the adapter stops. Idempotent per thread id. Adapters without
+ * `startTyping` and untrusted Teams service URLs are skipped.
+ */
+export function startTypingKeepalive(adapter: string, threadId: string): void {
+  if (keepalives.has(threadId)) return;
+  // A shutdown flush creates tasks too; no indicator for a reply that comes after a restart.
+  if (isChatSdkStopping()) return;
+  // Typing sends the Teams bot token to the service URL in the thread id.
+  try {
+    assertTrustedChatTarget(threadId);
+  } catch {
+    return;
+  }
+  if (typeof getChatInstance(adapter)?.getAdapter(adapter)?.startTyping !== "function") return;
+
+  const hooks = getChatSdkTestHooks();
+  const maxMs = hooks.typingMaxMs ?? TYPING_MAX_MS;
+  const startedAt = Date.now();
+  let warned = false;
+  const sendTyping = async (): Promise<void> => {
+    const target = getChatInstance(adapter)?.getAdapter(adapter);
+    if (Date.now() - startedAt >= maxMs || typeof target?.startTyping !== "function") {
+      stopTypingKeepalive(threadId);
+      return;
+    }
+    try {
+      await target.startTyping(threadId);
+    } catch (error) {
+      if (warned) return;
+      warned = true;
+      console.warn(`[chat-sdk] Typing indicator failed for ${threadId}: ${errorMessage(error)}`);
+    }
+  };
+  const timer = setInterval(() => void sendTyping(), hooks.typingIntervalMs ?? TYPING_INTERVAL_MS);
+  timer.unref();
+  keepalives.set(threadId, timer);
+  void sendTyping();
+}
+
+export function stopTypingKeepalive(threadId: string): void {
+  const timer = keepalives.get(threadId);
+  if (!timer) return;
+  clearInterval(timer);
+  keepalives.delete(threadId);
+}
+
+/** Stop every keepalive. For `stopChatSdk`. */
+export function stopAllTypingKeepalives(): void {
+  for (const timer of keepalives.values()) clearInterval(timer);
+  keepalives.clear();
+}

package/src/pages/version.ts

@@ -1,4 +1,5 @@
-import { createPageVersion, getPage, getPageVersions } from "../be/db";
+import { createPageVersion, getPage } from "../be/db";
+import { getPageEditCounter } from "../be/db/page-versions";
 import type { PageSnapshot, PageVersion } from "../types";
 
 /**
@@ -8,7 +9,7 @@ import type { PageSnapshot, PageVersion } from "../types";
  * Mirrors `snapshotWorkflow` (src/workflows/version.ts:13-44).
  *
  * 1. Load current page state
- * 2. Get max version number for this page (page_versions ORDER BY version DESC)
+ * 2. Get max version number for this page (MAX(page_versions.version))
  * 3. Insert page_versions row with version+1 and the pre-update snapshot
  *
  * Throws on missing parent. Callers in HTTP handlers wrap this in a try/catch
@@ -24,9 +25,7 @@ export async function snapshotPage(
     throw new Error(`Page ${pageId} not found — cannot create snapshot`);
   }
 
-  const existingVersions = await getPageVersions(pageId);
-  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
-  const nextVersion = maxVersion + 1;
+  const nextVersion = await getPageEditCounter(pageId);
 
   const snapshot: PageSnapshot = {
     title: page.title,