@qjp88995/agent-runtime-redis 0.0.0-stage → 0.2.0

package/src/coordination.ts

@@ -0,0 +1,459 @@
+import type { Redis } from 'ioredis';
+import { randomUUID } from 'node:crypto';
+
+import {
+  AWAIT_LEASE_TTL_MS,
+  consoleLogger,
+  LOCK_TTL_MS,
+  type Logger,
+  type LoggerFactory,
+  type SessionLock,
+  type SubagentAwaitLease,
+  type TaskLease,
+  type TaskSignals,
+  type TreeBudget,
+  type WakeChannel,
+} from '@qjp88995/agent-runtime';
+
+import { type RedisKeyOptions, type RedisKeys, redisKeys } from './keys.js';
+
+/**
+ * 会话锁、唤醒 / 空闲广播、子 Agent 等待租约、树级名额、任务监视租约与转后台广播的 Redis 实现。
+ * 搬自 agent-base `agent-core/loop/{session-lock,session-wake}.service.ts`、`session-idle.ts`、
+ * `agent-core/subagent/{subagent-await,tree-budget}.service.ts`，语义见 runtime 的 `ports/coordination`。
+ *
+ * 锁 / 租约 / 名额都直接用宿主给的共享连接（全是非阻塞的常规命令），只有唤醒频道与转后台广播
+ * 各要一条独立的订阅连接（进了 subscribe 模式的连接不能再发普通命令）。
+ */
+
+/** DEL 前比对 token，避免误删「TTL 过期后被别人重新抢到」的锁。 */
+const RELEASE_LUA =
+  "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end";
+/** PEXPIRE 前比对 token，只续自己的锁。 */
+const RENEW_LUA =
+  "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('pexpire', KEYS[1], ARGV[2]) else return 0 end";
+
+export interface RedisSessionLockOptions extends RedisKeyOptions {
+  /** 缺省 `LOCK_TTL_MS`（60s）。 */
+  ttlMs?: number;
+}
+
+/** SET NX PX 抢，Lua 比对 token 再 DEL / PEXPIRE。会话锁与任务租约共用，只是键空间不同。 */
+class RedisTokenLock {
+  constructor(
+    private readonly redis: Redis,
+    private readonly keyOf: (id: string) => string,
+    private readonly ttlMs: number
+  ) {}
+
+  async acquire(id: string): Promise<string | null> {
+    const token = randomUUID();
+    const res = await this.redis.set(
+      this.keyOf(id),
+      token,
+      'PX',
+      this.ttlMs,
+      'NX'
+    );
+    return res === 'OK' ? token : null;
+  }
+
+  async renew(id: string, token: string): Promise<boolean> {
+    const res = await this.redis.eval(
+      RENEW_LUA,
+      1,
+      this.keyOf(id),
+      token,
+      String(this.ttlMs)
+    );
+    return res === 1;
+  }
+
+  async release(id: string, token: string): Promise<void> {
+    await this.redis.eval(RELEASE_LUA, 1, this.keyOf(id), token);
+  }
+
+  async isHeld(id: string): Promise<boolean> {
+    return (await this.redis.exists(this.keyOf(id))) === 1;
+  }
+}
+
+/** 会话锁。TTL 兜底持有者崩溃。 */
+export class RedisSessionLock implements SessionLock {
+  private readonly lock: RedisTokenLock;
+
+  constructor(redis: Redis, options: RedisSessionLockOptions = {}) {
+    this.lock = new RedisTokenLock(
+      redis,
+      redisKeys(options).lock,
+      options.ttlMs ?? LOCK_TTL_MS
+    );
+  }
+
+  acquire(sessionId: string): Promise<string | null> {
+    return this.lock.acquire(sessionId);
+  }
+
+  renew(sessionId: string, token: string): Promise<boolean> {
+    return this.lock.renew(sessionId, token);
+  }
+
+  release(sessionId: string, token: string): Promise<void> {
+    return this.lock.release(sessionId, token);
+  }
+
+  isHeld(sessionId: string): Promise<boolean> {
+    return this.lock.isHeld(sessionId);
+  }
+}
+
+export interface RedisTaskLeaseOptions extends RedisKeyOptions {
+  /** 缺省 `LOCK_TTL_MS`（60s）。监视器每段等待（runtime 缺省 20s）之后续一次。 */
+  ttlMs?: number;
+}
+
+/** 任务监视租约：与会话锁同一套写法，键 `agent-task:lease:<taskId>`。 */
+export class RedisTaskLease implements TaskLease {
+  private readonly lock: RedisTokenLock;
+
+  constructor(redis: Redis, options: RedisTaskLeaseOptions = {}) {
+    this.lock = new RedisTokenLock(
+      redis,
+      redisKeys(options).taskLease,
+      options.ttlMs ?? LOCK_TTL_MS
+    );
+  }
+
+  acquire(taskId: string): Promise<string | null> {
+    return this.lock.acquire(taskId);
+  }
+
+  renew(taskId: string, token: string): Promise<boolean> {
+    return this.lock.renew(taskId, token);
+  }
+
+  release(taskId: string, token: string): Promise<void> {
+    return this.lock.release(taskId, token);
+  }
+}
+
+export interface RedisWakeChannelOptions extends RedisKeyOptions {
+  /**
+   * 订阅用的连接。缺省 `redis.duplicate()`，由本对象负责关闭；宿主自己给的不关。
+   */
+  subscriber?: Redis;
+  logger?: LoggerFactory;
+}
+
+type Handler = (sessionId: string) => void;
+
+/**
+ * 唤醒 / 空闲广播走 Redis pub/sub（at-most-once，订阅前发的收不到——与端口约定一致）。
+ *
+ * 用 `RedisWakeChannel.create()` 构造：它等 SUBSCRIBE 应答回来才返回，之后 `onWake` / `onIdle`
+ * 只是登记本地处理函数，同步生效。否则「刚订阅就有人 wake」会落在 SUBSCRIBE 应答之前、静默丢失。
+ * 断线重连后 ioredis 会自动重新订阅（`autoResubscribe` 缺省开）；断线期间的广播照样丢，
+ * 这由 sweeper 的启动补唤醒与消费方自己的兜底扫描覆盖。
+ *
+ * 一个处理函数抛错只记日志，不影响别的处理函数，也不冒进 ioredis 的事件循环。
+ */
+export class RedisWakeChannel implements WakeChannel {
+  private readonly wakeHandlers = new Set<Handler>();
+  private readonly idleHandlers = new Set<Handler>();
+  private disposed = false;
+
+  private constructor(
+    private readonly redis: Redis,
+    private readonly sub: Redis,
+    private readonly ownsSub: boolean,
+    private readonly keys: RedisKeys,
+    private readonly logger: Logger
+  ) {}
+
+  static async create(
+    redis: Redis,
+    options: RedisWakeChannelOptions = {}
+  ): Promise<RedisWakeChannel> {
+    const sub = options.subscriber ?? redis.duplicate();
+    const channel = new RedisWakeChannel(
+      redis,
+      sub,
+      !options.subscriber,
+      redisKeys(options),
+      (options.logger ?? consoleLogger)('RedisWakeChannel')
+    );
+    sub.on('message', (ch: string, message: string) =>
+      channel.dispatch(ch, message)
+    );
+    await sub.subscribe(channel.keys.wakeChannel, channel.keys.idleChannel);
+    return channel;
+  }
+
+  private dispatch(ch: string, message: string): void {
+    if (ch === this.keys.wakeChannel) {
+      this.fanOut(this.wakeHandlers, message, 'wake');
+    } else if (ch === this.keys.idleChannel) {
+      let sessionId: unknown;
+      try {
+        sessionId = (JSON.parse(message) as { sessionId?: unknown }).sessionId;
+      } catch {
+        sessionId = undefined;
+      }
+      if (typeof sessionId !== 'string') {
+        this.logger.warn(`dropping malformed idle message: ${message}`);
+        return;
+      }
+      this.fanOut(this.idleHandlers, sessionId, 'idle');
+    }
+  }
+
+  private fanOut(handlers: Set<Handler>, sessionId: string, kind: string) {
+    for (const handler of [...handlers]) {
+      try {
+        handler(sessionId);
+      } catch (err) {
+        this.logger.error(
+          `${kind} handler failed for ${sessionId}: ${String(err)}`,
+          err instanceof Error ? err.stack : undefined
+        );
+      }
+    }
+  }
+
+  async wake(sessionId: string): Promise<void> {
+    await this.redis.publish(this.keys.wakeChannel, sessionId);
+  }
+
+  onWake(handler: Handler): () => void {
+    this.wakeHandlers.add(handler);
+    return () => this.wakeHandlers.delete(handler);
+  }
+
+  async idle(sessionId: string): Promise<void> {
+    await this.redis.publish(
+      this.keys.idleChannel,
+      JSON.stringify({ sessionId })
+    );
+  }
+
+  onIdle(handler: Handler): () => void {
+    this.idleHandlers.add(handler);
+    return () => this.idleHandlers.delete(handler);
+  }
+
+  /** 摘掉所有处理函数；订阅连接是本对象建的就关掉。 */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.wakeHandlers.clear();
+    this.idleHandlers.clear();
+    if (this.ownsSub) {
+      await this.sub.quit().catch(() => undefined);
+    } else {
+      await this.sub
+        .unsubscribe(this.keys.wakeChannel, this.keys.idleChannel)
+        .catch(() => undefined);
+    }
+  }
+}
+
+export interface RedisTaskSignalsOptions extends RedisKeyOptions {
+  /** 订阅用的连接。缺省 `redis.duplicate()`，由本对象负责关闭；宿主自己给的不关。 */
+  subscriber?: Redis;
+  logger?: LoggerFactory;
+}
+
+/**
+ * 「任务转后台」广播走 Redis pub/sub，载荷就是任务 id。与 `RedisWakeChannel` 同样用
+ * `create()` 等 SUBSCRIBE 应答回来才返回。广播丢了不要紧：前台等待方每段等待之后都回看任务行
+ * 的 `background`，信号只是让它不必等满这一段。
+ */
+export class RedisTaskSignals implements TaskSignals {
+  private readonly handlers = new Set<Handler>();
+  private disposed = false;
+
+  private constructor(
+    private readonly redis: Redis,
+    private readonly sub: Redis,
+    private readonly ownsSub: boolean,
+    private readonly channel: string,
+    private readonly logger: Logger
+  ) {}
+
+  static async create(
+    redis: Redis,
+    options: RedisTaskSignalsOptions = {}
+  ): Promise<RedisTaskSignals> {
+    const sub = options.subscriber ?? redis.duplicate();
+    const signals = new RedisTaskSignals(
+      redis,
+      sub,
+      !options.subscriber,
+      redisKeys(options).taskBackgroundChannel,
+      (options.logger ?? consoleLogger)('RedisTaskSignals')
+    );
+    sub.on('message', (ch: string, taskId: string) => {
+      if (ch === signals.channel) signals.dispatch(taskId);
+    });
+    await sub.subscribe(signals.channel);
+    return signals;
+  }
+
+  private dispatch(taskId: string): void {
+    for (const handler of [...this.handlers]) {
+      try {
+        handler(taskId);
+      } catch (err) {
+        this.logger.error(
+          `background handler failed for ${taskId}: ${String(err)}`,
+          err instanceof Error ? err.stack : undefined
+        );
+      }
+    }
+  }
+
+  async background(taskId: string): Promise<void> {
+    await this.redis.publish(this.channel, taskId);
+  }
+
+  onBackground(handler: Handler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  /** 摘掉处理函数；订阅连接是本对象建的就关掉，否则只退订本频道。 */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.handlers.clear();
+    if (this.ownsSub) await this.sub.quit().catch(() => undefined);
+    else await this.sub.unsubscribe(this.channel).catch(() => undefined);
+  }
+}
+
+export interface RedisSubagentAwaitLeaseOptions extends RedisKeyOptions {
+  /** 缺省 `AWAIT_LEASE_TTL_MS`（60s）。 */
+  ttlMs?: number;
+  logger?: LoggerFactory;
+}
+
+/**
+ * 等待租约：一个带 TTL 的键。`claim` 是一条原子 DEL，父与 finalizer 抢同一条，恰有一方胜出。
+ * Redis 出错时按端口约定一律退化成异步（见各方法）。
+ */
+export class RedisSubagentAwaitLease implements SubagentAwaitLease {
+  private readonly keys: RedisKeys;
+  private readonly ttlMs: number;
+  private readonly logger: Logger;
+
+  constructor(
+    private readonly redis: Redis,
+    options: RedisSubagentAwaitLeaseOptions = {}
+  ) {
+    this.keys = redisKeys(options);
+    this.ttlMs = options.ttlMs ?? AWAIT_LEASE_TTL_MS;
+    this.logger = (options.logger ?? consoleLogger)('RedisSubagentAwaitLease');
+  }
+
+  /** 失败返回 false：没有租约就没有互斥，调用方退回异步模式。 */
+  async begin(childSessionId: string): Promise<boolean> {
+    try {
+      await this.redis.set(
+        this.keys.awaited(childSessionId),
+        '1',
+        'PX',
+        this.ttlMs
+      );
+      return true;
+    } catch (err) {
+      this.logger.warn(
+        `await lease begin(${childSessionId}) failed, falling back to async: ${String(err)}`
+      );
+      return false;
+    }
+  }
+
+  /** 只续已存在的租约（PEXPIRE 对不存在的键是 no-op）。失败不抛。 */
+  async renew(childSessionId: string): Promise<void> {
+    try {
+      await this.redis.pexpire(this.keys.awaited(childSessionId), this.ttlMs);
+    } catch {
+      // 续租失败不打断等待：最坏是租约过期、finalizer 改走回投，父随后超时降级。
+    }
+  }
+
+  /** 拿不准当作没人等：猜「有人等」会让该回投的产出被跳过，那是静默丢失。 */
+  async isAwaited(childSessionId: string): Promise<boolean> {
+    try {
+      return (await this.redis.exists(this.keys.awaited(childSessionId))) === 1;
+    } catch (err) {
+      this.logger.warn(
+        `await lease isAwaited(${childSessionId}) failed, assuming none: ${String(err)}`
+      );
+      return false;
+    }
+  }
+
+  /** 拿不准时父得 true（放弃等待）、finalizer 得 false（照常回投），合起来就是退化成异步。 */
+  async claim(
+    childSessionId: string,
+    by: 'parent' | 'finalizer'
+  ): Promise<boolean> {
+    try {
+      return (await this.redis.del(this.keys.awaited(childSessionId))) === 1;
+    } catch (err) {
+      this.logger.warn(
+        `await lease claim(${childSessionId}, ${by}) failed: ${String(err)}`
+      );
+      return by === 'parent';
+    }
+  }
+}
+
+/** 只有当前值 < 上限才 INCR（并刷新 TTL），否则不动。 */
+const INCR_IF_UNDER_LUA =
+  "local v=tonumber(redis.call('get',KEYS[1]) or '0') if v<tonumber(ARGV[1]) then redis.call('incr',KEYS[1]) redis.call('expire',KEYS[1],ARGV[2]) return 1 else return 0 end";
+/** DECR 后 ≤ 0 就 DEL，不留负值。 */
+const DECR_LUA =
+  "local v=redis.call('decr',KEYS[1]) if v<=0 then redis.call('del',KEYS[1]) end return v";
+
+export interface RedisTreeBudgetOptions extends RedisKeyOptions {
+  /** 计数键的 TTL，兜底「整棵树都没了、计数还留着」。缺省 1 天。 */
+  ttlSeconds?: number;
+}
+
+/** 树级名额：Lua 里做「读比较写」，并发 `tryIncr` 不超发。 */
+export class RedisTreeBudget implements TreeBudget {
+  private readonly keys: RedisKeys;
+  private readonly ttlSeconds: number;
+
+  constructor(
+    private readonly redis: Redis,
+    options: RedisTreeBudgetOptions = {}
+  ) {
+    this.keys = redisKeys(options);
+    this.ttlSeconds = options.ttlSeconds ?? 86_400;
+  }
+
+  async tryIncr(rootSessionId: string, limit: number): Promise<boolean> {
+    const res = await this.redis.eval(
+      INCR_IF_UNDER_LUA,
+      1,
+      this.keys.liveSubs(rootSessionId),
+      String(limit),
+      String(this.ttlSeconds)
+    );
+    return res === 1;
+  }
+
+  async decr(rootSessionId: string): Promise<void> {
+    await this.redis.eval(DECR_LUA, 1, this.keys.liveSubs(rootSessionId));
+  }
+
+  /** 与进程内实现一致：n ≤ 0 直接删键。 */
+  async set(rootSessionId: string, n: number): Promise<void> {
+    const key = this.keys.liveSubs(rootSessionId);
+    if (n <= 0) await this.redis.del(key);
+    else await this.redis.set(key, String(n), 'EX', this.ttlSeconds);
+  }
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * `@qjp88995/agent-runtime` 的 Redis 适配：多实例部署时替换进程内的总线与协调件。
+ *
+ * 换的是七个端口——`StreamBus`、`SessionLock`、`WakeChannel`、`SubagentAwaitLease`、`TreeBudget`、
+ * `TaskLease`、`TaskSignals`。
+ * 存储类端口（跑次、消息、会话、问题、厂商文件、任务表）不在这里：它们归宿主的数据库。
+ */
+import type { Redis } from 'ioredis';
+
+import type { LoggerFactory } from '@qjp88995/agent-runtime';
+
+import {
+  RedisSessionLock,
+  RedisSubagentAwaitLease,
+  RedisTaskLease,
+  RedisTaskSignals,
+  RedisTreeBudget,
+  RedisWakeChannel,
+} from './coordination.js';
+import type { RedisKeyOptions } from './keys.js';
+import { RedisStreamBus, type RedisStreamBusOptions } from './stream-bus.js';
+
+export {
+  RedisSessionLock,
+  type RedisSessionLockOptions,
+  RedisSubagentAwaitLease,
+  type RedisSubagentAwaitLeaseOptions,
+  RedisTaskLease,
+  type RedisTaskLeaseOptions,
+  RedisTaskSignals,
+  type RedisTaskSignalsOptions,
+  RedisTreeBudget,
+  type RedisTreeBudgetOptions,
+  RedisWakeChannel,
+  type RedisWakeChannelOptions,
+} from './coordination.js';
+export { type RedisKeyOptions, type RedisKeys, redisKeys } from './keys.js';
+export { RedisStreamBus, type RedisStreamBusOptions } from './stream-bus.js';
+
+export interface RedisPortsOptions extends RedisKeyOptions {
+  logger?: LoggerFactory;
+  /** 透传给 `RedisStreamBus`（`keyPrefix` 以外层的为准）。 */
+  bus?: Omit<RedisStreamBusOptions, 'keyPrefix'>;
+}
+
+export interface RedisPorts {
+  bus: RedisStreamBus;
+  lock: RedisSessionLock;
+  wake: RedisWakeChannel;
+  awaitLease: RedisSubagentAwaitLease;
+  treeBudget: RedisTreeBudget;
+  taskLease: RedisTaskLease;
+  taskSignals: RedisTaskSignals;
+  /** 停总线定时器、关唤醒频道与转后台广播的订阅连接。不关 `redis` 本身（它是宿主的）。 */
+  dispose(): Promise<void>;
+}
+
+/**
+ * 一组 Redis 实现，键名与 `createInProcessPorts()` 的对应项相同，宿主可以直接覆盖：
+ *
+ * ```ts
+ * const ports = { ...createInProcessPorts(), ...(await createRedisPorts(redis)) };
+ * ```
+ *
+ * `redis` 是宿主的共享连接（锁、租约、名额、写会话流都用它）；唤醒频道、转后台广播与每个会话订阅
+ * 各自 `duplicate()` 一条。等两个频道的订阅都就绪才返回。
+ */
+export async function createRedisPorts(
+  redis: Redis,
+  options: RedisPortsOptions = {}
+): Promise<RedisPorts> {
+  const { keyPrefix, logger } = options;
+  const [wake, taskSignals] = await Promise.all([
+    RedisWakeChannel.create(redis, { keyPrefix, logger }),
+    RedisTaskSignals.create(redis, { keyPrefix, logger }),
+  ]);
+  const bus = new RedisStreamBus(redis, { ...options.bus, keyPrefix });
+  return {
+    bus,
+    lock: new RedisSessionLock(redis, { keyPrefix }),
+    wake,
+    awaitLease: new RedisSubagentAwaitLease(redis, { keyPrefix, logger }),
+    treeBudget: new RedisTreeBudget(redis, { keyPrefix }),
+    taskLease: new RedisTaskLease(redis, { keyPrefix }),
+    taskSignals,
+    async dispose() {
+      bus.dispose();
+      await Promise.all([wake.dispose(), taskSignals.dispose()]);
+    },
+  };
+}

package/src/keys.ts

@@ -0,0 +1,36 @@
+/**
+ * 键与频道名。缺省与 agent-base 线上用的一字不差（`agent-task:*` 是 0.2.0 新加的，没有旧格式要兼容）——agent-base 换上本包时可以滚动发布
+ * （新旧实例共用一个 Redis 期间锁、唤醒、租约、会话流都互通），空闲广播的载荷也照旧是
+ * JSON `{ sessionId }`，它现有的订阅方不用改。
+ *
+ * 多个 APP 共用一个 Redis 时给 `keyPrefix`（例如 `'novel:'`），键和 pub/sub 频道都加前缀。
+ * 不用 ioredis 自带的 `keyPrefix`：它只管键、不管频道，而且是整条连接的设置，宿主的其它用途会被连带。
+ */
+export interface RedisKeyOptions {
+  keyPrefix?: string;
+}
+
+export interface RedisKeys {
+  lock(sessionId: string): string;
+  wakeChannel: string;
+  idleChannel: string;
+  awaited(childSessionId: string): string;
+  liveSubs(rootSessionId: string): string;
+  sessionStream(rootSessionId: string): string;
+  taskLease(taskId: string): string;
+  taskBackgroundChannel: string;
+}
+
+export function redisKeys(options: RedisKeyOptions = {}): RedisKeys {
+  const p = options.keyPrefix ?? '';
+  return {
+    lock: s => `${p}agent-loop:lock:${s}`,
+    wakeChannel: `${p}agent-loop:wake`,
+    idleChannel: `${p}agent-session:idle`,
+    awaited: c => `${p}agent-subagent:awaited:${c}`,
+    liveSubs: r => `${p}agent-tree:live-subs:${r}`,
+    sessionStream: r => `${p}agent-session:${r}`,
+    taskLease: t => `${p}agent-task:lease:${t}`,
+    taskBackgroundChannel: `${p}agent-task:background`,
+  };
+}