@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/reply-context.ts

@@ -0,0 +1,92 @@
+import type { MatrixClient } from "../sdk.js";
+import { summarizeMatrixMessageContextEvent, trimMatrixMaybeString } from "./context-summary.js";
+import type { MatrixRawEvent } from "./types.js";
+
+const MAX_CACHED_REPLY_CONTEXTS = 256;
+const MAX_REPLY_BODY_LENGTH = 500;
+
+export type MatrixReplyContext = {
+  replyToBody?: string;
+  replyToSender?: string;
+  replyToSenderId?: string;
+};
+
+function truncateReplyBody(value: string): string {
+  if (value.length <= MAX_REPLY_BODY_LENGTH) {
+    return value;
+  }
+  return `${value.slice(0, MAX_REPLY_BODY_LENGTH - 3)}...`;
+}
+
+export function summarizeMatrixReplyEvent(event: MatrixRawEvent): string | undefined {
+  const body = summarizeMatrixMessageContextEvent(event);
+  return body ? truncateReplyBody(body) : undefined;
+}
+
+/**
+ * Creates a cached resolver that fetches the body and sender of a replied-to
+ * Matrix event. This allows the agent to see the content of the message being
+ * replied to, not just its event ID.
+ */
+export function createMatrixReplyContextResolver(params: {
+  client: MatrixClient;
+  getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
+  logVerboseMessage: (message: string) => void;
+}) {
+  const cache = new Map<string, MatrixReplyContext>();
+
+  const remember = (key: string, value: MatrixReplyContext): MatrixReplyContext => {
+    cache.set(key, value);
+    if (cache.size > MAX_CACHED_REPLY_CONTEXTS) {
+      const oldest = cache.keys().next().value;
+      if (typeof oldest === "string") {
+        cache.delete(oldest);
+      }
+    }
+    return value;
+  };
+
+  return async (input: { roomId: string; eventId: string }): Promise<MatrixReplyContext> => {
+    const cacheKey = `${input.roomId}:${input.eventId}`;
+    const cached = cache.get(cacheKey);
+    if (cached) {
+      // Move to end for LRU semantics so frequently accessed entries survive eviction.
+      cache.delete(cacheKey);
+      cache.set(cacheKey, cached);
+      return cached;
+    }
+
+    const event = await params.client.getEvent(input.roomId, input.eventId).catch((err) => {
+      params.logVerboseMessage(
+        `matrix: failed resolving reply context room=${input.roomId} id=${input.eventId}: ${String(err)}`,
+      );
+      return null;
+    });
+    if (!event) {
+      // Do not cache failures so transient errors can be retried on the next
+      // message that references the same event.
+      return {};
+    }
+
+    const rawEvent = event as MatrixRawEvent;
+    if (rawEvent.unsigned?.redacted_because) {
+      return remember(cacheKey, {});
+    }
+
+    const replyToBody = summarizeMatrixReplyEvent(rawEvent);
+    if (!replyToBody) {
+      return remember(cacheKey, {});
+    }
+
+    const senderId = trimMatrixMaybeString(rawEvent.sender);
+    const senderName =
+      senderId &&
+      (await params.getMemberDisplayName(input.roomId, senderId).catch(() => undefined));
+
+    return remember(cacheKey, {
+      replyToBody,
+      replyToSender: senderName ?? senderId,
+      replyToSenderId: senderId,
+    });
+  };
+}

package/src/matrix/monitor/room-history.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Unit tests for createRoomHistoryTracker.
+ *
+ * Covers correctness properties that are hard to observe through the handler harness:
+ * - Monotone watermark advancement (out-of-order consumeHistory must not regress)
+ * - roomQueues FIFO eviction when the room count exceeds the cap
+ */
+
+import { describe, expect, it } from "vitest";
+import { createRoomHistoryTrackerForTests } from "./room-history.js";
+
+const ROOM = "!room:test";
+const AGENT = "agent_a";
+
+function entry(body: string) {
+  return { sender: "user", body };
+}
+
+describe("createRoomHistoryTracker — watermark monotonicity", () => {
+  it("consumeHistory is monotone: out-of-order completion does not regress the watermark", () => {
+    const tracker = createRoomHistoryTrackerForTests();
+
+    // Queue: [msg1, msg2, trigger1, msg3, trigger2]
+    tracker.recordPending(ROOM, entry("msg1"));
+    tracker.recordPending(ROOM, entry("msg2"));
+    const snap1 = tracker.recordTrigger(ROOM, entry("trigger1")); // snap=3
+    tracker.recordPending(ROOM, entry("msg3"));
+    const snap2 = tracker.recordTrigger(ROOM, entry("trigger2")); // snap=5
+
+    // trigger2 completes first (higher index)
+    tracker.consumeHistory(AGENT, ROOM, snap2); // watermark → 5
+    expect(tracker.getPendingHistory(AGENT, ROOM, 100)).toHaveLength(0);
+
+    // trigger1 completes later (lower index) — must NOT regress to 3
+    tracker.consumeHistory(AGENT, ROOM, snap1);
+    // If regressed: [msg3, trigger2] would be visible (2 entries); must stay at 0
+    expect(tracker.getPendingHistory(AGENT, ROOM, 100)).toHaveLength(0);
+
+    // In-order advancement still works
+    tracker.recordPending(ROOM, entry("msg4"));
+    const snap3 = tracker.recordTrigger(ROOM, entry("trigger3")); // snap=7
+    tracker.consumeHistory(AGENT, ROOM, snap3); // watermark → 7
+    expect(tracker.getPendingHistory(AGENT, ROOM, 100)).toHaveLength(0);
+  });
+
+  it("prepareTrigger reuses the original history window for a retried event", () => {
+    const tracker = createRoomHistoryTrackerForTests();
+
+    tracker.recordPending(ROOM, { sender: "user", body: "msg1", messageId: "$m1" });
+    const first = tracker.prepareTrigger(AGENT, ROOM, 100, {
+      sender: "user",
+      body: "trigger",
+      messageId: "$trigger",
+    });
+
+    tracker.recordPending(ROOM, { sender: "user", body: "msg2", messageId: "$m2" });
+    const retried = tracker.prepareTrigger(AGENT, ROOM, 100, {
+      sender: "user",
+      body: "trigger",
+      messageId: "$trigger",
+    });
+
+    expect(first.history.map((entry) => entry.body)).toEqual(["msg1"]);
+    expect(retried.history.map((entry) => entry.body)).toEqual(["msg1"]);
+    expect(retried.snapshotIdx).toBe(first.snapshotIdx);
+  });
+
+  it("refreshes watermark recency before capped-map eviction", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 10, 2);
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+    const room3 = "!room3:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    const snap1 = tracker.recordTrigger(room1, entry("trigger in room1"));
+    tracker.consumeHistory(AGENT, room1, snap1);
+
+    tracker.recordPending(room2, entry("old msg in room2"));
+    const snap2 = tracker.recordTrigger(room2, entry("trigger in room2"));
+    tracker.consumeHistory(AGENT, room2, snap2);
+
+    // Refresh room1 so room2 becomes the stalest watermark entry.
+    tracker.consumeHistory(AGENT, room1, snap1);
+
+    tracker.recordPending(room3, entry("old msg in room3"));
+    const snap3 = tracker.recordTrigger(room3, entry("trigger in room3"));
+    tracker.consumeHistory(AGENT, room3, snap3);
+
+    tracker.recordPending(room1, entry("new msg in room1"));
+    const room1History = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(room1History).toHaveLength(1);
+    expect(room1History[0]?.body).toBe("new msg in room1");
+  });
+
+  it("refreshes prepared-trigger recency before capped eviction on retry hits", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 10, 5000, 2);
+    const room1 = "!room1:test";
+
+    tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger1",
+      messageId: "$trigger1",
+    });
+    tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger2",
+      messageId: "$trigger2",
+    });
+
+    // Retry hit should refresh trigger1 so trigger2 becomes the stale entry.
+    const retried = tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger1",
+      messageId: "$trigger1",
+    });
+    tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger3",
+      messageId: "$trigger3",
+    });
+
+    const reused = tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger1",
+      messageId: "$trigger1",
+    });
+    expect(reused.snapshotIdx).toBe(retried.snapshotIdx);
+  });
+});
+
+describe("createRoomHistoryTracker — roomQueues eviction", () => {
+  it("evicts the oldest room (FIFO) when the room count exceeds the cap", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 3);
+
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+    const room3 = "!room3:test";
+    const room4 = "!room4:test";
+
+    tracker.recordPending(room1, entry("msg in room1"));
+    tracker.recordPending(room2, entry("msg in room2"));
+    tracker.recordPending(room3, entry("msg in room3"));
+
+    // At cap (3 rooms) — no eviction yet
+    expect(tracker.getPendingHistory(AGENT, room1, 100)).toHaveLength(1);
+
+    // room4 pushes count to 4 > cap=3 → room1 (oldest) evicted
+    tracker.recordPending(room4, entry("msg in room4"));
+    expect(tracker.getPendingHistory(AGENT, room1, 100)).toHaveLength(0);
+    expect(tracker.getPendingHistory(AGENT, room2, 100)).toHaveLength(1);
+    expect(tracker.getPendingHistory(AGENT, room3, 100)).toHaveLength(1);
+    expect(tracker.getPendingHistory(AGENT, room4, 100)).toHaveLength(1);
+  });
+
+  it("re-accessing an evicted room starts a fresh empty queue", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 2);
+
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+    const room3 = "!room3:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    tracker.recordPending(room2, entry("msg in room2"));
+    tracker.recordPending(room3, entry("msg in room3")); // evicts room1
+
+    tracker.recordPending(room1, entry("new msg in room1"));
+    const history = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.body).toBe("new msg in room1");
+  });
+
+  it("clears stale room watermarks when an evicted room is recreated", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 1);
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    const firstSnapshot = tracker.recordTrigger(room1, entry("trigger in room1"));
+    tracker.consumeHistory(AGENT, room1, firstSnapshot);
+
+    // room2 creation evicts room1 (maxRoomQueues=1)
+    tracker.recordPending(room2, entry("msg in room2"));
+
+    // Recreate room1 and add fresh content.
+    tracker.recordPending(room1, entry("new msg in room1"));
+    const history = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.body).toBe("new msg in room1");
+  });
+
+  it("ignores late consumeHistory calls after the room queue was evicted", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 1);
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    const prepared = tracker.prepareTrigger(AGENT, room1, 100, {
+      sender: "user",
+      body: "trigger in room1",
+      messageId: "$trigger",
+    });
+
+    // room2 creation evicts room1 (maxRoomQueues=1) while the trigger is still in flight.
+    tracker.recordPending(room2, entry("msg in room2"));
+
+    // Late completion for the evicted room must not recreate a stale watermark.
+    tracker.consumeHistory(AGENT, room1, prepared, "$trigger");
+
+    // Recreate room1 and add fresh content.
+    tracker.recordPending(room1, entry("new msg in room1"));
+    const history = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.body).toBe("new msg in room1");
+  });
+
+  it("rejects stale snapshots after the room queue is recreated", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 1);
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    const staleSnapshot = tracker.recordTrigger(room1, entry("trigger in room1"));
+
+    tracker.recordPending(room2, entry("msg in room2")); // evicts room1
+    tracker.recordPending(room1, entry("new msg in room1")); // recreates room1 with new generation
+
+    tracker.consumeHistory(AGENT, room1, staleSnapshot);
+
+    const history = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.body).toBe("new msg in room1");
+  });
+
+  it("preserves newer watermarks when an older snapshot finishes after room recreation", () => {
+    const tracker = createRoomHistoryTrackerForTests(200, 1);
+    const room1 = "!room1:test";
+    const room2 = "!room2:test";
+
+    tracker.recordPending(room1, entry("old msg in room1"));
+    const staleSnapshot = tracker.recordTrigger(room1, entry("old trigger in room1"));
+
+    tracker.recordPending(room2, entry("msg in room2")); // evicts room1
+
+    tracker.recordPending(room1, entry("new msg in room1"));
+    const freshSnapshot = tracker.recordTrigger(room1, entry("new trigger in room1"));
+    tracker.consumeHistory(AGENT, room1, freshSnapshot);
+
+    // Late completion from the old generation must be ignored and must not clear the
+    // watermark already written by the newer trigger.
+    tracker.consumeHistory(AGENT, room1, staleSnapshot);
+
+    tracker.recordPending(room1, entry("fresh msg after consume"));
+
+    const history = tracker.getPendingHistory(AGENT, room1, 100);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.body).toBe("fresh msg after consume");
+  });
+});

package/src/matrix/monitor/room-history.ts

@@ -0,0 +1,301 @@
+/**
+ * Per-room group chat history tracking for Matrix.
+ *
+ * Maintains a shared per-room message queue and per-(agentId, roomId) watermarks so
+ * each agent independently tracks which messages it has already consumed. This design
+ * lets multiple agents in the same room see independent history windows:
+ *
+ * - dev replies to @dev msgB (watermark advances to B) → room queue still has [A, B]
+ * - spark replies to @spark msgC → spark watermark starts at 0 and sees [A, B, C]
+ *
+ * Race-condition safety: the watermark only advances to the snapshot index taken at
+ * dispatch time, NOT to the queue's end at reply time.  Messages that land in the queue
+ * while the agent is processing stay visible to the next trigger for that agent.
+ */
+
+import type { HistoryEntry } from "openclaw/plugin-sdk/reply-history";
+
+/** Maximum entries retained per room (hard cap to bound memory). */
+const DEFAULT_MAX_QUEUE_SIZE = 200;
+/** Maximum number of rooms to retain queues for (FIFO eviction beyond this). */
+const DEFAULT_MAX_ROOM_QUEUES = 1000;
+/** Maximum number of (agentId, roomId) watermark entries to retain. */
+const MAX_WATERMARK_ENTRIES = 5000;
+/** Maximum prepared trigger snapshots retained per room for retry reuse. */
+const MAX_PREPARED_TRIGGER_ENTRIES = 500;
+
+export type { HistoryEntry };
+
+export type HistorySnapshotToken = {
+  snapshotIdx: number;
+  queueGeneration: number;
+};
+
+export type PreparedTriggerResult = {
+  history: HistoryEntry[];
+} & HistorySnapshotToken;
+
+export type RoomHistoryTracker = {
+  /**
+   * Record a non-trigger message for future context.
+   * Call this when a room message arrives but does not mention the bot.
+   */
+  recordPending: (roomId: string, entry: HistoryEntry) => void;
+
+  /**
+   * Capture pending history and append the trigger as one idempotent operation.
+   * Retries of the same Matrix event reuse the original prepared history window.
+   */
+  prepareTrigger: (
+    agentId: string,
+    roomId: string,
+    limit: number,
+    entry: HistoryEntry,
+  ) => PreparedTriggerResult;
+
+  /**
+   * Advance the agent's watermark to the snapshot index returned by prepareTrigger
+   * (or the lower-level recordTrigger helper used in tests).
+   * Only messages appended after that snapshot remain visible on the next trigger.
+   */
+  consumeHistory: (
+    agentId: string,
+    roomId: string,
+    snapshot: HistorySnapshotToken,
+    messageId?: string,
+  ) => void;
+};
+
+export type RoomHistoryTrackerTestApi = RoomHistoryTracker & {
+  /**
+   * Test-only helper for inspecting pending room history directly.
+   */
+  getPendingHistory: (agentId: string, roomId: string, limit: number) => HistoryEntry[];
+
+  /**
+   * Test-only helper for manually appending a trigger entry and snapshot index.
+   */
+  recordTrigger: (roomId: string, entry: HistoryEntry) => HistorySnapshotToken;
+};
+
+type RoomQueue = {
+  entries: HistoryEntry[];
+  /** Absolute index of entries[0] — increases as old entries are trimmed. */
+  baseIndex: number;
+  generation: number;
+  preparedTriggers: Map<string, PreparedTriggerResult>;
+};
+
+function createRoomHistoryTrackerInternal(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTrackerTestApi {
+  const roomQueues = new Map<string, RoomQueue>();
+  /** Maps `${agentId}:${roomId}` → absolute consumed-up-to index */
+  const agentWatermarks = new Map<string, number>();
+  let nextQueueGeneration = 1;
+
+  function clearRoomWatermarks(roomId: string): void {
+    const roomSuffix = `:${roomId}`;
+    for (const key of agentWatermarks.keys()) {
+      if (key.endsWith(roomSuffix)) {
+        agentWatermarks.delete(key);
+      }
+    }
+  }
+
+  function getOrCreateQueue(roomId: string): RoomQueue {
+    let queue = roomQueues.get(roomId);
+    if (!queue) {
+      queue = {
+        entries: [],
+        baseIndex: 0,
+        generation: nextQueueGeneration++,
+        preparedTriggers: new Map(),
+      };
+      roomQueues.set(roomId, queue);
+      // FIFO eviction to prevent unbounded growth across many rooms
+      if (roomQueues.size > maxRoomQueues) {
+        const oldest = roomQueues.keys().next().value;
+        if (oldest !== undefined) {
+          roomQueues.delete(oldest);
+          clearRoomWatermarks(oldest);
+        }
+      }
+    }
+    return queue;
+  }
+
+  function appendToQueue(queue: RoomQueue, entry: HistoryEntry): HistorySnapshotToken {
+    queue.entries.push(entry);
+    if (queue.entries.length > maxQueueSize) {
+      const overflow = queue.entries.length - maxQueueSize;
+      queue.entries.splice(0, overflow);
+      queue.baseIndex += overflow;
+    }
+    return {
+      snapshotIdx: queue.baseIndex + queue.entries.length,
+      queueGeneration: queue.generation,
+    };
+  }
+
+  function wmKey(agentId: string, roomId: string): string {
+    return `${agentId}:${roomId}`;
+  }
+
+  function preparedTriggerKey(agentId: string, messageId?: string): string | null {
+    if (!messageId?.trim()) {
+      return null;
+    }
+    return `${agentId}:${messageId.trim()}`;
+  }
+
+  function rememberWatermark(key: string, snapshotIdx: number): void {
+    const nextSnapshotIdx = Math.max(agentWatermarks.get(key) ?? 0, snapshotIdx);
+    if (agentWatermarks.has(key)) {
+      // Refresh insertion order so capped-map eviction removes the stalest pair, not an active one.
+      agentWatermarks.delete(key);
+    }
+    agentWatermarks.set(key, nextSnapshotIdx);
+    if (agentWatermarks.size > maxWatermarkEntries) {
+      const oldest = agentWatermarks.keys().next().value;
+      if (oldest !== undefined) {
+        agentWatermarks.delete(oldest);
+      }
+    }
+  }
+
+  function rememberPreparedTrigger(
+    queue: RoomQueue,
+    retryKey: string,
+    prepared: PreparedTriggerResult,
+  ): PreparedTriggerResult {
+    if (queue.preparedTriggers.has(retryKey)) {
+      // Refresh insertion order so capped eviction keeps actively retried events hot.
+      queue.preparedTriggers.delete(retryKey);
+    }
+    queue.preparedTriggers.set(retryKey, prepared);
+    if (queue.preparedTriggers.size > maxPreparedTriggerEntries) {
+      const oldest = queue.preparedTriggers.keys().next().value;
+      if (oldest !== undefined) {
+        queue.preparedTriggers.delete(oldest);
+      }
+    }
+    return prepared;
+  }
+
+  function computePendingHistory(
+    queue: RoomQueue,
+    agentId: string,
+    roomId: string,
+    limit: number,
+  ): HistoryEntry[] {
+    if (limit <= 0 || queue.entries.length === 0) {
+      return [];
+    }
+    const wm = agentWatermarks.get(wmKey(agentId, roomId)) ?? 0;
+    // startAbs: the first absolute index the agent hasn't seen yet
+    const startAbs = Math.max(wm, queue.baseIndex);
+    const startRel = startAbs - queue.baseIndex;
+    const available = queue.entries.slice(startRel);
+    return available.length > limit ? available.slice(-limit) : available;
+  }
+
+  return {
+    recordPending(roomId, entry) {
+      const queue = getOrCreateQueue(roomId);
+      appendToQueue(queue, entry);
+    },
+
+    getPendingHistory(agentId, roomId, limit) {
+      const queue = roomQueues.get(roomId);
+      if (!queue) {
+        return [];
+      }
+      return computePendingHistory(queue, agentId, roomId, limit);
+    },
+
+    recordTrigger(roomId, entry) {
+      const queue = getOrCreateQueue(roomId);
+      return appendToQueue(queue, entry);
+    },
+
+    prepareTrigger(agentId, roomId, limit, entry) {
+      const queue = getOrCreateQueue(roomId);
+      const retryKey = preparedTriggerKey(agentId, entry.messageId);
+      if (retryKey) {
+        const prepared = queue.preparedTriggers.get(retryKey);
+        if (prepared) {
+          return rememberPreparedTrigger(queue, retryKey, prepared);
+        }
+      }
+      const prepared = {
+        history: computePendingHistory(queue, agentId, roomId, limit),
+        ...appendToQueue(queue, entry),
+      };
+      if (retryKey) {
+        return rememberPreparedTrigger(queue, retryKey, prepared);
+      }
+      return prepared;
+    },
+
+    consumeHistory(agentId, roomId, snapshot, messageId) {
+      const key = wmKey(agentId, roomId);
+      const queue = roomQueues.get(roomId);
+      if (!queue) {
+        // The room was evicted while this trigger was in flight. Keep eviction authoritative
+        // so a late completion cannot recreate a stale watermark against a fresh queue.
+        agentWatermarks.delete(key);
+        return;
+      }
+      if (queue.generation !== snapshot.queueGeneration) {
+        // The room was evicted and recreated before this trigger completed. Reject the stale
+        // snapshot so it cannot advance or erase state for the new queue generation.
+        return;
+      }
+      // Monotone write: never regress an already-advanced watermark.
+      // Guards against out-of-order completion when two triggers for the same
+      // (agentId, roomId) are in-flight concurrently.
+      rememberWatermark(key, snapshot.snapshotIdx);
+      const retryKey = preparedTriggerKey(agentId, messageId);
+      if (queue && retryKey) {
+        queue.preparedTriggers.delete(retryKey);
+      }
+    },
+  };
+}
+
+export function createRoomHistoryTracker(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTracker {
+  const tracker = createRoomHistoryTrackerInternal(
+    maxQueueSize,
+    maxRoomQueues,
+    maxWatermarkEntries,
+    maxPreparedTriggerEntries,
+  );
+  return {
+    recordPending: tracker.recordPending,
+    prepareTrigger: tracker.prepareTrigger,
+    consumeHistory: tracker.consumeHistory,
+  };
+}
+
+export function createRoomHistoryTrackerForTests(
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxRoomQueues = DEFAULT_MAX_ROOM_QUEUES,
+  maxWatermarkEntries = MAX_WATERMARK_ENTRIES,
+  maxPreparedTriggerEntries = MAX_PREPARED_TRIGGER_ENTRIES,
+): RoomHistoryTrackerTestApi {
+  return createRoomHistoryTrackerInternal(
+    maxQueueSize,
+    maxRoomQueues,
+    maxWatermarkEntries,
+    maxPreparedTriggerEntries,
+  );
+}