@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/slack/external-channel.ts

@@ -0,0 +1,309 @@
+import type { WebClient } from "@slack/web-api";
+import { claimKv, deleteKv, sweepExpiredKv, upsertKv } from "../be/db";
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { slackCode, slackMissingScopeMessage } from "./channel-join";
+
+/**
+ * External (Slack Connect) channel detection and enforcement.
+ *
+ * A channel is external when `conversations.info` returns `is_ext_shared` or
+ * `is_pending_ext_shared`, or when the event envelope carries
+ * `is_ext_shared_channel: true`. `is_shared` / `is_org_shared` alone are
+ * internal (Enterprise Grid org-shared channels).
+ *
+ * `SLACK_BLOCK_EXTERNAL_CHANNELS` is read at call time so a dashboard change
+ * applies without a restart.
+ */
+
+export type ChannelExternality = "external" | "internal" | "unknown";
+export type ExternalChannelTrigger = "joined" | "shared" | "boot-scan";
+/** Why a channel is blocked: Slack says it is external, or Slack could not confirm it is not. */
+export type ChannelBlockReason = "external" | "unverified";
+
+const EXTERNALITY_TTL_MS = 10 * 60 * 1000;
+const EXTERNALITY_CACHE_MAX = 500;
+const ALERT_DEDUPE_MS = 60 * 60 * 1000;
+/** A reservation whose post never settles (crash mid-post) frees the key after this. */
+const ALERT_SENDING_TTL_MS = 2 * 60 * 1000;
+/** Durable alert dedupe in kv_entries, so a restart does not repeat alerts. */
+export const EXTERNAL_ALERT_KV_NAMESPACE = "slack-external-alert";
+
+const externalityCache = new Map<string, { value: "external" | "internal"; expiresAt: number }>();
+// Bumped on every invalidation or positive external evidence. A lookup that
+// started under an older generation must not overwrite the newer state.
+const channelGeneration = new Map<string, number>();
+let generationCounter = 0;
+
+export const EXTERNAL_CHANNEL_BLOCKED_REPLY =
+  "This channel is shared with another organization. The swarm does not work here.";
+
+export function externalChannelToolError(
+  channelId: string,
+  reason: ChannelBlockReason = "external",
+): string {
+  if (reason === "unverified") {
+    return `Could not verify that channel ${channelId} is internal to this organization. SLACK_BLOCK_EXTERNAL_CHANNELS blocks swarm messages there until Slack confirms it. Try again later.`;
+  }
+  return `Channel ${channelId} is shared with another organization. SLACK_BLOCK_EXTERNAL_CHANNELS blocks swarm messages there.`;
+}
+
+export function isBlockExternalEnabled(): boolean {
+  return isEnvFlagEnabled("SLACK_BLOCK_EXTERNAL_CHANNELS", false);
+}
+
+/** Reset in-memory caches between tests. Durable alert state lives in kv_entries. */
+export function resetExternalChannelStateForTesting(): void {
+  externalityCache.clear();
+  channelGeneration.clear();
+}
+
+/** Insert into an insertion-ordered Map, evicting the oldest entry at the cap. */
+function setBounded<V>(map: Map<string, V>, key: string, value: V): void {
+  map.delete(key);
+  if (map.size >= EXTERNALITY_CACHE_MAX) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+  map.set(key, value);
+}
+
+function bumpGeneration(channelId: string): void {
+  generationCounter += 1;
+  setBounded(channelGeneration, channelId, generationCounter);
+}
+
+export function invalidateChannelExternality(channelId: string): void {
+  externalityCache.delete(channelId);
+  bumpGeneration(channelId);
+}
+
+/**
+ * Records positive evidence that a channel is external (for example an event
+ * envelope with `is_ext_shared_channel: true`), so later outbound checks block
+ * without waiting for the cached internal value to expire.
+ */
+export function recordExternalChannel(channelId: string): void {
+  bumpGeneration(channelId);
+  setBounded(externalityCache, channelId, {
+    value: "external",
+    expiresAt: Date.now() + EXTERNALITY_TTL_MS,
+  });
+}
+
+/**
+ * Looks up whether a channel is external. Known results are cached for 10
+ * minutes; an API error returns "unknown" and is not cached. A result whose
+ * channel was invalidated or marked external while the lookup was in flight
+ * is not cached: the newer state wins, and an invalidated lookup returns
+ * "unknown".
+ */
+export async function getChannelExternality(
+  client: WebClient,
+  channelId: string,
+): Promise<ChannelExternality> {
+  const cached = externalityCache.get(channelId);
+  if (cached && cached.expiresAt > Date.now()) return cached.value;
+  if (cached) externalityCache.delete(channelId);
+
+  const generation = channelGeneration.get(channelId);
+  let value: "external" | "internal";
+  try {
+    const resp = await client.conversations.info({ channel: channelId });
+    const ch = (resp.channel ?? {}) as {
+      is_ext_shared?: boolean;
+      is_pending_ext_shared?: boolean;
+    };
+    value =
+      ch.is_ext_shared === true || ch.is_pending_ext_shared === true ? "external" : "internal";
+  } catch (error) {
+    console.warn(
+      `[Slack] conversations.info failed for ${channelId}:`,
+      scrubSecrets(error instanceof Error ? error.message : String(error)),
+    );
+    return "unknown";
+  }
+
+  if (channelGeneration.get(channelId) !== generation) {
+    const fresher = externalityCache.get(channelId);
+    if (fresher && fresher.expiresAt > Date.now()) return fresher.value;
+    return value === "external" ? "external" : "unknown";
+  }
+  setBounded(externalityCache, channelId, { value, expiresAt: Date.now() + EXTERNALITY_TTL_MS });
+  return value;
+}
+
+/**
+ * Returns why the swarm must not touch a channel, or null when it may. With the
+ * flag on, a channel Slack cannot classify is blocked as "unverified" (fail
+ * closed): disclosing swarm output across an unverified boundary is worse than
+ * a temporary refusal.
+ */
+export async function getChannelBlockReason(
+  client: WebClient,
+  channelId: string,
+  envelopeFlag?: boolean,
+): Promise<ChannelBlockReason | null> {
+  if (!isBlockExternalEnabled()) return null;
+  if (envelopeFlag === true) {
+    recordExternalChannel(channelId);
+    return "external";
+  }
+  const externality = await getChannelExternality(client, channelId);
+  if (externality === "external") return "external";
+  if (externality === "unknown") {
+    console.warn(
+      `[Slack] Could not tell if channel ${channelId} is external; blocking (fail closed)`,
+    );
+    return "unverified";
+  }
+  return null;
+}
+
+/** True when the flag is on and the channel is external or cannot be verified. */
+export async function shouldBlockChannel(
+  client: WebClient,
+  channelId: string,
+  envelopeFlag?: boolean,
+): Promise<boolean> {
+  return (await getChannelBlockReason(client, channelId, envelopeFlag)) !== null;
+}
+
+async function postExternalChannelAlert(
+  client: WebClient,
+  channelId: string,
+  trigger: ExternalChannelTrigger,
+  leave: string,
+  scopeHint?: string,
+): Promise<void> {
+  const alertsChannel = process.env.SLACK_ALERTS_CHANNEL?.trim();
+  if (!alertsChannel) {
+    console.warn("[Slack] SLACK_ALERTS_CHANNEL not set; skipping external channel alert");
+    return;
+  }
+
+  // Durable dedupe: reserve the key briefly, extend it to an hour only after
+  // Slack accepts the post, and release it when the post fails.
+  const key = `${channelId}:${trigger}`;
+  if (!(await reserveAlert(key))) return;
+
+  const lines = [
+    `:no_entry: Swarm bot in external Slack channel <#${channelId}> (${channelId})`,
+    `Trigger: ${trigger}`,
+    `Leave: ${leave}`,
+    ...(scopeHint ? [scopeHint] : []),
+    "Inbound guard: active. The swarm creates no task from this channel.",
+  ];
+
+  try {
+    await client.chat.postMessage({
+      channel: alertsChannel,
+      text: scrubSecrets(lines.join("\n")),
+      unfurl_links: false,
+      unfurl_media: false,
+    });
+  } catch (error) {
+    console.error(
+      "[Slack] Failed to send external channel alert:",
+      scrubSecrets(error instanceof Error ? error.message : String(error)),
+    );
+    await settleAlert(key, false);
+    return;
+  }
+  await settleAlert(key, true);
+}
+
+/** True when this caller may send the alert. A DB failure sends rather than suppresses. */
+async function reserveAlert(key: string): Promise<boolean> {
+  try {
+    return await claimKv({
+      namespace: EXTERNAL_ALERT_KV_NAMESPACE,
+      key,
+      value: "sending",
+      valueType: "string",
+      expiresAt: Date.now() + ALERT_SENDING_TTL_MS,
+    });
+  } catch (error) {
+    console.warn("[Slack] External channel alert dedupe unavailable:", error);
+    return true;
+  }
+}
+
+async function settleAlert(key: string, sent: boolean): Promise<void> {
+  try {
+    if (sent) {
+      await upsertKv({
+        namespace: EXTERNAL_ALERT_KV_NAMESPACE,
+        key,
+        value: "sent",
+        valueType: "string",
+        expiresAt: Date.now() + ALERT_DEDUPE_MS,
+      });
+    } else {
+      await deleteKv(EXTERNAL_ALERT_KV_NAMESPACE, key);
+    }
+  } catch (error) {
+    console.warn("[Slack] Failed to record external channel alert state:", error);
+  }
+}
+
+/** Leaves an external channel and posts one alert with the result. */
+export async function leaveExternalChannel(
+  client: WebClient,
+  channelId: string,
+  reason: "joined" | "shared",
+): Promise<void> {
+  let leave: string;
+  let scopeHint: string | undefined;
+  try {
+    // A bot that is not a member gets {"ok":false,"not_in_channel":true}; treat it as left.
+    await client.conversations.leave({ channel: channelId });
+    leave = "left";
+  } catch (error) {
+    const code = slackCode(error);
+    const notInChannel =
+      code === "not_in_channel" ||
+      (error as { data?: { not_in_channel?: boolean } })?.data?.not_in_channel === true;
+    if (notInChannel) {
+      leave = "left";
+    } else {
+      leave = `failed (${code ?? "unknown_error"})`;
+      if (code === "missing_scope") scopeHint = slackMissingScopeMessage(error);
+      console.error(`[Slack] Failed to leave external channel ${channelId}: ${leave}`);
+    }
+  }
+  if (leave === "left") console.log(`[Slack] Left external channel ${channelId} (${reason})`);
+  await postExternalChannelAlert(client, channelId, reason, leave, scopeHint);
+}
+
+/**
+ * Boot scan, report only: posts one alert per external channel the bot is in.
+ * It never leaves a channel; a human decides.
+ */
+export async function scanExternalChannelsOnBoot(client: WebClient): Promise<void> {
+  if (!isBlockExternalEnabled()) return;
+
+  // kv_entries has no background sweep; drop expired alert keys so the namespace stays bounded.
+  await sweepExpiredKv(EXTERNAL_ALERT_KV_NAMESPACE).catch((error) => {
+    console.warn("[Slack] Failed to sweep expired external channel alert keys:", error);
+  });
+
+  let cursor: string | undefined;
+  do {
+    const resp = await client.users.conversations({
+      types: "public_channel,private_channel",
+      exclude_archived: true,
+      limit: 200,
+      cursor,
+    });
+    for (const ch of (resp.channels ?? []) as Array<{
+      id?: string;
+      is_ext_shared?: boolean;
+      is_pending_ext_shared?: boolean;
+    }>) {
+      if (!ch.id || !(ch.is_ext_shared === true || ch.is_pending_ext_shared === true)) continue;
+      await postExternalChannelAlert(client, ch.id, "boot-scan", "not attempted (report only)");
+    }
+    cursor = resp.response_metadata?.next_cursor || undefined;
+  } while (cursor);
+}

package/src/slack/handlers.ts

@@ -44,6 +44,13 @@ import type { AgentMatch } from "./types";
 // Side-effect import: registers all Slack event templates in the in-memory registry
 import "./templates";
 import { isEnvFlagEnabled } from "../utils/env-flag";
+import {
+  getChannelBlockReason,
+  invalidateChannelExternality,
+  isBlockExternalEnabled,
+  leaveExternalChannel,
+  shouldBlockChannel,
+} from "./external-channel";
 import { extractSlackMessageText } from "./message-text";
 import { ensureSlackThreadTree, isSlackRenderV2Enabled } from "./render-v2";
 import { formatSlackSteeringAck, requestSlackThreadSteering } from "./steering";
@@ -461,6 +468,18 @@ export function registerMessageHandler(app: App): void {
       return ignoreSlackInbound("duplicate_message");
     }
 
+    // Block external (Slack Connect) channels when SLACK_BLOCK_EXTERNAL_CHANNELS is on.
+    if (
+      await shouldBlockChannel(
+        client,
+        msg.channel,
+        (body as { is_ext_shared_channel?: boolean }).is_ext_shared_channel,
+      )
+    ) {
+      console.log(`[Slack] Ignoring message in external channel ${msg.channel}`);
+      return ignoreSlackInbound("external_channel");
+    }
+
     // Check user authorization
     if (!(await isUserAllowed(client, msg.user))) {
       console.log(`[Slack] Ignoring message from unauthorized user ${msg.user}`);
@@ -1018,4 +1037,46 @@ export function registerMessageHandler(app: App): void {
     // but we can add specific behavior here if needed
     console.log(`[Slack] App mentioned in channel ${event.channel}`);
   });
+
+  // External (Slack Connect) channels: leave when the bot joins one, or when a
+  // channel the bot is in becomes shared. All no-ops unless
+  // SLACK_BLOCK_EXTERNAL_CHANNELS is on.
+  app.event("member_joined_channel", async ({ event, client }) => {
+    if (!isBlockExternalEnabled()) return ignoreSlackInbound("external_block_disabled");
+
+    if (!cachedBotUserId) {
+      try {
+        const authResult = await client.auth.test();
+        cachedBotUserId = authResult.user_id as string;
+        cachedBotId = (authResult.bot_id as string | undefined) ?? null;
+      } catch (error) {
+        console.error("[Slack] Failed to cache bot user ID:", error);
+      }
+    }
+    if (!cachedBotUserId || event.user !== cachedBotUserId) {
+      return ignoreSlackInbound("member_joined_not_bot");
+    }
+
+    invalidateChannelExternality(event.channel);
+    // Leave only on positive evidence; an unverified channel stays blocked by the guards.
+    if ((await getChannelBlockReason(client, event.channel)) !== "external") {
+      return ignoreSlackInbound("member_joined_internal");
+    }
+    await leaveExternalChannel(client, event.channel, "joined");
+  });
+
+  app.event("channel_shared", async ({ event, client }) => {
+    if (!isBlockExternalEnabled()) return ignoreSlackInbound("external_block_disabled");
+
+    invalidateChannelExternality(event.channel);
+    if ((await getChannelBlockReason(client, event.channel)) !== "external") {
+      return ignoreSlackInbound("channel_shared_internal");
+    }
+    await leaveExternalChannel(client, event.channel, "shared");
+  });
+
+  app.event("channel_unshared", async ({ event }) => {
+    if (!isBlockExternalEnabled()) return ignoreSlackInbound("external_block_disabled");
+    invalidateChannelExternality(event.channel);
+  });
 }

package/src/slack/render-v2.ts

@@ -961,14 +961,16 @@ export async function childOutcomeContent(
   );
 }
 
-// A deferred wake continues a human conversation even though the scheduler
-// assigns source="schedule". Its answer must not depend on delegation cards.
-function isSlackContinuation(task: AgentTask): boolean {
+// A lead deferred wake continues the human conversation. Worker wakes report
+// through their lead follow-up instead of posting their own outcome cards.
+async function isSlackContinuation(task: AgentTask): Promise<boolean> {
   return (
     task.source === "schedule" &&
     task.taskType === "deferred" &&
     !!task.slackChannelId &&
-    !!task.slackThreadTs
+    !!task.slackThreadTs &&
+    !!task.agentId &&
+    !!(await getAgentById(task.agentId))?.isLead
   );
 }
 
@@ -981,7 +983,7 @@ function isSlackContinuation(task: AgentTask): boolean {
 function isChildCardCandidate(task: AgentTask, delegationActivatedAt: string): boolean {
   return (
     task.source !== "slack" &&
-    !isSlackContinuation(task) &&
+    !(task.source === "schedule" && task.taskType === "deferred") &&
     !!task.slackChannelId &&
     !!task.slackThreadTs &&
     (task.status === "completed" || task.status === "failed") &&
@@ -991,10 +993,10 @@ function isChildCardCandidate(task: AgentTask, delegationActivatedAt: string): b
   );
 }
 
-function taskNeedsDirectOutcome(task: AgentTask, activatedAt: string): boolean {
+async function taskNeedsDirectOutcome(task: AgentTask, activatedAt: string): Promise<boolean> {
   return (
     ((task.source === "slack" && isAskOutcomeStatus(task.status)) ||
-      (isSlackContinuation(task) && isOutcomeStatus(task.status))) &&
+      ((await isSlackContinuation(task)) && isOutcomeStatus(task.status))) &&
     task.createdAt >= activatedAt
   );
 }
@@ -1431,48 +1433,34 @@ export async function streamOutcomeCard(
   });
 }
 
-/**
- * The body a resolved deferral card is rewritten to. The ⏳ block promised
- * the thread an answer; this is that promise being kept in place, instead of
- * in a second card below it — `isAnsweredByDeferralCard` keeps the wake-up
- * from posting one, so the answer lands in the thread exactly once. It is
- * the card the wake-up would have posted, collapsed the same way when the
- * wake-up already answered by hand with `slack-reply`.
- *
- * A wake-up that deferred again does post its own card — the next ⏳ in the
- * chain, which its own wake-up resolves — so this card only points at it.
- */
+/** Render the latest wait or final result into the chain's original card. */
 async function resolvedDeferralContent(
   wake: AgentTask,
 ): Promise<{ text: string; blocks?: unknown[] }> {
-  if (!isDeferredTask(wake)) {
-    const content = await outcomeContent(wake, wake.slackReplySent);
-    const presentation = await outcomePresentation(wake, content);
-    const captions = await outcomeCaptionBlocks(wake, content);
-    return { text: presentation, blocks: [{ type: "markdown", text: presentation }, ...captions] };
-  }
-  const card = await getSlackOutcomeMessage(wake.id);
-  const pointer = card?.permalink ? ` — <${card.permalink}|next update>` : ".";
-  return { text: `↪️ Resumed by ${await agentDisplayNameFor(wake)} and deferred again${pointer}` };
+  const content = await outcomeContent(wake, wake.slackReplySent);
+  const presentation = await outcomePresentation(wake, content);
+  const captions = await outcomeCaptionBlocks(wake, content);
+  return { text: presentation, blocks: [{ type: "markdown", text: presentation }, ...captions] };
 }
 
-/**
- * True when `task` is a wake-up whose answer goes into its deferral's ⏳ card
- * (`refreshResolvedDeferralCards`), so it must not post an outcome card of
- * its own. False — and the wake-up posts its own card as before — when it
- * deferred again, when the deferral never got a card, and when the in-place
- * rewrite was abandoned.
- */
+/** A continuation uses the first retained, usable deferral card in its chain. */
 async function isAnsweredByDeferralCard(
   task: AgentTask,
   threadTasks: readonly AgentTask[],
 ): Promise<boolean> {
-  if (!isSlackContinuation(task) || !task.parentTaskId || isDeferredTask(task)) return false;
-  const deferred = threadTasks.find((candidate) => candidate.id === task.parentTaskId);
-  // Mirrors getResolvableDeferralOutcomes: only a `deferredAt` card is rewritten.
-  if (!deferred?.deferredAt) return false;
-  const card = await getSlackOutcomeMessage(deferred.id);
-  return !!card?.finalizedAt && !isPendingSlackMessage(card) && !card.deferralAbandonedAt;
+  const seen = new Set<string>();
+  let current = task;
+  while ((await isSlackContinuation(current)) && current.parentTaskId && !seen.has(current.id)) {
+    seen.add(current.id);
+    const deferred = threadTasks.find((candidate) => candidate.id === current.parentTaskId);
+    if (!deferred?.deferredAt) return false;
+    const card = await getSlackOutcomeMessage(deferred.id);
+    if (card) {
+      return !!card.finalizedAt && !isPendingSlackMessage(card) && !card.deferralAbandonedAt;
+    }
+    current = deferred;
+  }
+  return false;
 }
 
 /**
@@ -1490,6 +1478,8 @@ const TRANSIENT_SLACK_ERROR_CODES = new Set([
   "service_unavailable",
   "fatal_error",
   "request_timeout",
+  // The external-channel guard could not classify the channel; Slack may answer next time.
+  "external_channel_unverified",
 ]);
 
 export function slackErrorCode(error: unknown): string | undefined {
@@ -1539,9 +1529,8 @@ const deferralRefreshAttempts = new Map<string, number>();
  *
  * Runs after the tree loop and independently of it: resolution needs only
  * the retained outcome `ts`, so it must not be skipped when the thread has
- * no other pending render work. After, so a wake-up that deferred again has
- * already posted the card this one points at. Each card is rewritten exactly
- * once (`deferral_resolved_at`).
+ * no other pending render work. Re-defers update the same card; the final
+ * result marks it resolved (`deferral_resolved_at`).
  *
  * The marker is also burned when Slack refuses the rewrite for good, and when
  * an unclassifiable failure has used up its attempts — a card that can never
@@ -1562,10 +1551,14 @@ export async function refreshResolvedDeferralCards(): Promise<void> {
         ts: card.ts,
         ...content,
       });
-      await markSlackDeferralResolved(card.id);
+      if (isDeferredTask(wake)) {
+        await updateSlackMessageRecord(card.id, {});
+      } else {
+        await markSlackDeferralResolved(card.id);
+      }
       deferralRefreshAttempts.delete(card.id);
       // The rewrite is the wake-up's outcome, so it settles the ask's reaction.
-      await finalizeTerminalSlackReactions([wake]);
+      if (!isDeferredTask(wake)) await finalizeTerminalSlackReactions([wake]);
     } catch (error) {
       const attempts = (deferralRefreshAttempts.get(card.id) ?? 0) + 1;
       deferralRefreshAttempts.set(card.id, attempts);
@@ -1652,7 +1645,7 @@ export async function processSlackRenderV2(): Promise<void> {
       // not represent immediately active outcome work, so avoid waking an old
       // tree solely to verify its permalink on every render tick.
       const isDirectCandidate =
-        taskNeedsDirectOutcome(task, activatedAt) &&
+        (await taskNeedsDirectOutcome(task, activatedAt)) &&
         isOutcomeStatus(task.status) &&
         !(await isAnsweredByDeferralCard(task, tasks));
       const isChildCandidate =
@@ -1751,7 +1744,7 @@ export async function processSlackRenderV2(): Promise<void> {
 
     for (const task of tasks) {
       if (!isSlackRenderV2Enabled()) return;
-      if (!taskNeedsDirectOutcome(task, activatedAt)) continue;
+      if (!(await taskNeedsDirectOutcome(task, activatedAt))) continue;
       const card = await getSlackOutcomeMessage(task.id);
       if (card && isSettledSlackMessage(card)) continue;
       if (await isAnsweredByDeferralCard(task, tasks)) continue;

package/src/slack/work-objects.ts

@@ -3,6 +3,7 @@ import type { EntityPresentDetailsArguments, WebClient } from "@slack/web-api";
 import { getAgentById, getTaskById } from "../be/db";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { getTaskUrl } from "./blocks";
+import { shouldBlockChannel } from "./external-channel";
 import { isUserAllowed } from "./handlers";
 import { slackTaskOutput } from "./task-output";
 
@@ -30,6 +31,10 @@ async function getDetails(event: DetailsEvent, client: WebClient): Promise<Detai
     return { error: { status: "restricted" } };
   }
 
+  if (await shouldBlockChannel(client, event.channel)) {
+    return { error: { status: "restricted" } };
+  }
+
   const task = await getTaskById(ref.id);
   if (!task) return { error: { status: "not_found" } };
 

package/src/tasks/additive-buffer.ts

@@ -22,8 +22,10 @@
  *     the underlying context becomes irrelevant — e.g. user cancels).
  *
  * Concurrency: single-process, single-event-loop. No cross-instance locking.
- * Flush callbacks run sequentially per key (the buffer is cleared BEFORE the
- * callback fires, so re-enqueues during `onFlush` create a fresh buffer).
+ * The buffer is cleared BEFORE the callback fires, so re-enqueues during
+ * `onFlush` create a fresh buffer, and its flush can start while the earlier
+ * `onFlush` for the same key still runs. A caller that needs per-key order
+ * must serialize inside `onFlush`.
  */
 
 export type BufferFlushReason = "timer" | "manual";