@dudousxd/nestjs-agent 0.3.2 → 0.3.3

package/dist/sink-redis/index.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sink-redis/index.ts
+var sink_redis_exports = {};
+__export(sink_redis_exports, {
+  RedisTokenStreamSink: () => RedisTokenStreamSink
+});
+module.exports = __toCommonJS(sink_redis_exports);
+
+// src/sink-redis/redis-token-stream-sink.ts
+var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
+var CHUNK_FIELD = "c";
+var END_FIELD = "e";
+var FAIL_FIELD = "f";
+var RedisTokenStreamSink = class {
+  static {
+    __name(this, "RedisTokenStreamSink");
+  }
+  redis;
+  keyPrefix;
+  ttlSeconds;
+  blockMs;
+  constructor(redis, options = {}) {
+    this.redis = redis;
+    this.keyPrefix = options.keyPrefix ?? "agent:sink:";
+    this.ttlSeconds = options.ttlSeconds ?? 3600;
+    this.blockMs = options.blockMs ?? 5e3;
+  }
+  key(runId) {
+    return `${this.keyPrefix}${runId}`;
+  }
+  open(runId) {
+    const key = this.key(runId);
+    return {
+      write: /* @__PURE__ */ __name(async (chunk) => {
+        await this.redis.xadd(key, "*", CHUNK_FIELD, Buffer.from(chunk));
+      }, "write"),
+      end: /* @__PURE__ */ __name(async () => {
+        await this.redis.xadd(key, "*", END_FIELD, "1");
+        await this.redis.expire(key, this.ttlSeconds);
+      }, "end"),
+      fail: /* @__PURE__ */ __name(async (error) => {
+        await this.redis.xadd(key, "*", FAIL_FIELD, JSON.stringify(error));
+        await this.redis.expire(key, this.ttlSeconds);
+      }, "fail")
+    };
+  }
+  async *subscribe(runId) {
+    const key = this.key(runId);
+    const reader = this.redis.duplicate();
+    try {
+      let lastId = "0";
+      while (true) {
+        const response = await reader.xreadBuffer("BLOCK", this.blockMs, "STREAMS", key, lastId);
+        for (const entry of readEntries(response)) {
+          lastId = entry.id;
+          if (entry.field === CHUNK_FIELD && entry.value !== void 0) {
+            yield new Uint8Array(entry.value);
+          } else if (entry.field === END_FIELD) {
+            return;
+          } else if (entry.field === FAIL_FIELD && entry.value !== void 0) {
+            throw new import_nestjs_agent_core.AgentStreamError(parseStreamError(entry.value.toString()));
+          }
+        }
+      }
+    } finally {
+      reader.disconnect();
+    }
+  }
+  async close(runId) {
+    await this.redis.del(this.key(runId));
+  }
+};
+function readEntries(response) {
+  if (!Array.isArray(response)) {
+    return [];
+  }
+  const entries = [];
+  for (const stream of response) {
+    if (!Array.isArray(stream) || !Array.isArray(stream[1])) {
+      continue;
+    }
+    for (const item of stream[1]) {
+      if (!Array.isArray(item) || item.length < 2) {
+        continue;
+      }
+      const [id, fields] = item;
+      if (!Buffer.isBuffer(id) || !Array.isArray(fields)) {
+        continue;
+      }
+      const field = Buffer.isBuffer(fields[0]) ? fields[0].toString() : void 0;
+      if (field === void 0) {
+        continue;
+      }
+      entries.push({
+        id: id.toString(),
+        field,
+        value: Buffer.isBuffer(fields[1]) ? fields[1] : void 0
+      });
+    }
+  }
+  return entries;
+}
+__name(readEntries, "readEntries");
+function parseStreamError(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "code" in parsed && "message" in parsed && typeof parsed.code === "string" && typeof parsed.message === "string") {
+      return {
+        code: parsed.code,
+        message: parsed.message
+      };
+    }
+  } catch {
+  }
+  return {
+    code: "stream_failed",
+    message: raw
+  };
+}
+__name(parseStreamError, "parseStreamError");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RedisTokenStreamSink
+});
+//# sourceMappingURL=index.cjs.map

package/dist/sink-redis/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sink-redis/index.ts","../../src/sink-redis/redis-token-stream-sink.ts"],"sourcesContent":["export {\n  RedisTokenStreamSink,\n  type RedisTokenStreamSinkOptions,\n} from './redis-token-stream-sink.js';\n","import {\n  AgentStreamError,\n  type SinkWriter,\n  type StreamError,\n  type TokenStreamSink,\n} from '@dudousxd/nestjs-agent-core';\nimport type { Redis } from 'ioredis';\n\nexport interface RedisTokenStreamSinkOptions {\n  /** Key namespace for the per-run streams. Default `agent:sink:`. */\n  keyPrefix?: string;\n  /**\n   * TTL (seconds) applied to a run's stream once it ends/fails, so completed streams self-expire\n   * instead of accumulating in Redis. A subscriber that reconnects within the window still replays.\n   * Default 3600 (1h).\n   */\n  ttlSeconds?: number;\n  /** `XREAD BLOCK` timeout (ms) between follow polls. Default 5000. Purely an internal cadence. */\n  blockMs?: number;\n}\n\n// One-character field names keep each stream entry's payload minimal (one XADD per token delta).\nconst CHUNK_FIELD = 'c';\nconst END_FIELD = 'e';\nconst FAIL_FIELD = 'f';\n\n/**\n * A cross-process {@link TokenStreamSink} backed by Redis Streams — the \"data plane\" for durable\n * agent turns whose model call runs on a WORKER pod while the SSE connection is served by an API\n * pod. The turn `XADD`s each delta to `agent:sink:<runId>`; a subscriber `XREAD`s from `0` so it\n * REPLAYS everything buffered so far (a reconnect or a subscriber that attaches after the run\n * started misses nothing), then blocks for live entries until an `end`/`fail` sentinel.\n *\n * The consumer supplies the ioredis client (so the lib stays Redis-driver-agnostic and reuses the\n * app's connection config). Blocking reads monopolise a connection, so each `subscribe` runs on a\n * short-lived `duplicate()` that is disconnected when the subscriber stops.\n */\nexport class RedisTokenStreamSink implements TokenStreamSink {\n  private readonly keyPrefix: string;\n  private readonly ttlSeconds: number;\n  private readonly blockMs: number;\n\n  constructor(\n    private readonly redis: Redis,\n    options: RedisTokenStreamSinkOptions = {},\n  ) {\n    this.keyPrefix = options.keyPrefix ?? 'agent:sink:';\n    this.ttlSeconds = options.ttlSeconds ?? 3600;\n    this.blockMs = options.blockMs ?? 5000;\n  }\n\n  private key(runId: string): string {\n    return `${this.keyPrefix}${runId}`;\n  }\n\n  open(runId: string): SinkWriter {\n    const key = this.key(runId);\n    return {\n      write: async (chunk: Uint8Array) => {\n        await this.redis.xadd(key, '*', CHUNK_FIELD, Buffer.from(chunk));\n      },\n      end: async () => {\n        await this.redis.xadd(key, '*', END_FIELD, '1');\n        await this.redis.expire(key, this.ttlSeconds);\n      },\n      fail: async (error: StreamError) => {\n        await this.redis.xadd(key, '*', FAIL_FIELD, JSON.stringify(error));\n        await this.redis.expire(key, this.ttlSeconds);\n      },\n    };\n  }\n\n  async *subscribe(runId: string): AsyncIterable<Uint8Array> {\n    const key = this.key(runId);\n    // Blocking XREAD holds the connection for the whole poll, so follow on a dedicated one.\n    const reader = this.redis.duplicate();\n    try {\n      let lastId = '0';\n      while (true) {\n        const response = await reader.xreadBuffer('BLOCK', this.blockMs, 'STREAMS', key, lastId);\n        for (const entry of readEntries(response)) {\n          lastId = entry.id;\n          if (entry.field === CHUNK_FIELD && entry.value !== undefined) {\n            yield new Uint8Array(entry.value);\n          } else if (entry.field === END_FIELD) {\n            return;\n          } else if (entry.field === FAIL_FIELD && entry.value !== undefined) {\n            throw new AgentStreamError(parseStreamError(entry.value.toString()));\n          }\n        }\n      }\n    } finally {\n      reader.disconnect();\n    }\n  }\n\n  async close(runId: string): Promise<void> {\n    await this.redis.del(this.key(runId));\n  }\n}\n\ninterface StreamEntry {\n  id: string;\n  field: string;\n  value: Buffer | undefined;\n}\n\n/**\n * Flatten ioredis's `XREAD` buffer response — `[[key, [[id, [field, value, …]], …]], …] | null` —\n * into the entries we care about. Validated defensively at runtime (it crosses the Redis boundary)\n * rather than trusting the driver's loose typing.\n */\nfunction readEntries(response: unknown): StreamEntry[] {\n  if (!Array.isArray(response)) {\n    return [];\n  }\n  const entries: StreamEntry[] = [];\n  for (const stream of response) {\n    if (!Array.isArray(stream) || !Array.isArray(stream[1])) {\n      continue;\n    }\n    for (const item of stream[1]) {\n      if (!Array.isArray(item) || item.length < 2) {\n        continue;\n      }\n      const [id, fields] = item;\n      if (!Buffer.isBuffer(id) || !Array.isArray(fields)) {\n        continue;\n      }\n      const field = Buffer.isBuffer(fields[0]) ? fields[0].toString() : undefined;\n      if (field === undefined) {\n        continue;\n      }\n      entries.push({\n        id: id.toString(),\n        field,\n        value: Buffer.isBuffer(fields[1]) ? fields[1] : undefined,\n      });\n    }\n  }\n  return entries;\n}\n\n/** Parse a `fail` sentinel's payload back into a {@link StreamError}, tolerating malformed JSON. */\nfunction parseStreamError(raw: string): StreamError {\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (\n      typeof parsed === 'object' &&\n      parsed !== null &&\n      'code' in parsed &&\n      'message' in parsed &&\n      typeof parsed.code === 'string' &&\n      typeof parsed.message === 'string'\n    ) {\n      return { code: parsed.code, message: parsed.message };\n    }\n  } catch {\n    // fall through to the generic terminal below\n  }\n  return { code: 'stream_failed', message: raw };\n}\n"],"mappings":"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","names":["CHUNK_FIELD","END_FIELD","FAIL_FIELD","RedisTokenStreamSink","keyPrefix","ttlSeconds","blockMs","redis","options","key","runId","open","write","chunk","xadd","Buffer","from","end","expire","fail","error","JSON","stringify","subscribe","reader","duplicate","lastId","response","xreadBuffer","entry","readEntries","id","field","value","undefined","Uint8Array","AgentStreamError","parseStreamError","toString","disconnect","close","del","Array","isArray","entries","stream","item","length","fields","isBuffer","push","raw","parsed","parse","code","message"]}

package/dist/sink-redis/index.d.cts

@@ -0,0 +1,39 @@
+import { TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { Redis } from 'ioredis';
+
+interface RedisTokenStreamSinkOptions {
+    /** Key namespace for the per-run streams. Default `agent:sink:`. */
+    keyPrefix?: string;
+    /**
+     * TTL (seconds) applied to a run's stream once it ends/fails, so completed streams self-expire
+     * instead of accumulating in Redis. A subscriber that reconnects within the window still replays.
+     * Default 3600 (1h).
+     */
+    ttlSeconds?: number;
+    /** `XREAD BLOCK` timeout (ms) between follow polls. Default 5000. Purely an internal cadence. */
+    blockMs?: number;
+}
+/**
+ * A cross-process {@link TokenStreamSink} backed by Redis Streams — the "data plane" for durable
+ * agent turns whose model call runs on a WORKER pod while the SSE connection is served by an API
+ * pod. The turn `XADD`s each delta to `agent:sink:<runId>`; a subscriber `XREAD`s from `0` so it
+ * REPLAYS everything buffered so far (a reconnect or a subscriber that attaches after the run
+ * started misses nothing), then blocks for live entries until an `end`/`fail` sentinel.
+ *
+ * The consumer supplies the ioredis client (so the lib stays Redis-driver-agnostic and reuses the
+ * app's connection config). Blocking reads monopolise a connection, so each `subscribe` runs on a
+ * short-lived `duplicate()` that is disconnected when the subscriber stops.
+ */
+declare class RedisTokenStreamSink implements TokenStreamSink {
+    private readonly redis;
+    private readonly keyPrefix;
+    private readonly ttlSeconds;
+    private readonly blockMs;
+    constructor(redis: Redis, options?: RedisTokenStreamSinkOptions);
+    private key;
+    open(runId: string): SinkWriter;
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    close(runId: string): Promise<void>;
+}
+
+export { RedisTokenStreamSink, type RedisTokenStreamSinkOptions };

package/dist/sink-redis/index.d.ts

@@ -0,0 +1,39 @@
+import { TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { Redis } from 'ioredis';
+
+interface RedisTokenStreamSinkOptions {
+    /** Key namespace for the per-run streams. Default `agent:sink:`. */
+    keyPrefix?: string;
+    /**
+     * TTL (seconds) applied to a run's stream once it ends/fails, so completed streams self-expire
+     * instead of accumulating in Redis. A subscriber that reconnects within the window still replays.
+     * Default 3600 (1h).
+     */
+    ttlSeconds?: number;
+    /** `XREAD BLOCK` timeout (ms) between follow polls. Default 5000. Purely an internal cadence. */
+    blockMs?: number;
+}
+/**
+ * A cross-process {@link TokenStreamSink} backed by Redis Streams — the "data plane" for durable
+ * agent turns whose model call runs on a WORKER pod while the SSE connection is served by an API
+ * pod. The turn `XADD`s each delta to `agent:sink:<runId>`; a subscriber `XREAD`s from `0` so it
+ * REPLAYS everything buffered so far (a reconnect or a subscriber that attaches after the run
+ * started misses nothing), then blocks for live entries until an `end`/`fail` sentinel.
+ *
+ * The consumer supplies the ioredis client (so the lib stays Redis-driver-agnostic and reuses the
+ * app's connection config). Blocking reads monopolise a connection, so each `subscribe` runs on a
+ * short-lived `duplicate()` that is disconnected when the subscriber stops.
+ */
+declare class RedisTokenStreamSink implements TokenStreamSink {
+    private readonly redis;
+    private readonly keyPrefix;
+    private readonly ttlSeconds;
+    private readonly blockMs;
+    constructor(redis: Redis, options?: RedisTokenStreamSinkOptions);
+    private key;
+    open(runId: string): SinkWriter;
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    close(runId: string): Promise<void>;
+}
+
+export { RedisTokenStreamSink, type RedisTokenStreamSinkOptions };

package/dist/sink-redis/index.js

@@ -0,0 +1,119 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/sink-redis/redis-token-stream-sink.ts
+import { AgentStreamError } from "@dudousxd/nestjs-agent-core";
+var CHUNK_FIELD = "c";
+var END_FIELD = "e";
+var FAIL_FIELD = "f";
+var RedisTokenStreamSink = class {
+  static {
+    __name(this, "RedisTokenStreamSink");
+  }
+  redis;
+  keyPrefix;
+  ttlSeconds;
+  blockMs;
+  constructor(redis, options = {}) {
+    this.redis = redis;
+    this.keyPrefix = options.keyPrefix ?? "agent:sink:";
+    this.ttlSeconds = options.ttlSeconds ?? 3600;
+    this.blockMs = options.blockMs ?? 5e3;
+  }
+  key(runId) {
+    return `${this.keyPrefix}${runId}`;
+  }
+  open(runId) {
+    const key = this.key(runId);
+    return {
+      write: /* @__PURE__ */ __name(async (chunk) => {
+        await this.redis.xadd(key, "*", CHUNK_FIELD, Buffer.from(chunk));
+      }, "write"),
+      end: /* @__PURE__ */ __name(async () => {
+        await this.redis.xadd(key, "*", END_FIELD, "1");
+        await this.redis.expire(key, this.ttlSeconds);
+      }, "end"),
+      fail: /* @__PURE__ */ __name(async (error) => {
+        await this.redis.xadd(key, "*", FAIL_FIELD, JSON.stringify(error));
+        await this.redis.expire(key, this.ttlSeconds);
+      }, "fail")
+    };
+  }
+  async *subscribe(runId) {
+    const key = this.key(runId);
+    const reader = this.redis.duplicate();
+    try {
+      let lastId = "0";
+      while (true) {
+        const response = await reader.xreadBuffer("BLOCK", this.blockMs, "STREAMS", key, lastId);
+        for (const entry of readEntries(response)) {
+          lastId = entry.id;
+          if (entry.field === CHUNK_FIELD && entry.value !== void 0) {
+            yield new Uint8Array(entry.value);
+          } else if (entry.field === END_FIELD) {
+            return;
+          } else if (entry.field === FAIL_FIELD && entry.value !== void 0) {
+            throw new AgentStreamError(parseStreamError(entry.value.toString()));
+          }
+        }
+      }
+    } finally {
+      reader.disconnect();
+    }
+  }
+  async close(runId) {
+    await this.redis.del(this.key(runId));
+  }
+};
+function readEntries(response) {
+  if (!Array.isArray(response)) {
+    return [];
+  }
+  const entries = [];
+  for (const stream of response) {
+    if (!Array.isArray(stream) || !Array.isArray(stream[1])) {
+      continue;
+    }
+    for (const item of stream[1]) {
+      if (!Array.isArray(item) || item.length < 2) {
+        continue;
+      }
+      const [id, fields] = item;
+      if (!Buffer.isBuffer(id) || !Array.isArray(fields)) {
+        continue;
+      }
+      const field = Buffer.isBuffer(fields[0]) ? fields[0].toString() : void 0;
+      if (field === void 0) {
+        continue;
+      }
+      entries.push({
+        id: id.toString(),
+        field,
+        value: Buffer.isBuffer(fields[1]) ? fields[1] : void 0
+      });
+    }
+  }
+  return entries;
+}
+__name(readEntries, "readEntries");
+function parseStreamError(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "code" in parsed && "message" in parsed && typeof parsed.code === "string" && typeof parsed.message === "string") {
+      return {
+        code: parsed.code,
+        message: parsed.message
+      };
+    }
+  } catch {
+  }
+  return {
+    code: "stream_failed",
+    message: raw
+  };
+}
+__name(parseStreamError, "parseStreamError");
+export {
+  RedisTokenStreamSink
+};
+//# sourceMappingURL=index.js.map

package/dist/sink-redis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sink-redis/redis-token-stream-sink.ts"],"sourcesContent":["import {\n  AgentStreamError,\n  type SinkWriter,\n  type StreamError,\n  type TokenStreamSink,\n} from '@dudousxd/nestjs-agent-core';\nimport type { Redis } from 'ioredis';\n\nexport interface RedisTokenStreamSinkOptions {\n  /** Key namespace for the per-run streams. Default `agent:sink:`. */\n  keyPrefix?: string;\n  /**\n   * TTL (seconds) applied to a run's stream once it ends/fails, so completed streams self-expire\n   * instead of accumulating in Redis. A subscriber that reconnects within the window still replays.\n   * Default 3600 (1h).\n   */\n  ttlSeconds?: number;\n  /** `XREAD BLOCK` timeout (ms) between follow polls. Default 5000. Purely an internal cadence. */\n  blockMs?: number;\n}\n\n// One-character field names keep each stream entry's payload minimal (one XADD per token delta).\nconst CHUNK_FIELD = 'c';\nconst END_FIELD = 'e';\nconst FAIL_FIELD = 'f';\n\n/**\n * A cross-process {@link TokenStreamSink} backed by Redis Streams — the \"data plane\" for durable\n * agent turns whose model call runs on a WORKER pod while the SSE connection is served by an API\n * pod. The turn `XADD`s each delta to `agent:sink:<runId>`; a subscriber `XREAD`s from `0` so it\n * REPLAYS everything buffered so far (a reconnect or a subscriber that attaches after the run\n * started misses nothing), then blocks for live entries until an `end`/`fail` sentinel.\n *\n * The consumer supplies the ioredis client (so the lib stays Redis-driver-agnostic and reuses the\n * app's connection config). Blocking reads monopolise a connection, so each `subscribe` runs on a\n * short-lived `duplicate()` that is disconnected when the subscriber stops.\n */\nexport class RedisTokenStreamSink implements TokenStreamSink {\n  private readonly keyPrefix: string;\n  private readonly ttlSeconds: number;\n  private readonly blockMs: number;\n\n  constructor(\n    private readonly redis: Redis,\n    options: RedisTokenStreamSinkOptions = {},\n  ) {\n    this.keyPrefix = options.keyPrefix ?? 'agent:sink:';\n    this.ttlSeconds = options.ttlSeconds ?? 3600;\n    this.blockMs = options.blockMs ?? 5000;\n  }\n\n  private key(runId: string): string {\n    return `${this.keyPrefix}${runId}`;\n  }\n\n  open(runId: string): SinkWriter {\n    const key = this.key(runId);\n    return {\n      write: async (chunk: Uint8Array) => {\n        await this.redis.xadd(key, '*', CHUNK_FIELD, Buffer.from(chunk));\n      },\n      end: async () => {\n        await this.redis.xadd(key, '*', END_FIELD, '1');\n        await this.redis.expire(key, this.ttlSeconds);\n      },\n      fail: async (error: StreamError) => {\n        await this.redis.xadd(key, '*', FAIL_FIELD, JSON.stringify(error));\n        await this.redis.expire(key, this.ttlSeconds);\n      },\n    };\n  }\n\n  async *subscribe(runId: string): AsyncIterable<Uint8Array> {\n    const key = this.key(runId);\n    // Blocking XREAD holds the connection for the whole poll, so follow on a dedicated one.\n    const reader = this.redis.duplicate();\n    try {\n      let lastId = '0';\n      while (true) {\n        const response = await reader.xreadBuffer('BLOCK', this.blockMs, 'STREAMS', key, lastId);\n        for (const entry of readEntries(response)) {\n          lastId = entry.id;\n          if (entry.field === CHUNK_FIELD && entry.value !== undefined) {\n            yield new Uint8Array(entry.value);\n          } else if (entry.field === END_FIELD) {\n            return;\n          } else if (entry.field === FAIL_FIELD && entry.value !== undefined) {\n            throw new AgentStreamError(parseStreamError(entry.value.toString()));\n          }\n        }\n      }\n    } finally {\n      reader.disconnect();\n    }\n  }\n\n  async close(runId: string): Promise<void> {\n    await this.redis.del(this.key(runId));\n  }\n}\n\ninterface StreamEntry {\n  id: string;\n  field: string;\n  value: Buffer | undefined;\n}\n\n/**\n * Flatten ioredis's `XREAD` buffer response — `[[key, [[id, [field, value, …]], …]], …] | null` —\n * into the entries we care about. Validated defensively at runtime (it crosses the Redis boundary)\n * rather than trusting the driver's loose typing.\n */\nfunction readEntries(response: unknown): StreamEntry[] {\n  if (!Array.isArray(response)) {\n    return [];\n  }\n  const entries: StreamEntry[] = [];\n  for (const stream of response) {\n    if (!Array.isArray(stream) || !Array.isArray(stream[1])) {\n      continue;\n    }\n    for (const item of stream[1]) {\n      if (!Array.isArray(item) || item.length < 2) {\n        continue;\n      }\n      const [id, fields] = item;\n      if (!Buffer.isBuffer(id) || !Array.isArray(fields)) {\n        continue;\n      }\n      const field = Buffer.isBuffer(fields[0]) ? fields[0].toString() : undefined;\n      if (field === undefined) {\n        continue;\n      }\n      entries.push({\n        id: id.toString(),\n        field,\n        value: Buffer.isBuffer(fields[1]) ? fields[1] : undefined,\n      });\n    }\n  }\n  return entries;\n}\n\n/** Parse a `fail` sentinel's payload back into a {@link StreamError}, tolerating malformed JSON. */\nfunction parseStreamError(raw: string): StreamError {\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (\n      typeof parsed === 'object' &&\n      parsed !== null &&\n      'code' in parsed &&\n      'message' in parsed &&\n      typeof parsed.code === 'string' &&\n      typeof parsed.message === 'string'\n    ) {\n      return { code: parsed.code, message: parsed.message };\n    }\n  } catch {\n    // fall through to the generic terminal below\n  }\n  return { code: 'stream_failed', message: raw };\n}\n"],"mappings":"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","names":["AgentStreamError","CHUNK_FIELD","END_FIELD","FAIL_FIELD","RedisTokenStreamSink","keyPrefix","ttlSeconds","blockMs","redis","options","key","runId","open","write","chunk","xadd","Buffer","from","end","expire","fail","error","JSON","stringify","subscribe","reader","duplicate","lastId","response","xreadBuffer","entry","readEntries","id","field","value","undefined","Uint8Array","AgentStreamError","parseStreamError","toString","disconnect","close","del","Array","isArray","entries","stream","item","length","fields","isBuffer","push","raw","parsed","parse","code","message"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Governed, durable-backed AI agent for NestJS — @AiTool, discovery, /agent controllers",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -28,6 +28,16 @@
         "types": "./dist/durable/index.d.cts",
         "default": "./dist/durable/index.cjs"
       }
+    },
+    "./sink-redis": {
+      "import": {
+        "types": "./dist/sink-redis/index.d.ts",
+        "default": "./dist/sink-redis/index.js"
+      },
+      "require": {
+        "types": "./dist/sink-redis/index.d.cts",
+        "default": "./dist/sink-redis/index.cjs"
+      }
     }
   },
   "files": [
@@ -36,13 +46,14 @@
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
     "zod": "3.25.76",
-    "@dudousxd/nestjs-agent-core": "0.3.2"
+    "@dudousxd/nestjs-agent-core": "0.3.3"
   },
   "peerDependencies": {
-    "@nestjs/common": "^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^10.0.0 || ^11.0.0",
     "@dudousxd/nestjs-durable": ">=0.26.0",
     "@dudousxd/nestjs-durable-core": ">=0.45.0",
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "ioredis": "^5.0.0",
     "reflect-metadata": "^0.2.0"
   },
   "peerDependenciesMeta": {
@@ -51,6 +62,9 @@
     },
     "@dudousxd/nestjs-durable-core": {
       "optional": true
+    },
+    "ioredis": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -65,13 +79,14 @@
     "@nestjs/testing": "11.1.6",
     "@types/express": "5.0.0",
     "@types/supertest": "6.0.2",
+    "ioredis": "^5.4.1",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.1",
     "supertest": "7.0.0",
     "tsup": "8.3.5",
     "typescript": "5.9.3",
     "zod": "3.25.76",
-    "@dudousxd/nestjs-agent-testing": "0.3.2"
+    "@dudousxd/nestjs-agent-testing": "0.3.3"
   },
   "scripts": {
     "build": "tsup",