@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/access/access-control.ts

@@ -0,0 +1,226 @@
+/**
+ * QQBot inbound access decision.
+ *
+ * This module is the single place where the QQBot engine decides
+ * whether an inbound message from a given sender is allowed to
+ * proceed into the outbound pipeline. The implementation mirrors the
+ * semantics of the framework-wide `resolveDmGroupAccessDecision`
+ * (`src/security/dm-policy-shared.ts`) but is kept standalone so the
+ * `engine/` layer does not pull in `openclaw/plugin-sdk/*` modules —
+ * a hard constraint shared with the standalone `openclaw-qqbot` build.
+ *
+ * If in the future we lift the zero-dependency rule in the engine
+ * layer, this file can be replaced by a thin adapter around the
+ * framework API with identical semantics.
+ */
+
+import { resolveQQBotEffectivePolicies, type EffectivePolicyInput } from "./resolve-policy.js";
+import { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "./sender-match.js";
+import {
+  QQBOT_ACCESS_REASON,
+  type QQBotAccessResult,
+  type QQBotDmPolicy,
+  type QQBotGroupPolicy,
+} from "./types.js";
+
+interface QQBotAccessInput extends EffectivePolicyInput {
+  /** Whether the inbound originated in a group (or guild) chat. */
+  isGroup: boolean;
+  /** The raw inbound sender id as provided by the QQ event. */
+  senderId: string;
+}
+
+/**
+ * Evaluate the inbound access policy.
+ *
+ * Semantics (aligned with `resolveDmGroupAccessDecision`):
+ *   - Group message:
+ *     - `groupPolicy=disabled` → block
+ *     - `groupPolicy=open`     → allow
+ *     - `groupPolicy=allowlist`:
+ *         - empty effectiveGroupAllowFrom → block (empty_allowlist)
+ *         - sender not in list            → block (not_allowlisted)
+ *         - otherwise                     → allow
+ *   - Direct message:
+ *     - `dmPolicy=disabled`    → block
+ *     - `dmPolicy=open`        → allow wildcard, legacy empty allowFrom, or matching allowFrom
+ *     - `dmPolicy=allowlist`:
+ *         - empty effectiveAllowFrom → block (empty_allowlist)
+ *         - sender not in list       → block (not_allowlisted)
+ *         - otherwise                → allow
+ *
+ * The function never throws; callers can rely on the returned
+ * `decision`/`reasonCode` pair for branching.
+ */
+export function resolveQQBotAccess(input: QQBotAccessInput): QQBotAccessResult {
+  const { dmPolicy, groupPolicy } = resolveQQBotEffectivePolicies(input);
+
+  // Per framework convention: groupAllowFrom falls back to allowFrom
+  // when not provided. We preserve that behaviour so a single
+  // `allowFrom` entry locks down both DM and group.
+  const rawGroupAllowFrom =
+    input.groupAllowFrom && input.groupAllowFrom.length > 0
+      ? input.groupAllowFrom
+      : (input.allowFrom ?? []);
+
+  const normalizedAllowFrom = normalizeQQBotAllowFrom(input.allowFrom);
+  const effectiveAllowFrom =
+    dmPolicy === "open" && normalizedAllowFrom.length === 0 ? ["*"] : normalizedAllowFrom;
+  const effectiveGroupAllowFrom = normalizeQQBotAllowFrom(rawGroupAllowFrom);
+
+  const isSenderAllowed = createQQBotSenderMatcher(input.senderId);
+
+  if (input.isGroup) {
+    return evaluateGroupDecision({
+      groupPolicy,
+      dmPolicy,
+      effectiveAllowFrom,
+      effectiveGroupAllowFrom,
+      isSenderAllowed,
+    });
+  }
+
+  return evaluateDmDecision({
+    groupPolicy,
+    dmPolicy,
+    effectiveAllowFrom,
+    effectiveGroupAllowFrom,
+    isSenderAllowed,
+  });
+}
+
+// ---- internal helpers ------------------------------------------------
+
+interface DecisionContext {
+  dmPolicy: QQBotDmPolicy;
+  groupPolicy: QQBotGroupPolicy;
+  effectiveAllowFrom: string[];
+  effectiveGroupAllowFrom: string[];
+  isSenderAllowed: (allowFrom: string[]) => boolean;
+}
+
+function evaluateGroupDecision(ctx: DecisionContext): QQBotAccessResult {
+  const base = buildResultBase(ctx);
+
+  if (ctx.groupPolicy === "disabled") {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.GROUP_POLICY_DISABLED,
+      reason: "groupPolicy=disabled",
+    };
+  }
+
+  if (ctx.groupPolicy === "open") {
+    return {
+      ...base,
+      decision: "allow",
+      reasonCode: QQBOT_ACCESS_REASON.GROUP_POLICY_ALLOWED,
+      reason: "groupPolicy=open",
+    };
+  }
+
+  // groupPolicy === "allowlist"
+  if (ctx.effectiveGroupAllowFrom.length === 0) {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.GROUP_POLICY_EMPTY_ALLOWLIST,
+      reason: "groupPolicy=allowlist (empty allowlist)",
+    };
+  }
+
+  if (!ctx.isSenderAllowed(ctx.effectiveGroupAllowFrom)) {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.GROUP_POLICY_NOT_ALLOWLISTED,
+      reason: "groupPolicy=allowlist (not allowlisted)",
+    };
+  }
+
+  return {
+    ...base,
+    decision: "allow",
+    reasonCode: QQBOT_ACCESS_REASON.GROUP_POLICY_ALLOWED,
+    reason: "groupPolicy=allowlist (allowlisted)",
+  };
+}
+
+function evaluateDmDecision(ctx: DecisionContext): QQBotAccessResult {
+  const base = buildResultBase(ctx);
+
+  if (ctx.dmPolicy === "disabled") {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_DISABLED,
+      reason: "dmPolicy=disabled",
+    };
+  }
+
+  if (ctx.dmPolicy === "open") {
+    if (ctx.effectiveAllowFrom.includes("*")) {
+      return {
+        ...base,
+        decision: "allow",
+        reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_OPEN,
+        reason: "dmPolicy=open",
+      };
+    }
+    if (ctx.isSenderAllowed(ctx.effectiveAllowFrom)) {
+      return {
+        ...base,
+        decision: "allow",
+        reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_ALLOWLISTED,
+        reason: "dmPolicy=open (allowlisted)",
+      };
+    }
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_NOT_ALLOWLISTED,
+      reason: "dmPolicy=open (not allowlisted)",
+    };
+  }
+
+  // dmPolicy === "allowlist"
+  if (ctx.effectiveAllowFrom.length === 0) {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_EMPTY_ALLOWLIST,
+      reason: "dmPolicy=allowlist (empty allowlist)",
+    };
+  }
+
+  if (!ctx.isSenderAllowed(ctx.effectiveAllowFrom)) {
+    return {
+      ...base,
+      decision: "block",
+      reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_NOT_ALLOWLISTED,
+      reason: "dmPolicy=allowlist (not allowlisted)",
+    };
+  }
+
+  return {
+    ...base,
+    decision: "allow",
+    reasonCode: QQBOT_ACCESS_REASON.DM_POLICY_ALLOWLISTED,
+    reason: "dmPolicy=allowlist (allowlisted)",
+  };
+}
+
+function buildResultBase(
+  ctx: DecisionContext,
+): Pick<
+  QQBotAccessResult,
+  "effectiveAllowFrom" | "effectiveGroupAllowFrom" | "dmPolicy" | "groupPolicy"
+> {
+  return {
+    effectiveAllowFrom: ctx.effectiveAllowFrom,
+    effectiveGroupAllowFrom: ctx.effectiveGroupAllowFrom,
+    dmPolicy: ctx.dmPolicy,
+    groupPolicy: ctx.groupPolicy,
+  };
+}

package/src/engine/access/index.ts

@@ -0,0 +1,16 @@
+/**
+ * QQBot inbound access control — public entry points.
+ *
+ * Consumers (inbound-pipeline and future adapters) should import from
+ * this barrel to keep the internal module layout opaque.
+ */
+
+export { resolveQQBotAccess } from "./access-control.js";
+export { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "./sender-match.js";
+export {
+  type QQBotAccessDecision,
+  type QQBotAccessReasonCode,
+  type QQBotAccessResult,
+  type QQBotDmPolicy,
+  type QQBotGroupPolicy,
+} from "./types.js";

package/src/engine/access/resolve-policy.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { resolveQQBotEffectivePolicies } from "./resolve-policy.js";
+
+describe("resolveQQBotEffectivePolicies", () => {
+  describe("backwards-compatible inference", () => {
+    it("defaults to open when no allowFrom is configured", () => {
+      expect(resolveQQBotEffectivePolicies({})).toEqual({
+        dmPolicy: "open",
+        groupPolicy: "open",
+      });
+    });
+
+    it("defaults to open when allowFrom only contains wildcard", () => {
+      expect(resolveQQBotEffectivePolicies({ allowFrom: ["*"] })).toEqual({
+        dmPolicy: "open",
+        groupPolicy: "open",
+      });
+    });
+
+    it("infers allowlist when allowFrom has a concrete entry", () => {
+      expect(resolveQQBotEffectivePolicies({ allowFrom: ["USER1"] })).toEqual({
+        dmPolicy: "allowlist",
+        groupPolicy: "allowlist",
+      });
+    });
+
+    it("infers group=allowlist when only groupAllowFrom is restricted", () => {
+      expect(
+        resolveQQBotEffectivePolicies({ allowFrom: ["*"], groupAllowFrom: ["USER1"] }),
+      ).toEqual({
+        dmPolicy: "open",
+        groupPolicy: "allowlist",
+      });
+    });
+  });
+
+  describe("explicit policy precedence", () => {
+    it("honours explicit dmPolicy over inference", () => {
+      expect(
+        resolveQQBotEffectivePolicies({ allowFrom: ["USER1"], dmPolicy: "open" }),
+      ).toMatchObject({ dmPolicy: "open" });
+    });
+
+    it("honours explicit groupPolicy over inference", () => {
+      expect(
+        resolveQQBotEffectivePolicies({
+          allowFrom: ["USER1"],
+          groupPolicy: "disabled",
+        }),
+      ).toMatchObject({ groupPolicy: "disabled" });
+    });
+
+    it("allows dmPolicy=disabled to cut off DM entirely", () => {
+      expect(resolveQQBotEffectivePolicies({ dmPolicy: "disabled" })).toMatchObject({
+        dmPolicy: "disabled",
+      });
+    });
+  });
+});

package/src/engine/access/resolve-policy.ts

@@ -0,0 +1,57 @@
+/**
+ * Effective-policy resolver.
+ *
+ * Maps a raw `QQBotAccountConfig` to the concrete `dmPolicy`/`groupPolicy`
+ * values that the access engine consumes. Provides backwards-compatible
+ * defaults for accounts that only have the legacy `allowFrom` field:
+ *
+ *   - Empty `allowFrom` or containing `"*"` → `"open"` (the historical
+ *     behaviour before P0/P1 landed).
+ *   - Non-empty `allowFrom` without `"*"`   → `"allowlist"` (what a
+ *     security-conscious operator almost certainly meant).
+ *
+ * An explicit `dmPolicy`/`groupPolicy` always wins over the inference.
+ */
+
+import type { QQBotDmPolicy, QQBotGroupPolicy } from "./types.js";
+
+/** Subset of the account config fields this resolver actually reads. */
+export interface EffectivePolicyInput {
+  allowFrom?: Array<string | number> | null;
+  groupAllowFrom?: Array<string | number> | null;
+  dmPolicy?: QQBotDmPolicy | null;
+  groupPolicy?: QQBotGroupPolicy | null;
+}
+
+function hasRealRestriction(list: Array<string | number> | null | undefined): boolean {
+  if (!list || list.length === 0) {
+    return false;
+  }
+  // A list that only contains `"*"` is logically equivalent to open.
+  return !list.every((entry) => String(entry).trim() === "*");
+}
+
+/**
+ * Derive the effective dmPolicy and groupPolicy applied at runtime.
+ *
+ * Caller should pass the raw `QQBotAccountConfig`. The resolver does
+ * not look at `groups[id]` overrides — per-group overrides are layered
+ * on top elsewhere (see `inbound-pipeline` mention gating).
+ */
+export function resolveQQBotEffectivePolicies(input: EffectivePolicyInput): {
+  dmPolicy: QQBotDmPolicy;
+  groupPolicy: QQBotGroupPolicy;
+} {
+  const allowFromRestricted = hasRealRestriction(input.allowFrom);
+  const groupAllowFromRestricted = hasRealRestriction(input.groupAllowFrom);
+
+  const dmPolicy: QQBotDmPolicy = input.dmPolicy ?? (allowFromRestricted ? "allowlist" : "open");
+
+  // groupPolicy defaults: if an explicit groupAllowFrom is provided and
+  // restricts, enforce allowlist. Otherwise fall back to the same rule
+  // as DM (so a single `allowFrom` entry locks down both DM and group).
+  const groupPolicy: QQBotGroupPolicy =
+    input.groupPolicy ?? (groupAllowFromRestricted || allowFromRestricted ? "allowlist" : "open");
+
+  return { dmPolicy, groupPolicy };
+}

package/src/engine/access/sender-match.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import {
+  createQQBotSenderMatcher,
+  normalizeQQBotAllowFrom,
+  normalizeQQBotSenderId,
+} from "./sender-match.js";
+
+describe("normalizeQQBotSenderId", () => {
+  it("uppercases and strips qqbot: prefix", () => {
+    expect(normalizeQQBotSenderId("qqbot:abc123")).toBe("ABC123");
+    expect(normalizeQQBotSenderId("QQBot:abc123")).toBe("ABC123");
+  });
+
+  it("trims whitespace", () => {
+    expect(normalizeQQBotSenderId("  USER1  ")).toBe("USER1");
+  });
+
+  it("returns empty string for non-string input", () => {
+    expect(normalizeQQBotSenderId(undefined as unknown as string)).toBe("");
+    expect(normalizeQQBotSenderId(null as unknown as string)).toBe("");
+    expect(normalizeQQBotSenderId({} as unknown as string)).toBe("");
+  });
+
+  it("accepts numeric input", () => {
+    expect(normalizeQQBotSenderId(42)).toBe("42");
+  });
+});
+
+describe("normalizeQQBotAllowFrom", () => {
+  it("normalizes all entries and drops empty ones", () => {
+    expect(normalizeQQBotAllowFrom(["qqbot:user1", "USER2", "", " "])).toEqual(["USER1", "USER2"]);
+  });
+
+  it("returns empty array for undefined/null", () => {
+    expect(normalizeQQBotAllowFrom(undefined)).toEqual([]);
+    expect(normalizeQQBotAllowFrom(null)).toEqual([]);
+  });
+});
+
+describe("createQQBotSenderMatcher", () => {
+  it("matches wildcard regardless of sender", () => {
+    expect(createQQBotSenderMatcher("USER1")(["*"])).toBe(true);
+    expect(createQQBotSenderMatcher("")(["*"])).toBe(true);
+  });
+
+  it("matches case-insensitive with qqbot: prefix", () => {
+    const match = createQQBotSenderMatcher("qqbot:USER1");
+    expect(match(["qqbot:user1"])).toBe(true);
+    expect(match(["USER1"])).toBe(true);
+    expect(match(["USER2"])).toBe(false);
+  });
+
+  it("returns false on empty allowlist", () => {
+    expect(createQQBotSenderMatcher("USER1")([])).toBe(false);
+  });
+
+  it("returns false for empty sender against non-wildcard list", () => {
+    expect(createQQBotSenderMatcher("")(["USER1"])).toBe(false);
+  });
+});

package/src/engine/access/sender-match.ts

@@ -0,0 +1,55 @@
+/**
+ * QQBot sender normalization and allowlist matching.
+ *
+ * Keeps QQ-specific quirks (the `qqbot:` prefix, uppercase-insensitive
+ * comparison) localized to this module so the policy engine itself can
+ * stay channel-agnostic.
+ */
+
+/** Normalize a single entry (openid): strip `qqbot:` prefix, uppercase, trim. */
+export function normalizeQQBotSenderId(raw: unknown): string {
+  if (typeof raw !== "string" && typeof raw !== "number") {
+    return "";
+  }
+  return String(raw)
+    .trim()
+    .replace(/^qqbot:/i, "")
+    .toUpperCase();
+}
+
+/** Normalize an entire allowFrom list, dropping empty entries. */
+export function normalizeQQBotAllowFrom(list: Array<string | number> | undefined | null): string[] {
+  if (!list || list.length === 0) {
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of list) {
+    const normalized = normalizeQQBotSenderId(entry);
+    if (normalized) {
+      out.push(normalized);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a matcher closure suitable for passing to the policy engine's
+ * `isSenderAllowed` callback. The caller supplies the sender once, and
+ * the returned function can be invoked against different allowlists
+ * (DM allowlist vs group allowlist) without repeating normalization.
+ */
+export function createQQBotSenderMatcher(senderId: string): (allowFrom: string[]) => boolean {
+  const normalizedSender = normalizeQQBotSenderId(senderId);
+  return (allowFrom: string[]) => {
+    if (allowFrom.length === 0) {
+      return false;
+    }
+    if (allowFrom.includes("*")) {
+      return true;
+    }
+    if (!normalizedSender) {
+      return false;
+    }
+    return allowFrom.some((entry) => normalizeQQBotSenderId(entry) === normalizedSender);
+  };
+}

package/src/engine/access/types.ts

@@ -0,0 +1,53 @@
+/**
+ * QQBot access-control primitive types.
+ *
+ * Mirrors the semantics of the framework-shared `DmPolicy` and
+ * `DmGroupAccessDecision` types while staying zero-dependency so the
+ * engine layer remains portable across the built-in and standalone
+ * plugin builds.
+ *
+ * The reason codes here intentionally match
+ * `src/security/dm-policy-shared.ts::DM_GROUP_ACCESS_REASON` so metric
+ * dashboards can treat QQBot decisions identically to WhatsApp /
+ * Telegram / Discord decisions.
+ */
+
+/** DM-level policy selecting between open / allowlist / disabled gating. */
+export type QQBotDmPolicy = "open" | "allowlist" | "disabled";
+
+/** Group-level policy selecting between open / allowlist / disabled gating. */
+export type QQBotGroupPolicy = "open" | "allowlist" | "disabled";
+
+/** High-level outcome returned by the access gate. */
+export type QQBotAccessDecision = "allow" | "block";
+
+/** Structured reason codes used in logs and metrics. */
+export const QQBOT_ACCESS_REASON = {
+  DM_POLICY_OPEN: "dm_policy_open",
+  DM_POLICY_DISABLED: "dm_policy_disabled",
+  DM_POLICY_ALLOWLISTED: "dm_policy_allowlisted",
+  DM_POLICY_NOT_ALLOWLISTED: "dm_policy_not_allowlisted",
+  DM_POLICY_EMPTY_ALLOWLIST: "dm_policy_empty_allowlist",
+  GROUP_POLICY_ALLOWED: "group_policy_allowed",
+  GROUP_POLICY_DISABLED: "group_policy_disabled",
+  GROUP_POLICY_EMPTY_ALLOWLIST: "group_policy_empty_allowlist",
+  GROUP_POLICY_NOT_ALLOWLISTED: "group_policy_not_allowlisted",
+  BOT_SELF_ECHO: "bot_self_echo",
+} as const;
+
+export type QQBotAccessReasonCode = (typeof QQBOT_ACCESS_REASON)[keyof typeof QQBOT_ACCESS_REASON];
+
+/** Result of the access gate evaluation. */
+export interface QQBotAccessResult {
+  decision: QQBotAccessDecision;
+  reasonCode: QQBotAccessReasonCode;
+  /** Human-readable reason suitable for logging. */
+  reason: string;
+  /** The allowFrom list that was actually compared against. */
+  effectiveAllowFrom: string[];
+  /** The groupAllowFrom list that was actually compared against. */
+  effectiveGroupAllowFrom: string[];
+  /** The dm/group policies that were used (after defaults were applied). */
+  dmPolicy: QQBotDmPolicy;
+  groupPolicy: QQBotGroupPolicy;
+}

package/src/engine/adapter/audio.port.ts

@@ -0,0 +1,27 @@
+/**
+ * Audio port — abstracts inbound + outbound audio conversion operations.
+ *
+ * The engine defines this interface; the bridge layer provides an
+ * implementation backed by `engine/utils/audio.js` functions.
+ */
+
+/** Inbound audio conversion (SILK→WAV, voice detection, duration formatting). */
+export interface AudioConvertPort {
+  convertSilkToWav(
+    silkPath: string,
+    outputDir: string,
+  ): Promise<{ wavPath: string; duration: number } | null>;
+  isVoiceAttachment(att: { content_type: string; filename?: string }): boolean;
+  formatDuration(seconds: number): string;
+}
+
+/** Outbound audio conversion (WAV→SILK, audio detection, transcoding). */
+export interface OutboundAudioPort {
+  audioFileToSilkBase64(
+    audioPath: string,
+    directUploadFormats?: string[],
+  ): Promise<string | undefined>;
+  isAudioFile(pathOrUrl: string, mimeType?: string): boolean;
+  shouldTranscodeVoice(filePath: string): boolean;
+  waitForFile(filePath: string, maxWaitMs?: number): Promise<number>;
+}

package/src/engine/adapter/commands.port.ts

@@ -0,0 +1,22 @@
+/**
+ * Commands port — abstracts slash-command dependencies injected by the
+ * bridge layer (version resolvers, approve runtime getter).
+ *
+ * Eliminates global `register*` singletons in `slash-commands-impl.ts`.
+ */
+
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+
+/** Runtime getter shape for the `/bot-approve` command. */
+export type ApproveRuntimeGetter = () => {
+  config: Pick<PluginRuntime["config"], "current" | "replaceConfigFile">;
+};
+
+export interface CommandsPort {
+  /** Resolve the framework runtime version string. */
+  resolveVersion: () => string;
+  /** Plugin version string (e.g. "1.2.3"). */
+  pluginVersion: string;
+  /** Runtime getter for `/bot-approve` config management. */
+  approveRuntimeGetter?: ApproveRuntimeGetter;
+}

package/src/engine/adapter/history.port.ts

@@ -0,0 +1,52 @@
+/**
+ * History port — abstracts the group history cache operations.
+ *
+ * The engine defines this interface; the bridge layer provides an
+ * implementation backed by SDK `reply-history` functions. The engine's
+ * built-in implementation in `group/history.ts` is used as the default
+ * when no adapter is injected (standalone build).
+ */
+
+/** Minimal history entry shape expected by the port. */
+export interface HistoryEntryLike {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  messageId?: string;
+}
+
+export interface HistoryPort {
+  /**
+   * Record a non-@ message into the pending history buffer.
+   * No-op when `limit <= 0` or `entry` is missing.
+   */
+  recordPendingHistoryEntry<T extends HistoryEntryLike>(params: {
+    historyMap: Map<string, T[]>;
+    historyKey: string;
+    entry?: T | null;
+    limit: number;
+  }): T[];
+
+  /**
+   * Build the full user-message string prefixed with buffered history.
+   * Returns `currentMessage` unchanged when no history exists.
+   */
+  buildPendingHistoryContext(params: {
+    historyMap: Map<string, HistoryEntryLike[]>;
+    historyKey: string;
+    limit: number;
+    currentMessage: string;
+    formatEntry: (entry: HistoryEntryLike) => string;
+    lineBreak?: string;
+  }): string;
+
+  /**
+   * Clear a group's pending history buffer.
+   * No-op when `limit <= 0`.
+   */
+  clearPendingHistory(params: {
+    historyMap: Map<string, HistoryEntryLike[]>;
+    historyKey: string;
+    limit: number;
+  }): void;
+}