@mastra/redis-streams 0.3.0 → 0.4.0-alpha.1

package/dist/index.js

@@ -1,621 +1,593 @@
-import { randomUUID } from 'crypto';
-import { PubSub } from '@mastra/core/events';
-import { createClient } from 'redis';
-
-// src/index.ts
+import { randomUUID } from "crypto";
+import { PubSub } from "@mastra/core/events";
+import { createClient } from "redis";
+//#region src/index.ts
+/**
+* Flatten an error into searchable text. node-redis MULTI failures throw a
+* `MultiErrorReply` whose own message is just "N commands failed…" — the real
+* per-command errors (e.g. BUSYGROUP) live in `err.replies`, so those are
+* folded in too.
+*/
 function errorText(err) {
-  const parts = [err instanceof Error ? err.message : String(err)];
-  if (err instanceof Error && "replies" in err && Array.isArray(err.replies)) {
-    parts.push(...err.replies.map((r) => String(r)));
-  }
-  return parts.join("; ");
+	const parts = [err instanceof Error ? err.message : String(err)];
+	if (err instanceof Error && "replies" in err && Array.isArray(err.replies)) parts.push(...err.replies.map((r) => String(r)));
+	return parts.join("; ");
 }
 var RedisStreamsPubSub = class extends PubSub {
-  // Redis Streams is a pull transport: consumers issue XREADGROUP to read
-  // events. Mastra reads this to know an OrchestrationWorker is required.
-  get supportedModes() {
-    return ["pull"];
-  }
-  #writeClient;
-  #connectOptions;
-  #keyPrefix;
-  #blockMs;
-  #maxStreamLength;
-  #streamIdleTtlMs;
-  #reclaimIntervalMs;
-  #reclaimIdleMs;
-  #maxDeliveryAttempts;
-  #logger;
-  // Keyed by `${topic}::${cbId}` so the same callback can be subscribed to
-  // multiple topics independently. Without the topic in the key,
-  // unsubscribe(otherTopic, cb) would tear down the wrong subscription.
-  #subscriptions = /* @__PURE__ */ new Map();
-  #cbIds = /* @__PURE__ */ new WeakMap();
-  #pendingPublishes = /* @__PURE__ */ new Set();
-  // `localOnly` publishes bypass Redis entirely so values carrying live
-  // methods (e.g. `MastraModelOutput` returned from an evented agent run via
-  // `workflows-finish`) survive intact. Mirrors the same contract honored by
-  // `UnixSocketPubSub` so consumers like `Mastra.__registerInternalWorkflow`
-  // get consistent semantics across transports.
-  #localCallbacks = /* @__PURE__ */ new Map();
-  #closed = false;
-  constructor(options = {}) {
-    super();
-    const url = options.url ?? options.redisOptions?.url ?? "redis://localhost:6379";
-    this.#connectOptions = { ...options.redisOptions, url };
-    this.#writeClient = createClient(this.#connectOptions);
-    this.#logger = options.logger;
-    this.#attachErrorLogger(this.#writeClient, "write");
-    this.#keyPrefix = options.keyPrefix ?? "mastra:topic";
-    this.#blockMs = options.blockMs ?? 1e3;
-    this.#maxStreamLength = options.maxStreamLength ?? 1e4;
-    const ttl = options.streamIdleTtlMs ?? 0;
-    if (!Number.isInteger(ttl) || ttl < 0) {
-      throw new Error(`redis-streams: streamIdleTtlMs must be a non-negative integer (milliseconds), got ${ttl}`);
-    }
-    this.#streamIdleTtlMs = ttl;
-    this.#reclaimIntervalMs = options.reclaimIntervalMs ?? 3e4;
-    this.#reclaimIdleMs = options.reclaimIdleMs ?? 6e4;
-    const cap = options.maxDeliveryAttempts ?? 5;
-    if (cap === 0) {
-      options.logger?.warn?.(
-        "redis-streams: maxDeliveryAttempts=0 is treated as Infinity for back-compat; pass Infinity to disable the cap explicitly."
-      );
-      this.#maxDeliveryAttempts = Infinity;
-    } else if (cap < 0 || Number.isNaN(cap)) {
-      throw new Error(`redis-streams: maxDeliveryAttempts must be >= 1 or Infinity, got ${cap}`);
-    } else {
-      this.#maxDeliveryAttempts = cap;
-    }
-  }
-  /**
-   * Attach the `'error'` listener node-redis requires on every client. Without
-   * one, a mid-life socket close makes the client emit an unhandled `'error'`,
-   * which (per EventEmitter semantics) throws from inside RedisSocket's error
-   * handler BEFORE the built-in reconnect is scheduled — the process gets an
-   * uncaughtException and the client is left permanently un-reconnected
-   * (isOpen=true, isReady=false), hanging every subsequent command. Merely
-   * having a listener lets node-redis's own reconnect run.
-   *
-   * Logged at warn so operators can see connection churn, throttled to one line
-   * per 30s per client: node-redis re-emits `'error'` roughly every 500ms while
-   * a server is unreachable, and with one reader client per subscription an
-   * outage would otherwise flood the logs with thousands of identical lines.
-   */
-  #attachErrorLogger(client, role, extra = {}) {
-    let lastWarnAt = 0;
-    client.on("error", (err) => {
-      const now = Date.now();
-      if (now - lastWarnAt < 3e4) return;
-      lastWarnAt = now;
-      this.#logger?.warn?.(`redis-streams: ${role} client connection error (node-redis will reconnect)`, {
-        ...extra,
-        err: err instanceof Error ? err.message : err
-      });
-    });
-  }
-  #subKey(topic, cb) {
-    let cbId = this.#cbIds.get(cb);
-    if (!cbId) {
-      cbId = randomUUID();
-      this.#cbIds.set(cb, cbId);
-    }
-    return `${topic}::${cbId}`;
-  }
-  /** Lazily connect the shared writer client. Idempotent. */
-  async #ensureWriterConnected() {
-    if (this.#writeClient.isOpen) return;
-    await this.#writeClient.connect();
-  }
-  #streamKey(topic) {
-    return `${this.#keyPrefix}:${topic}`;
-  }
-  async publish(topic, event, options) {
-    if (this.#closed) throw new Error("RedisStreamsPubSub: cannot publish on closed client");
-    if (options?.localOnly) {
-      const localEvent = {
-        ...event,
-        id: randomUUID(),
-        createdAt: /* @__PURE__ */ new Date(),
-        deliveryAttempt: event.deliveryAttempt ?? 1
-      };
-      this.#deliverLocal(topic, localEvent);
-      return;
-    }
-    await this.#ensureWriterConnected();
-    const id = randomUUID();
-    const createdAt = /* @__PURE__ */ new Date();
-    const payload = {
-      ...event,
-      id,
-      createdAt,
-      deliveryAttempt: event.deliveryAttempt ?? 1
-    };
-    const xaddOptions = {};
-    if (this.#maxStreamLength > 0) {
-      xaddOptions.TRIM = {
-        strategy: "MAXLEN",
-        strategyModifier: "~",
-        threshold: this.#maxStreamLength
-      };
-    }
-    const streamKey = this.#streamKey(topic);
-    const promise = this.#streamIdleTtlMs > 0 ? this.#writeClient.multi().xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions).pExpire(streamKey, this.#streamIdleTtlMs).exec().then((replies) => {
-      if (Number(replies[1]) !== 1) {
-        this.#logger?.warn?.("redis-streams: PEXPIRE inside publish MULTI did not apply", {
-          streamKey,
-          reply: String(replies[1])
-        });
-      }
-    }) : this.#writeClient.xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions);
-    this.#pendingPublishes.add(promise);
-    try {
-      await promise;
-    } finally {
-      this.#pendingPublishes.delete(promise);
-    }
-  }
-  async subscribe(topic, cb, options) {
-    if (this.#closed) throw new Error("RedisStreamsPubSub: cannot subscribe on closed client");
-    const key = this.#subKey(topic, cb);
-    if (this.#subscriptions.has(key)) return;
-    let localBucket = this.#localCallbacks.get(topic);
-    if (!localBucket) {
-      localBucket = /* @__PURE__ */ new Set();
-      this.#localCallbacks.set(topic, localBucket);
-    }
-    localBucket.add(cb);
-    await this.#ensureWriterConnected();
-    const isGrouped = !!options?.group;
-    const group = options?.group ?? `__fanout-${randomUUID()}`;
-    const consumer = `${group}-${randomUUID()}`;
-    const streamKey = this.#streamKey(topic);
-    try {
-      await this.#writeClient.xGroupCreate(streamKey, group, "0", { MKSTREAM: true });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (!msg.includes("BUSYGROUP")) throw err;
-      this.#logger?.debug?.("redis-streams: consumer group already exists", { topic, group });
-    }
-    const readClient = createClient(this.#connectOptions);
-    this.#attachErrorLogger(readClient, "read", { topic });
-    await readClient.connect();
-    const sub = {
-      cb,
-      topic,
-      streamKey,
-      group,
-      consumer,
-      isGrouped,
-      readClient,
-      stopped: false,
-      loop: void 0,
-      reclaimTimer: void 0
-    };
-    this.#subscriptions.set(key, sub);
-    sub.loop = this.#runReadLoop(sub);
-    this.#startReclaimLoop(sub);
-  }
-  /**
-   * Periodically run XAUTOCLAIM against this subscription's group so that
-   * messages a crashed/stuck consumer read but never acked get redelivered to
-   * a live sibling. Runs only for grouped subscriptions — fan-out groups are
-   * private to one consumer, so there's no sibling to claim from.
-   */
-  #startReclaimLoop(sub) {
-    if (this.#reclaimIntervalMs <= 0) return;
-    if (!sub.isGrouped) return;
-    const tick = async () => {
-      if (sub.stopped || this.#closed) return;
-      try {
-        const reply = await this.#writeClient.xAutoClaim(
-          sub.streamKey,
-          sub.group,
-          sub.consumer,
-          this.#reclaimIdleMs,
-          "0-0",
-          { COUNT: 100 }
-        );
-        const messages = reply?.messages ?? [];
-        for (const entry of messages) {
-          if (sub.stopped || this.#closed) return;
-          if (!entry) continue;
-          await this.#deliverMessage(sub, entry.id, entry.message);
-        }
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: XAUTOCLAIM failed", {
-          topic: sub.topic,
-          group: sub.group,
-          err: err instanceof Error ? err.message : err
-        });
-      }
-      if (sub.stopped || this.#closed) return;
-      sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
-    };
-    sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
-  }
-  async unsubscribe(topic, cb) {
-    const localBucket = this.#localCallbacks.get(topic);
-    if (localBucket) {
-      localBucket.delete(cb);
-      if (localBucket.size === 0) this.#localCallbacks.delete(topic);
-    }
-    const key = this.#subKey(topic, cb);
-    const sub = this.#subscriptions.get(key);
-    if (!sub) return;
-    this.#subscriptions.delete(key);
-    sub.stopped = true;
-    if (sub.reclaimTimer) {
-      clearTimeout(sub.reclaimTimer);
-      sub.reclaimTimer = void 0;
-    }
-    try {
-      await sub.readClient.quit();
-    } catch (err) {
-      this.#logger?.debug?.("redis-streams: reader quit failed", {
-        topic: sub.topic,
-        err: err instanceof Error ? err.message : err
-      });
-    }
-    if (sub.loop) {
-      try {
-        await sub.loop;
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: read loop exited with error", {
-          topic: sub.topic,
-          err: err instanceof Error ? err.message : err
-        });
-      }
-    }
-    if (!sub.isGrouped) {
-      try {
-        await this.#writeClient.xGroupDestroy(sub.streamKey, sub.group);
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: xGroupDestroy failed", {
-          topic: sub.topic,
-          group: sub.group,
-          err: err instanceof Error ? err.message : err
-        });
-      }
-    }
-  }
-  async flush() {
-    if (this.#pendingPublishes.size > 0) {
-      await Promise.allSettled([...this.#pendingPublishes]);
-    }
-  }
-  /**
-   * Delete a topic's stream, and with it every consumer group on that stream.
-   * This is the Redis implementation of the optional `clearTopic` hook that
-   * consumers (e.g. `DurableAgent`) call to free a topic once its lifecycle is
-   * over — without it, a persistent backend accumulates every finished run's
-   * stream until Redis exhausts its memory.
-   *
-   * Because it removes events for ALL consumers and destroys their groups, only
-   * call it once nothing will read the topic again. A subscriber still attached
-   * when the stream is deleted recovers on its own (the read loop recreates the
-   * group on NOGROUP) but will have missed the deleted entries.
-   *
-   * Best-effort and non-throwing: callers commonly invoke this fire-and-forget
-   * (`void clearTopic(...)`), so a rejection would surface as an
-   * unhandledRejection. Failures are swallowed and logged; the `streamIdleTtlMs`
-   * backstop (when configured) reclaims anything a failed delete leaves behind.
-   */
-  async clearTopic(topic) {
-    if (this.#closed) return;
-    try {
-      await this.#ensureWriterConnected();
-      await this.#writeClient.del(this.#streamKey(topic));
-    } catch (err) {
-      this.#logger?.warn?.("redis-streams: clearTopic failed", {
-        topic,
-        err: err instanceof Error ? err.message : err
-      });
-    }
-  }
-  /**
-   * Lease key used in Redis. Distinct prefix from streams so leases and
-   * streams can't collide on key namespace.
-   */
-  #leaseKey(key) {
-    return `${this.#keyPrefix}:lease:${key}`;
-  }
-  /**
-   * Atomic claim via SET NX PX. Idempotent for the same owner: if the
-   * current value is already this owner, we refresh the TTL instead of
-   * failing. Cross-process callers race here; Redis serializes them.
-   */
-  async acquireLease(key, owner, ttlMs) {
-    if (this.#closed) return { acquired: false };
-    await this.#ensureWriterConnected();
-    const redisKey = this.#leaseKey(key);
-    const result = await this.#writeClient.set(redisKey, owner, { NX: true, PX: ttlMs });
-    if (result === "OK") return { acquired: true, owner };
-    const script = `
+	get supportedModes() {
+		return ["pull"];
+	}
+	get supportsOffsets() {
+		return false;
+	}
+	onUnsupportedOffset(offset) {
+		this.#logger?.warn?.(`redis-streams: numeric replay offset ${offset} is unsupported; falling back to full replay`);
+	}
+	#writeClient;
+	#connectOptions;
+	#keyPrefix;
+	#blockMs;
+	#maxStreamLength;
+	#streamIdleTtlMs;
+	#reclaimIntervalMs;
+	#reclaimIdleMs;
+	#maxDeliveryAttempts;
+	#logger;
+	#subscriptions = /* @__PURE__ */ new Map();
+	#cbIds = /* @__PURE__ */ new WeakMap();
+	#pendingPublishes = /* @__PURE__ */ new Set();
+	#localCallbacks = /* @__PURE__ */ new Map();
+	#closed = false;
+	constructor(options = {}) {
+		super();
+		const url = options.url ?? options.redisOptions?.url ?? "redis://localhost:6379";
+		this.#connectOptions = {
+			...options.redisOptions,
+			url
+		};
+		this.#writeClient = createClient(this.#connectOptions);
+		this.#logger = options.logger;
+		this.#attachErrorLogger(this.#writeClient, "write");
+		this.#keyPrefix = options.keyPrefix ?? "mastra:topic";
+		this.#blockMs = options.blockMs ?? 1e3;
+		this.#maxStreamLength = options.maxStreamLength ?? 1e4;
+		const ttl = options.streamIdleTtlMs ?? 0;
+		if (!Number.isInteger(ttl) || ttl < 0) throw new Error(`redis-streams: streamIdleTtlMs must be a non-negative integer (milliseconds), got ${ttl}`);
+		this.#streamIdleTtlMs = ttl;
+		this.#reclaimIntervalMs = options.reclaimIntervalMs ?? 3e4;
+		this.#reclaimIdleMs = options.reclaimIdleMs ?? 6e4;
+		const cap = options.maxDeliveryAttempts ?? 5;
+		if (cap === 0) {
+			options.logger?.warn?.("redis-streams: maxDeliveryAttempts=0 is treated as Infinity for back-compat; pass Infinity to disable the cap explicitly.");
+			this.#maxDeliveryAttempts = Infinity;
+		} else if (cap < 0 || Number.isNaN(cap)) throw new Error(`redis-streams: maxDeliveryAttempts must be >= 1 or Infinity, got ${cap}`);
+		else this.#maxDeliveryAttempts = cap;
+	}
+	/**
+	* Attach the `'error'` listener node-redis requires on every client. Without
+	* one, a mid-life socket close makes the client emit an unhandled `'error'`,
+	* which (per EventEmitter semantics) throws from inside RedisSocket's error
+	* handler BEFORE the built-in reconnect is scheduled — the process gets an
+	* uncaughtException and the client is left permanently un-reconnected
+	* (isOpen=true, isReady=false), hanging every subsequent command. Merely
+	* having a listener lets node-redis's own reconnect run.
+	*
+	* Logged at warn so operators can see connection churn, throttled to one line
+	* per 30s per client: node-redis re-emits `'error'` roughly every 500ms while
+	* a server is unreachable, and with one reader client per subscription an
+	* outage would otherwise flood the logs with thousands of identical lines.
+	*/
+	#attachErrorLogger(client, role, extra = {}) {
+		let lastWarnAt = 0;
+		client.on("error", (err) => {
+			const now = Date.now();
+			if (now - lastWarnAt < 3e4) return;
+			lastWarnAt = now;
+			this.#logger?.warn?.(`redis-streams: ${role} client connection error (node-redis will reconnect)`, {
+				...extra,
+				err: err instanceof Error ? err.message : err
+			});
+		});
+	}
+	#subKey(topic, cb) {
+		let cbId = this.#cbIds.get(cb);
+		if (!cbId) {
+			cbId = randomUUID();
+			this.#cbIds.set(cb, cbId);
+		}
+		return `${topic}::${cbId}`;
+	}
+	/** Lazily connect the shared writer client. Idempotent. */
+	async #ensureWriterConnected() {
+		if (this.#writeClient.isOpen) return;
+		await this.#writeClient.connect();
+	}
+	#streamKey(topic) {
+		return `${this.#keyPrefix}:${topic}`;
+	}
+	async publish(topic, event, options) {
+		if (this.#closed) throw new Error("RedisStreamsPubSub: cannot publish on closed client");
+		if (options?.localOnly) {
+			const localEvent = {
+				...event,
+				id: randomUUID(),
+				createdAt: /* @__PURE__ */ new Date(),
+				deliveryAttempt: event.deliveryAttempt ?? 1
+			};
+			this.#deliverLocal(topic, localEvent);
+			return;
+		}
+		await this.#ensureWriterConnected();
+		const id = randomUUID();
+		const createdAt = /* @__PURE__ */ new Date();
+		const payload = {
+			...event,
+			id,
+			createdAt,
+			deliveryAttempt: event.deliveryAttempt ?? 1
+		};
+		const xaddOptions = {};
+		if (this.#maxStreamLength > 0) xaddOptions.TRIM = {
+			strategy: "MAXLEN",
+			strategyModifier: "~",
+			threshold: this.#maxStreamLength
+		};
+		const streamKey = this.#streamKey(topic);
+		const promise = this.#streamIdleTtlMs > 0 ? this.#writeClient.multi().xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions).pExpire(streamKey, this.#streamIdleTtlMs).exec().then((replies) => {
+			if (Number(replies[1]) !== 1) this.#logger?.warn?.("redis-streams: PEXPIRE inside publish MULTI did not apply", {
+				streamKey,
+				reply: String(replies[1])
+			});
+		}) : this.#writeClient.xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions);
+		this.#pendingPublishes.add(promise);
+		try {
+			await promise;
+		} finally {
+			this.#pendingPublishes.delete(promise);
+		}
+	}
+	async subscribe(topic, cb, options) {
+		if (this.#closed) throw new Error("RedisStreamsPubSub: cannot subscribe on closed client");
+		const key = this.#subKey(topic, cb);
+		if (this.#subscriptions.has(key)) return;
+		let localBucket = this.#localCallbacks.get(topic);
+		if (!localBucket) {
+			localBucket = /* @__PURE__ */ new Set();
+			this.#localCallbacks.set(topic, localBucket);
+		}
+		localBucket.add(cb);
+		await this.#ensureWriterConnected();
+		const isGrouped = !!options?.group;
+		const group = options?.group ?? `__fanout-${randomUUID()}`;
+		const consumer = `${group}-${randomUUID()}`;
+		const streamKey = this.#streamKey(topic);
+		const groupAnchor = options?.startFrom === "latest" ? "$" : "0";
+		try {
+			if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xGroupCreate(streamKey, group, groupAnchor, { MKSTREAM: true }).pExpire(streamKey, this.#streamIdleTtlMs).exec();
+			else await this.#writeClient.xGroupCreate(streamKey, group, groupAnchor, { MKSTREAM: true });
+		} catch (err) {
+			if (!errorText(err).includes("BUSYGROUP")) throw err;
+			this.#logger?.debug?.("redis-streams: consumer group already exists", {
+				topic,
+				group
+			});
+		}
+		const readClient = createClient(this.#connectOptions);
+		this.#attachErrorLogger(readClient, "read", { topic });
+		await readClient.connect();
+		const sub = {
+			cb,
+			topic,
+			streamKey,
+			group,
+			consumer,
+			isGrouped,
+			groupAnchor,
+			lastId: void 0,
+			readClient,
+			stopped: false,
+			loop: void 0,
+			reclaimTimer: void 0
+		};
+		this.#subscriptions.set(key, sub);
+		sub.loop = this.#runReadLoop(sub);
+		this.#startReclaimLoop(sub);
+	}
+	/**
+	* Periodically run XAUTOCLAIM against this subscription's group so that
+	* messages a crashed/stuck consumer read but never acked get redelivered to
+	* a live sibling. Runs only for grouped subscriptions — fan-out groups are
+	* private to one consumer, so there's no sibling to claim from.
+	*/
+	#startReclaimLoop(sub) {
+		if (this.#reclaimIntervalMs <= 0) return;
+		if (!sub.isGrouped) return;
+		const tick = async () => {
+			if (sub.stopped || this.#closed) return;
+			try {
+				const messages = (await this.#writeClient.xAutoClaim(sub.streamKey, sub.group, sub.consumer, this.#reclaimIdleMs, "0-0", { COUNT: 100 }))?.messages ?? [];
+				for (const entry of messages) {
+					if (sub.stopped || this.#closed) return;
+					if (!entry) continue;
+					await this.#deliverMessage(sub, entry.id, entry.message);
+				}
+			} catch (err) {
+				this.#logger?.debug?.("redis-streams: XAUTOCLAIM failed", {
+					topic: sub.topic,
+					group: sub.group,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+			if (sub.stopped || this.#closed) return;
+			sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+		};
+		sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+	}
+	async unsubscribe(topic, cb) {
+		const localBucket = this.#localCallbacks.get(topic);
+		if (localBucket) {
+			localBucket.delete(cb);
+			if (localBucket.size === 0) this.#localCallbacks.delete(topic);
+		}
+		const key = this.#subKey(topic, cb);
+		const sub = this.#subscriptions.get(key);
+		if (!sub) return;
+		this.#subscriptions.delete(key);
+		sub.stopped = true;
+		if (sub.reclaimTimer) {
+			clearTimeout(sub.reclaimTimer);
+			sub.reclaimTimer = void 0;
+		}
+		try {
+			await sub.readClient.quit();
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: reader quit failed", {
+				topic: sub.topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+		if (sub.loop) try {
+			await sub.loop;
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: read loop exited with error", {
+				topic: sub.topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+		if (!sub.isGrouped) try {
+			await this.#writeClient.xGroupDestroy(sub.streamKey, sub.group);
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: xGroupDestroy failed", {
+				topic: sub.topic,
+				group: sub.group,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
+	async flush() {
+		if (this.#pendingPublishes.size > 0) await Promise.allSettled([...this.#pendingPublishes]);
+	}
+	/**
+	* Delete a topic's stream, and with it every consumer group on that stream.
+	* This is the Redis implementation of the optional `clearTopic` hook that
+	* consumers (e.g. `DurableAgent`) call to free a topic once its lifecycle is
+	* over — without it, a persistent backend accumulates every finished run's
+	* stream until Redis exhausts its memory.
+	*
+	* Because it removes events for ALL consumers and destroys their groups, only
+	* call it once nothing will read the topic again. A subscriber still attached
+	* when the stream is deleted recovers on its own (the read loop recreates the
+	* group on NOGROUP) but will have missed the deleted entries.
+	*
+	* Best-effort and non-throwing: callers commonly invoke this fire-and-forget
+	* (`void clearTopic(...)`), so a rejection would surface as an
+	* unhandledRejection. Failures are swallowed and logged; the `streamIdleTtlMs`
+	* backstop (when configured) reclaims anything a failed delete leaves behind.
+	*/
+	async clearTopic(topic) {
+		if (this.#closed) return;
+		try {
+			await this.#ensureWriterConnected();
+			await this.#writeClient.del(this.#streamKey(topic));
+			for (const sub of this.#subscriptions.values()) if (sub.topic === topic) {
+				sub.lastId = void 0;
+				sub.groupAnchor = "0";
+			}
+		} catch (err) {
+			this.#logger?.warn?.("redis-streams: clearTopic failed", {
+				topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
+	/**
+	* Lease key used in Redis. Distinct prefix from streams so leases and
+	* streams can't collide on key namespace.
+	*/
+	#leaseKey(key) {
+		return `${this.#keyPrefix}:lease:${key}`;
+	}
+	/**
+	* Atomic claim via SET NX PX. Idempotent for the same owner: if the
+	* current value is already this owner, we refresh the TTL instead of
+	* failing. Cross-process callers race here; Redis serializes them.
+	*/
+	async acquireLease(key, owner, ttlMs) {
+		if (this.#closed) return { acquired: false };
+		await this.#ensureWriterConnected();
+		const redisKey = this.#leaseKey(key);
+		if (await this.#writeClient.set(redisKey, owner, {
+			NX: true,
+			PX: ttlMs
+		}) === "OK") return {
+			acquired: true,
+			owner
+		};
+		if (await this.#writeClient.eval(`
       local current = redis.call("GET", KEYS[1])
       if current == ARGV[1] then
         redis.call("PEXPIRE", KEYS[1], ARGV[2])
         return 1
       end
       return 0
-    `;
-    const refreshed = await this.#writeClient.eval(script, {
-      keys: [redisKey],
-      arguments: [owner, String(ttlMs)]
-    });
-    if (refreshed === 1) return { acquired: true, owner };
-    return { acquired: false, owner: await this.#writeClient.get(redisKey) ?? void 0 };
-  }
-  async getLeaseOwner(key) {
-    if (this.#closed) return void 0;
-    await this.#ensureWriterConnected();
-    const current = await this.#writeClient.get(this.#leaseKey(key));
-    return current ?? void 0;
-  }
-  /**
-   * Release only if we still own it. Implemented as GET+DEL with a Lua
-   * script so the check-and-delete is atomic against concurrent renewals
-   * from other processes.
-   */
-  async releaseLease(key, owner) {
-    if (this.#closed) return;
-    await this.#ensureWriterConnected();
-    const script = `
+    `, {
+			keys: [redisKey],
+			arguments: [owner, String(ttlMs)]
+		}) === 1) return {
+			acquired: true,
+			owner
+		};
+		return {
+			acquired: false,
+			owner: await this.#writeClient.get(redisKey) ?? void 0
+		};
+	}
+	async getLeaseOwner(key) {
+		if (this.#closed) return void 0;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.get(this.#leaseKey(key)) ?? void 0;
+	}
+	/**
+	* Release only if we still own it. Implemented as GET+DEL with a Lua
+	* script so the check-and-delete is atomic against concurrent renewals
+	* from other processes.
+	*/
+	async releaseLease(key, owner) {
+		if (this.#closed) return;
+		await this.#ensureWriterConnected();
+		await this.#writeClient.eval(`
       if redis.call("GET", KEYS[1]) == ARGV[1] then
         return redis.call("DEL", KEYS[1])
       else
         return 0
       end
-    `;
-    await this.#writeClient.eval(script, {
-      keys: [this.#leaseKey(key)],
-      arguments: [owner]
-    });
-  }
-  /**
-   * Extend the TTL only if we still own the lease. Returns false if the
-   * lease was lost (expired or another owner took it).
-   */
-  async renewLease(key, owner, ttlMs) {
-    if (this.#closed) return false;
-    await this.#ensureWriterConnected();
-    const script = `
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [owner]
+		});
+	}
+	/**
+	* Extend the TTL only if we still own the lease. Returns false if the
+	* lease was lost (expired or another owner took it).
+	*/
+	async renewLease(key, owner, ttlMs) {
+		if (this.#closed) return false;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.eval(`
       if redis.call("GET", KEYS[1]) == ARGV[1] then
         return redis.call("PEXPIRE", KEYS[1], ARGV[2])
       else
         return 0
       end
-    `;
-    const result = await this.#writeClient.eval(script, {
-      keys: [this.#leaseKey(key)],
-      arguments: [owner, String(ttlMs)]
-    });
-    return result === 1;
-  }
-  /**
-   * Atomically hand the lease from `fromOwner` to `toOwner`, refreshing the
-   * TTL to the full `ttlMs`, without the key ever going empty.
-   *
-   * Implemented as a single Lua script (GET == fromOwner -> SET toOwner PX)
-   * so a racing process cannot win the key between a release and a re-acquire.
-   * Returns false if `fromOwner` no longer holds the lease (expired or taken),
-   * in which case the caller should fall back to a fresh `acquireLease`.
-   */
-  async transferLease(key, fromOwner, toOwner, ttlMs) {
-    if (this.#closed) return false;
-    await this.#ensureWriterConnected();
-    const script = `
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [owner, String(ttlMs)]
+		}) === 1;
+	}
+	/**
+	* Atomically hand the lease from `fromOwner` to `toOwner`, refreshing the
+	* TTL to the full `ttlMs`, without the key ever going empty.
+	*
+	* Implemented as a single Lua script (GET == fromOwner -> SET toOwner PX)
+	* so a racing process cannot win the key between a release and a re-acquire.
+	* Returns false if `fromOwner` no longer holds the lease (expired or taken),
+	* in which case the caller should fall back to a fresh `acquireLease`.
+	*/
+	async transferLease(key, fromOwner, toOwner, ttlMs) {
+		if (this.#closed) return false;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.eval(`
       if redis.call("GET", KEYS[1]) == ARGV[1] then
         redis.call("SET", KEYS[1], ARGV[2], "PX", ARGV[3])
         return 1
       else
         return 0
       end
-    `;
-    const result = await this.#writeClient.eval(script, {
-      keys: [this.#leaseKey(key)],
-      arguments: [fromOwner, toOwner, String(ttlMs)]
-    });
-    return result === 1;
-  }
-  /**
-   * Disconnect all clients and stop all subscription loops.
-   */
-  async close() {
-    if (this.#closed) return;
-    this.#closed = true;
-    const subs = [...this.#subscriptions.values()];
-    await Promise.all(subs.map((sub) => this.unsubscribe(sub.topic, sub.cb)));
-    this.#localCallbacks.clear();
-    if (this.#writeClient.isOpen) {
-      try {
-        await this.#writeClient.quit();
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: writer quit failed", {
-          err: err instanceof Error ? err.message : err
-        });
-      }
-    }
-  }
-  async #runReadLoop(sub) {
-    while (!sub.stopped) {
-      let result;
-      try {
-        result = await sub.readClient.xReadGroup(sub.group, sub.consumer, [{ key: sub.streamKey, id: ">" }], {
-          COUNT: 10,
-          BLOCK: this.#blockMs
-        });
-      } catch (err) {
-        if (sub.stopped) return;
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes("NOGROUP")) {
-          try {
-            if (this.#streamIdleTtlMs > 0) {
-              await this.#writeClient.multi().xGroupCreate(sub.streamKey, sub.group, "0", { MKSTREAM: true }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
-            } else {
-              await this.#writeClient.xGroupCreate(sub.streamKey, sub.group, "0", { MKSTREAM: true });
-            }
-            this.#logger?.debug?.("redis-streams: recreated consumer group after NOGROUP", {
-              topic: sub.topic,
-              group: sub.group
-            });
-          } catch (recreateErr) {
-            const rmsg = errorText(recreateErr);
-            if (!rmsg.includes("BUSYGROUP")) {
-              this.#logger?.debug?.("redis-streams: consumer group re-create failed", { topic: sub.topic, err: rmsg });
-            }
-          }
-        } else {
-          this.#logger?.debug?.("redis-streams: xReadGroup failed", {
-            topic: sub.topic,
-            group: sub.group,
-            err: msg
-          });
-        }
-        await new Promise((r) => setTimeout(r, 100));
-        continue;
-      }
-      if (!result || result.length === 0) continue;
-      for (const stream of result) {
-        for (const entry of stream.messages) {
-          if (sub.stopped) return;
-          await this.#deliverMessage(sub, entry.id, entry.message);
-        }
-      }
-    }
-  }
-  async #deliverMessage(sub, streamId, fields) {
-    let event;
-    try {
-      event = JSON.parse(fields.event ?? "{}");
-      if (typeof event.createdAt === "string") {
-        event.createdAt = new Date(event.createdAt);
-      }
-    } catch (err) {
-      this.#logger?.debug?.("redis-streams: malformed payload, dropping", {
-        topic: sub.topic,
-        streamId,
-        err: err instanceof Error ? err.message : err
-      });
-      try {
-        await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
-      } catch (ackErr) {
-        this.#logger?.debug?.("redis-streams: xAck after malformed payload failed", {
-          topic: sub.topic,
-          err: ackErr instanceof Error ? ackErr.message : ackErr
-        });
-      }
-      return;
-    }
-    let settled = false;
-    const ack = async () => {
-      if (settled) return;
-      settled = true;
-      try {
-        await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: ack cleanup failed", {
-          topic: sub.topic,
-          err: err instanceof Error ? err.message : err
-        });
-      }
-    };
-    const nack = async () => {
-      if (settled) return;
-      settled = true;
-      const attempt = event.deliveryAttempt ?? 1;
-      if (attempt >= this.#maxDeliveryAttempts) {
-        this.#logger?.warn?.("redis-streams: dropping event after max delivery attempts", {
-          topic: sub.topic,
-          eventType: event.type,
-          eventId: event.id,
-          attempt,
-          max: this.#maxDeliveryAttempts
-        });
-        try {
-          await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
-        } catch (err) {
-          this.#logger?.debug?.("redis-streams: ack on dropped poison message failed", {
-            topic: sub.topic,
-            err: err instanceof Error ? err.message : err
-          });
-        }
-        return;
-      }
-      const next = {
-        ...event,
-        deliveryAttempt: attempt + 1
-      };
-      try {
-        if (this.#streamIdleTtlMs > 0) {
-          await this.#writeClient.multi().xAdd(sub.streamKey, "*", { event: JSON.stringify(next) }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
-        } else {
-          await this.#writeClient.xAdd(sub.streamKey, "*", { event: JSON.stringify(next) });
-        }
-      } catch (err) {
-        this.#logger?.warn?.("redis-streams: nack republish failed; leaving original pending for reclaim", {
-          topic: sub.topic,
-          eventId: event.id,
-          err: err instanceof Error ? err.message : err
-        });
-        settled = false;
-        return;
-      }
-      try {
-        await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
-      } catch (err) {
-        this.#logger?.debug?.("redis-streams: xAck after nack failed", {
-          topic: sub.topic,
-          err: err instanceof Error ? err.message : err
-        });
-      }
-    };
-    try {
-      const result = sub.cb(event, ack, nack);
-      if (result && typeof result.catch === "function") {
-        result.catch(async () => {
-          await nack();
-        });
-      }
-    } catch {
-      await nack();
-    }
-  }
-  #deliverLocal(topic, event) {
-    const callbacks = this.#localCallbacks.get(topic);
-    if (!callbacks || callbacks.size === 0) return;
-    for (const cb of callbacks) {
-      this.#invokeLocalCallback(topic, event, cb);
-    }
-  }
-  #invokeLocalCallback(topic, event, cb) {
-    const ack = async () => {
-    };
-    const nack = async () => {
-    };
-    try {
-      const result = cb(
-        event,
-        ack,
-        nack
-      );
-      if (result && typeof result.catch === "function") {
-        result.catch((err) => {
-          this.#logger?.debug?.("redis-streams: local subscriber rejected", {
-            topic,
-            err: err instanceof Error ? err.message : err
-          });
-        });
-      }
-    } catch (err) {
-      this.#logger?.debug?.("redis-streams: local subscriber threw", {
-        topic,
-        err: err instanceof Error ? err.message : err
-      });
-    }
-  }
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [
+				fromOwner,
+				toOwner,
+				String(ttlMs)
+			]
+		}) === 1;
+	}
+	/**
+	* Disconnect all clients and stop all subscription loops.
+	*/
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		const subs = [...this.#subscriptions.values()];
+		await Promise.all(subs.map((sub) => this.unsubscribe(sub.topic, sub.cb)));
+		this.#localCallbacks.clear();
+		if (this.#writeClient.isOpen) try {
+			await this.#writeClient.quit();
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: writer quit failed", { err: err instanceof Error ? err.message : err });
+		}
+	}
+	async #runReadLoop(sub) {
+		while (!sub.stopped) {
+			let result;
+			try {
+				result = await sub.readClient.xReadGroup(sub.group, sub.consumer, [{
+					key: sub.streamKey,
+					id: ">"
+				}], {
+					COUNT: 10,
+					BLOCK: this.#blockMs
+				});
+			} catch (err) {
+				if (sub.stopped) return;
+				const msg = err instanceof Error ? err.message : String(err);
+				if (msg.includes("NOGROUP")) {
+					const recoveryAnchor = sub.lastId ?? sub.groupAnchor;
+					try {
+						if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xGroupCreate(sub.streamKey, sub.group, recoveryAnchor, { MKSTREAM: true }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
+						else await this.#writeClient.xGroupCreate(sub.streamKey, sub.group, recoveryAnchor, { MKSTREAM: true });
+						this.#logger?.debug?.("redis-streams: recreated consumer group after NOGROUP", {
+							topic: sub.topic,
+							group: sub.group
+						});
+					} catch (recreateErr) {
+						const rmsg = errorText(recreateErr);
+						if (!rmsg.includes("BUSYGROUP")) this.#logger?.debug?.("redis-streams: consumer group re-create failed", {
+							topic: sub.topic,
+							err: rmsg
+						});
+					}
+				} else this.#logger?.debug?.("redis-streams: xReadGroup failed", {
+					topic: sub.topic,
+					group: sub.group,
+					err: msg
+				});
+				await new Promise((r) => setTimeout(r, 100));
+				continue;
+			}
+			if (!result || result.length === 0) continue;
+			for (const stream of result) for (const entry of stream.messages) {
+				if (sub.stopped) return;
+				sub.lastId = entry.id;
+				await this.#deliverMessage(sub, entry.id, entry.message);
+			}
+		}
+	}
+	async #deliverMessage(sub, streamId, fields) {
+		let event;
+		try {
+			event = JSON.parse(fields.event ?? "{}");
+			if (typeof event.createdAt === "string") event.createdAt = new Date(event.createdAt);
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: malformed payload, dropping", {
+				topic: sub.topic,
+				streamId,
+				err: err instanceof Error ? err.message : err
+			});
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (ackErr) {
+				this.#logger?.debug?.("redis-streams: xAck after malformed payload failed", {
+					topic: sub.topic,
+					err: ackErr instanceof Error ? ackErr.message : ackErr
+				});
+			}
+			return;
+		}
+		let settled = false;
+		const ack = async () => {
+			if (settled) return;
+			settled = true;
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (err) {
+				this.#logger?.debug?.("redis-streams: ack cleanup failed", {
+					topic: sub.topic,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+		};
+		const nack = async () => {
+			if (settled) return;
+			settled = true;
+			const attempt = event.deliveryAttempt ?? 1;
+			if (attempt >= this.#maxDeliveryAttempts) {
+				this.#logger?.warn?.("redis-streams: dropping event after max delivery attempts", {
+					topic: sub.topic,
+					eventType: event.type,
+					eventId: event.id,
+					attempt,
+					max: this.#maxDeliveryAttempts
+				});
+				try {
+					await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+				} catch (err) {
+					this.#logger?.debug?.("redis-streams: ack on dropped poison message failed", {
+						topic: sub.topic,
+						err: err instanceof Error ? err.message : err
+					});
+				}
+				return;
+			}
+			const next = {
+				...event,
+				deliveryAttempt: attempt + 1
+			};
+			try {
+				if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xAdd(sub.streamKey, "*", { event: JSON.stringify(next) }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
+				else await this.#writeClient.xAdd(sub.streamKey, "*", { event: JSON.stringify(next) });
+			} catch (err) {
+				this.#logger?.warn?.("redis-streams: nack republish failed; leaving original pending for reclaim", {
+					topic: sub.topic,
+					eventId: event.id,
+					err: err instanceof Error ? err.message : err
+				});
+				settled = false;
+				return;
+			}
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (err) {
+				this.#logger?.debug?.("redis-streams: xAck after nack failed", {
+					topic: sub.topic,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+		};
+		try {
+			const result = sub.cb(event, ack, nack);
+			if (result && typeof result.catch === "function") result.catch(async () => {
+				await nack();
+			});
+		} catch {
+			await nack();
+		}
+	}
+	#deliverLocal(topic, event) {
+		const callbacks = this.#localCallbacks.get(topic);
+		if (!callbacks || callbacks.size === 0) return;
+		for (const cb of callbacks) this.#invokeLocalCallback(topic, event, cb);
+	}
+	#invokeLocalCallback(topic, event, cb) {
+		const ack = async () => {};
+		const nack = async () => {};
+		try {
+			const result = cb(event, ack, nack);
+			if (result && typeof result.catch === "function") result.catch((err) => {
+				this.#logger?.debug?.("redis-streams: local subscriber rejected", {
+					topic,
+					err: err instanceof Error ? err.message : err
+				});
+			});
+		} catch (err) {
+			this.#logger?.debug?.("redis-streams: local subscriber threw", {
+				topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
 };
-
+//#endregion
 export { RedisStreamsPubSub };
-//# sourceMappingURL=index.js.map
+
 //# sourceMappingURL=index.js.map