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

package/dist/stream-bus.js

@@ -0,0 +1,285 @@
+import { InProcessStreamBus, } from '@qjp88995/agent-runtime';
+import { redisKeys } from './keys.js';
+/**
+ * 兜底上限，不是常态：落库的段落会从流里退役（`retireUpTo`），流里常态只剩尚未落库的那一段。
+ * 它只挡进程崩溃留下的孤儿轮次、以及一段长到落库之前就写出上万条的极端情况。
+ */
+const MAXLEN = 10_000;
+const STREAM_TTL_SECONDS = 3600;
+const XREAD_BLOCK_MS = 5_000;
+/**
+ * 一次 XREAD 最多取多少条。首连的重放段吃这个数（游标缺省 `'0'`，100 一批就是上百次往返）；
+ * 活跃期一批本来也就一两条，调大不影响。
+ */
+const XREAD_COUNT = 500;
+/**
+ * 非 abort 的 XREAD 失败后的退避。畸形游标会让 XREAD **立即**拒绝，没有退避就是 CPU 热循环兼
+ * 疯狂重连 Redis。
+ */
+const XREAD_RETRY_DELAY_MS = 250;
+/**
+ * 写侧合并窗口：同一段里连续的 `text-delta` / `reasoning-delta` 攒这么久再 XADD 成一条。流条目
+ * 不可变，合并只能在写入前做；前端本来就按渲染帧合帧，多攒两帧看不出来，条目数少一个数量级。
+ */
+const XADD_BATCH_MS = 50;
+/**
+ * 落库后条目在流里的宽限期。前端打开会话是「先拉历史、后订阅」两步，一段恰好在两步之间落库时，
+ * 它在库快照里没有、流里又删了——留一段让重放还能送到（前端按 `flushedSeq` 去重）。
+ */
+const RETIRE_GRACE_MS = 30_000;
+const XDEL_CHUNK = 500;
+const SWEEP_INTERVAL_MS = 60_000;
+function parseEntry(fields) {
+    const i = fields.indexOf('data');
+    if (i < 0 || i + 1 >= fields.length)
+        return null;
+    try {
+        return JSON.parse(fields[i + 1]);
+    }
+    catch {
+        return null;
+    }
+}
+function isMergeableDelta(e) {
+    return e.type === 'text-delta' || e.type === 'reasoning-delta';
+}
+function textOf(e) {
+    const p = e.payload;
+    return typeof p?.text === 'string' ? p.text : '';
+}
+/**
+ * 「紧邻的同一段」：同 root、同 run、同 messageId、同 type、同深度。退役边界永远落在类型切换处，
+ * 所以一条合并条目不会横跨边界，`seq ≤ 边界` 对合并条目（seq 取最后一条）仍然精确。
+ */
+function sameSegment(a, b) {
+    return (a.rootSessionId === b.rootSessionId &&
+        a.runId === b.runId &&
+        a.messageId === b.messageId &&
+        a.type === b.type &&
+        a.depth === b.depth);
+}
+/**
+ * 多实例事件总线：**per-stream 面留在进程内**（继承 `InProcessStreamBus`：seq、buffer、取消信号——
+ * 消费它们的 pump 与 `streamText` 都在跑这一轮的那个进程里），**会话面换成 Redis Streams**
+ * （键 `agent-session:<root>`），跨实例、断线可按游标续订。搬自 agent-base `RedisStreamBus`。
+ *
+ * ## 会话面只保留尚未落库的尾巴
+ *
+ * - **落库即退役**：宿主落库成功后调 `retireUpTo(runId, seq)`，宽限期后 XDEL 这一轮 seq ≤ 边界的条目；
+ *   `run-finish` / `error` 宽限期后整轮清掉。条目 id 从 XADD 回值登记在进程内存里（写这轮事件的
+ *   就是跑这轮的进程）；别的实例补发的 `run-finish` 在本进程查不到表，删除是 no-op，孤儿条目由
+ *   TTL / MAXLEN 兜底。
+ * - **写侧合并**：连续的同段 delta 攒一个窗口再写；任何不可合并的事件先把攒着的吐掉，顺序不变。
+ *
+ * 会话面的写是 fire-and-forget：观测不承重，序列化失败或 Redis 出错只丢这一条，绝不让一轮对话失败。
+ *
+ * ## 与 agent-base 的差别
+ *
+ * - `publish` 只在流活着时写会话面（agent-base 不看流状态；这里与进程内实现、端口约定对齐：
+ *   「流未 open / 已 close 时丢弃」）。
+ * - 测试用的 `configureForTest` 改成构造参数 `batchMs` / `retireGraceMs`；加 `dispose()`。
+ * - 键可加前缀（`keyPrefix`）。
+ *
+ * **停止按钮仍是进程内的**：`abort(streamId)` 只对本进程跑着的流生效，与 agent-base 一样——
+ * 停止请求落到别的实例上时，宿主要自己把它路由到跑这轮的实例（或者走会话锁所在实例）。
+ */
+export class RedisStreamBus extends InProcessStreamBus {
+    redis;
+    keys;
+    batchMs;
+    graceMs;
+    maxLen;
+    streamTtlSeconds;
+    xreadBlockMs;
+    pendingByRoot = new Map();
+    entriesByRun = new Map();
+    timers = new Set();
+    runTableTimer;
+    constructor(redis, options = {}) {
+        super(options);
+        this.redis = redis;
+        this.keys = redisKeys(options);
+        this.batchMs =
+            options.batchMs === undefined ? XADD_BATCH_MS : options.batchMs;
+        this.graceMs = options.retireGraceMs ?? RETIRE_GRACE_MS;
+        this.maxLen = options.maxLen ?? MAXLEN;
+        this.streamTtlSeconds = options.streamTtlSeconds ?? STREAM_TTL_SECONDS;
+        this.xreadBlockMs = options.xreadBlockMs ?? XREAD_BLOCK_MS;
+        this.runTableTimer = setInterval(() => this.sweepRunTables(), SWEEP_INTERVAL_MS);
+        this.runTableTimer.unref();
+    }
+    publish(event) {
+        // 只喂进程内的 per-stream 面，绝不走基类的进程内会话面（那块在这里永远是空的）。
+        if (this.publishToStream(event))
+            this.enqueueSession(event);
+    }
+    publishSessionEvent(event) {
+        this.enqueueSession(event);
+    }
+    retireUpTo(runId, uptoSeq) {
+        this.later(() => this.deleteEntries(runId, e => e.seq <= uptoSeq));
+    }
+    /** 宽限期后执行；`dispose()` 会清掉还没到点的。 */
+    later(fn) {
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            fn();
+        }, this.graceMs);
+        timer.unref();
+        this.timers.add(timer);
+    }
+    /**
+     * 会话面入口。序列化在进入 fire-and-forget 链之前同步做完（见 `xaddSession`），非 JSON-safe
+     * 载荷不会经 `publish` 冒进 `runTurn`。
+     */
+    enqueueSession(event) {
+        const root = event.rootSessionId;
+        const pending = this.pendingByRoot.get(root);
+        if (this.batchMs !== null && isMergeableDelta(event)) {
+            if (pending && sameSegment(pending.event, event)) {
+                pending.event = {
+                    ...pending.event,
+                    seq: event.seq,
+                    ts: event.ts,
+                    payload: { text: textOf(pending.event) + textOf(event) },
+                };
+                return;
+            }
+            if (pending)
+                this.flushPending(root);
+            const timer = setTimeout(() => this.flushPending(root), this.batchMs);
+            timer.unref();
+            this.pendingByRoot.set(root, { event, timer });
+            return;
+        }
+        if (pending)
+            this.flushPending(root);
+        const written = this.xaddSession(event);
+        // 宽限期从这条自己登记完才开始算：XADD 回包后才把 id 记进登记表，同步起表的话回包慢过
+        // 宽限期时删除先跑——边界事件本身漏删，回包再登记出一张没人清的表。
+        if (event.type === 'run-finish' || event.type === 'error') {
+            void written.then(() => this.later(() => {
+                this.deleteEntries(event.runId, () => true);
+                this.entriesByRun.delete(event.runId);
+            }));
+        }
+    }
+    flushPending(root) {
+        const pending = this.pendingByRoot.get(root);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pendingByRoot.delete(root);
+        void this.xaddSession(pending.event);
+    }
+    /** 写一条并登记；返回的 promise 在登记完（或失败被吞）后落定，从不 reject。 */
+    xaddSession(event) {
+        let data;
+        try {
+            data = JSON.stringify(event);
+        }
+        catch {
+            return Promise.resolve();
+        }
+        const key = this.keys.sessionStream(event.rootSessionId);
+        // XADD + 刷新 TTL 一次往返。会话级事件（seq 0）不登记——它们不属于任何会落库的段落。
+        return this.redis
+            .multi()
+            .xadd(key, 'MAXLEN', '~', String(this.maxLen), '*', 'data', data)
+            .expire(key, this.streamTtlSeconds)
+            .exec()
+            .then(res => {
+            const id = res?.[0]?.[1];
+            if (typeof id !== 'string' || event.seq <= 0)
+                return;
+            let run = this.entriesByRun.get(event.runId);
+            if (!run) {
+                run = { key, ids: [], lastActivity: Date.now() };
+                this.entriesByRun.set(event.runId, run);
+            }
+            run.ids.push({ seq: event.seq, id });
+            run.lastActivity = Date.now();
+        })
+            .catch(() => undefined);
+    }
+    deleteEntries(runId, pick) {
+        const run = this.entriesByRun.get(runId);
+        if (!run)
+            return;
+        const doomed = run.ids.filter(pick).map(e => e.id);
+        if (doomed.length === 0)
+            return;
+        run.ids = run.ids.filter(e => !pick(e));
+        run.lastActivity = Date.now();
+        for (let i = 0; i < doomed.length; i += XDEL_CHUNK) {
+            void this.redis
+                .xdel(run.key, ...doomed.slice(i, i + XDEL_CHUNK))
+                .catch(() => undefined);
+        }
+    }
+    /** 轮次登记表兜底清理：正常路径由 run-finish / error 清；崩溃或别的实例收尾的轮次靠这里。 */
+    sweepRunTables() {
+        const now = Date.now();
+        const ttlMs = this.streamTtlSeconds * 1000;
+        for (const [runId, run] of this.entriesByRun) {
+            if (now - run.lastActivity > ttlMs)
+                this.entriesByRun.delete(runId);
+        }
+    }
+    /**
+     * 每个订阅一条独立连接（XREAD BLOCK 会占住连接）；`signal` abort 时断开它，在途的 XREAD 随之结束。
+     */
+    async *subscribeSession(rootSessionId, fromId, signal) {
+        if (signal.aborted)
+            return;
+        const sub = this.redis.duplicate();
+        const onAbort = () => void sub.disconnect();
+        signal.addEventListener('abort', onAbort);
+        const key = this.keys.sessionStream(rootSessionId);
+        let cursor = fromId && fromId.length > 0 ? fromId : '0';
+        try {
+            for (;;) {
+                if (signal.aborted)
+                    return;
+                let res;
+                try {
+                    res = (await sub.xread('COUNT', XREAD_COUNT, 'BLOCK', this.xreadBlockMs, 'STREAMS', key, cursor));
+                }
+                catch {
+                    if (signal.aborted)
+                        return;
+                    await new Promise(resolve => setTimeout(resolve, XREAD_RETRY_DELAY_MS));
+                    continue;
+                }
+                if (!res)
+                    continue;
+                for (const [, entries] of res) {
+                    for (const [id, fields] of entries) {
+                        cursor = id;
+                        const event = parseEntry(fields);
+                        if (event)
+                            yield { id, event };
+                    }
+                }
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+            await sub.quit().catch(() => undefined);
+        }
+    }
+    /**
+     * 停掉定时器：攒着的 delta 立刻写出去（不丢），还没到点的退役放弃（条目由 TTL / MAXLEN 兜底）。
+     * 不关宿主给的连接。
+     */
+    dispose() {
+        super.dispose();
+        clearInterval(this.runTableTimer);
+        for (const root of [...this.pendingByRoot.keys()])
+            this.flushPending(root);
+        for (const timer of this.timers)
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+}
+//# sourceMappingURL=stream-bus.js.map

package/dist/stream-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-bus.js","sourceRoot":"","sources":["../src/stream-bus.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@qjp88995/agent-runtime-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Redis adapters for @qjp88995/agent-runtime: event bus, session lock, wake/idle channel, subagent await lease and tree budget, for running on more than one instance.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/test-redis.ts"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qjp88995/agent-kit.git",
+    "directory": "packages/runtime-redis"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "ioredis": "^5.4.0",
+    "@qjp88995/agent-runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "ioredis": "^5.11.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@qjp88995/agent-runtime": "0.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist *.tsbuildinfo && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && vitest run",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
 }

package/src/coordination.ts

@@ -0,0 +1,329 @@
+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 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。TTL 兜底持有者崩溃。 */
+export class RedisSessionLock implements SessionLock {
+  private readonly keys: RedisKeys;
+  private readonly ttlMs: number;
+
+  constructor(
+    private readonly redis: Redis,
+    options: RedisSessionLockOptions = {}
+  ) {
+    this.keys = redisKeys(options);
+    this.ttlMs = options.ttlMs ?? LOCK_TTL_MS;
+  }
+
+  async acquire(sessionId: string): Promise<string | null> {
+    const token = randomUUID();
+    const res = await this.redis.set(
+      this.keys.lock(sessionId),
+      token,
+      'PX',
+      this.ttlMs,
+      'NX'
+    );
+    return res === 'OK' ? token : null;
+  }
+
+  async renew(sessionId: string, token: string): Promise<boolean> {
+    const res = await this.redis.eval(
+      RENEW_LUA,
+      1,
+      this.keys.lock(sessionId),
+      token,
+      String(this.ttlMs)
+    );
+    return res === 1;
+  }
+
+  async release(sessionId: string, token: string): Promise<void> {
+    await this.redis.eval(RELEASE_LUA, 1, this.keys.lock(sessionId), token);
+  }
+
+  async isHeld(sessionId: string): Promise<boolean> {
+    return (await this.redis.exists(this.keys.lock(sessionId))) === 1;
+  }
+}
+
+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 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);
+  }
+}