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

package/dist/coordination.d.ts

@@ -0,0 +1,97 @@
+import type { Redis } from 'ioredis';
+import { type LoggerFactory, type SessionLock, type SubagentAwaitLease, type TreeBudget, type WakeChannel } from '@qjp88995/agent-runtime';
+import { type RedisKeyOptions } from './keys.js';
+export interface RedisSessionLockOptions extends RedisKeyOptions {
+    /** 缺省 `LOCK_TTL_MS`（60s）。 */
+    ttlMs?: number;
+}
+/** SET NX PX 抢锁，Lua 比对 token 再 DEL / PEXPIRE。TTL 兜底持有者崩溃。 */
+export declare class RedisSessionLock implements SessionLock {
+    private readonly redis;
+    private readonly keys;
+    private readonly ttlMs;
+    constructor(redis: Redis, options?: RedisSessionLockOptions);
+    acquire(sessionId: string): Promise<string | null>;
+    renew(sessionId: string, token: string): Promise<boolean>;
+    release(sessionId: string, token: string): Promise<void>;
+    isHeld(sessionId: string): Promise<boolean>;
+}
+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 declare class RedisWakeChannel implements WakeChannel {
+    private readonly redis;
+    private readonly sub;
+    private readonly ownsSub;
+    private readonly keys;
+    private readonly logger;
+    private readonly wakeHandlers;
+    private readonly idleHandlers;
+    private disposed;
+    private constructor();
+    static create(redis: Redis, options?: RedisWakeChannelOptions): Promise<RedisWakeChannel>;
+    private dispatch;
+    private fanOut;
+    wake(sessionId: string): Promise<void>;
+    onWake(handler: Handler): () => void;
+    idle(sessionId: string): Promise<void>;
+    onIdle(handler: Handler): () => void;
+    /** 摘掉所有处理函数；订阅连接是本对象建的就关掉。 */
+    dispose(): Promise<void>;
+}
+export interface RedisSubagentAwaitLeaseOptions extends RedisKeyOptions {
+    /** 缺省 `AWAIT_LEASE_TTL_MS`（60s）。 */
+    ttlMs?: number;
+    logger?: LoggerFactory;
+}
+/**
+ * 等待租约：一个带 TTL 的键。`claim` 是一条原子 DEL，父与 finalizer 抢同一条，恰有一方胜出。
+ * Redis 出错时按端口约定一律退化成异步（见各方法）。
+ */
+export declare class RedisSubagentAwaitLease implements SubagentAwaitLease {
+    private readonly redis;
+    private readonly keys;
+    private readonly ttlMs;
+    private readonly logger;
+    constructor(redis: Redis, options?: RedisSubagentAwaitLeaseOptions);
+    /** 失败返回 false：没有租约就没有互斥，调用方退回异步模式。 */
+    begin(childSessionId: string): Promise<boolean>;
+    /** 只续已存在的租约（PEXPIRE 对不存在的键是 no-op）。失败不抛。 */
+    renew(childSessionId: string): Promise<void>;
+    /** 拿不准当作没人等：猜「有人等」会让该回投的产出被跳过，那是静默丢失。 */
+    isAwaited(childSessionId: string): Promise<boolean>;
+    /** 拿不准时父得 true（放弃等待）、finalizer 得 false（照常回投），合起来就是退化成异步。 */
+    claim(childSessionId: string, by: 'parent' | 'finalizer'): Promise<boolean>;
+}
+export interface RedisTreeBudgetOptions extends RedisKeyOptions {
+    /** 计数键的 TTL，兜底「整棵树都没了、计数还留着」。缺省 1 天。 */
+    ttlSeconds?: number;
+}
+/** 树级名额：Lua 里做「读比较写」，并发 `tryIncr` 不超发。 */
+export declare class RedisTreeBudget implements TreeBudget {
+    private readonly redis;
+    private readonly keys;
+    private readonly ttlSeconds;
+    constructor(redis: Redis, options?: RedisTreeBudgetOptions);
+    tryIncr(rootSessionId: string, limit: number): Promise<boolean>;
+    decr(rootSessionId: string): Promise<void>;
+    /** 与进程内实现一致：n ≤ 0 直接删键。 */
+    set(rootSessionId: string, n: number): Promise<void>;
+}
+export {};
+//# sourceMappingURL=coordination.d.ts.map

package/dist/coordination.d.ts.map

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

package/dist/coordination.js

@@ -0,0 +1,221 @@
+import { randomUUID } from 'node:crypto';
+import { AWAIT_LEASE_TTL_MS, consoleLogger, LOCK_TTL_MS, } from '@qjp88995/agent-runtime';
+import { 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";
+/** SET NX PX 抢锁，Lua 比对 token 再 DEL / PEXPIRE。TTL 兜底持有者崩溃。 */
+export class RedisSessionLock {
+    redis;
+    keys;
+    ttlMs;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.keys = redisKeys(options);
+        this.ttlMs = options.ttlMs ?? LOCK_TTL_MS;
+    }
+    async acquire(sessionId) {
+        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, token) {
+        const res = await this.redis.eval(RENEW_LUA, 1, this.keys.lock(sessionId), token, String(this.ttlMs));
+        return res === 1;
+    }
+    async release(sessionId, token) {
+        await this.redis.eval(RELEASE_LUA, 1, this.keys.lock(sessionId), token);
+    }
+    async isHeld(sessionId) {
+        return (await this.redis.exists(this.keys.lock(sessionId))) === 1;
+    }
+}
+/**
+ * 唤醒 / 空闲广播走 Redis pub/sub（at-most-once，订阅前发的收不到——与端口约定一致）。
+ *
+ * 用 `RedisWakeChannel.create()` 构造：它等 SUBSCRIBE 应答回来才返回，之后 `onWake` / `onIdle`
+ * 只是登记本地处理函数，同步生效。否则「刚订阅就有人 wake」会落在 SUBSCRIBE 应答之前、静默丢失。
+ * 断线重连后 ioredis 会自动重新订阅（`autoResubscribe` 缺省开）；断线期间的广播照样丢，
+ * 这由 sweeper 的启动补唤醒与消费方自己的兜底扫描覆盖。
+ *
+ * 一个处理函数抛错只记日志，不影响别的处理函数，也不冒进 ioredis 的事件循环。
+ */
+export class RedisWakeChannel {
+    redis;
+    sub;
+    ownsSub;
+    keys;
+    logger;
+    wakeHandlers = new Set();
+    idleHandlers = new Set();
+    disposed = false;
+    constructor(redis, sub, ownsSub, keys, logger) {
+        this.redis = redis;
+        this.sub = sub;
+        this.ownsSub = ownsSub;
+        this.keys = keys;
+        this.logger = logger;
+    }
+    static async create(redis, options = {}) {
+        const sub = options.subscriber ?? redis.duplicate();
+        const channel = new RedisWakeChannel(redis, sub, !options.subscriber, redisKeys(options), (options.logger ?? consoleLogger)('RedisWakeChannel'));
+        sub.on('message', (ch, message) => channel.dispatch(ch, message));
+        await sub.subscribe(channel.keys.wakeChannel, channel.keys.idleChannel);
+        return channel;
+    }
+    dispatch(ch, message) {
+        if (ch === this.keys.wakeChannel) {
+            this.fanOut(this.wakeHandlers, message, 'wake');
+        }
+        else if (ch === this.keys.idleChannel) {
+            let sessionId;
+            try {
+                sessionId = JSON.parse(message).sessionId;
+            }
+            catch {
+                sessionId = undefined;
+            }
+            if (typeof sessionId !== 'string') {
+                this.logger.warn(`dropping malformed idle message: ${message}`);
+                return;
+            }
+            this.fanOut(this.idleHandlers, sessionId, 'idle');
+        }
+    }
+    fanOut(handlers, sessionId, kind) {
+        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) {
+        await this.redis.publish(this.keys.wakeChannel, sessionId);
+    }
+    onWake(handler) {
+        this.wakeHandlers.add(handler);
+        return () => this.wakeHandlers.delete(handler);
+    }
+    async idle(sessionId) {
+        await this.redis.publish(this.keys.idleChannel, JSON.stringify({ sessionId }));
+    }
+    onIdle(handler) {
+        this.idleHandlers.add(handler);
+        return () => this.idleHandlers.delete(handler);
+    }
+    /** 摘掉所有处理函数；订阅连接是本对象建的就关掉。 */
+    async dispose() {
+        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);
+        }
+    }
+}
+/**
+ * 等待租约：一个带 TTL 的键。`claim` 是一条原子 DEL，父与 finalizer 抢同一条，恰有一方胜出。
+ * Redis 出错时按端口约定一律退化成异步（见各方法）。
+ */
+export class RedisSubagentAwaitLease {
+    redis;
+    keys;
+    ttlMs;
+    logger;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.keys = redisKeys(options);
+        this.ttlMs = options.ttlMs ?? AWAIT_LEASE_TTL_MS;
+        this.logger = (options.logger ?? consoleLogger)('RedisSubagentAwaitLease');
+    }
+    /** 失败返回 false：没有租约就没有互斥，调用方退回异步模式。 */
+    async begin(childSessionId) {
+        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) {
+        try {
+            await this.redis.pexpire(this.keys.awaited(childSessionId), this.ttlMs);
+        }
+        catch {
+            // 续租失败不打断等待：最坏是租约过期、finalizer 改走回投，父随后超时降级。
+        }
+    }
+    /** 拿不准当作没人等：猜「有人等」会让该回投的产出被跳过，那是静默丢失。 */
+    async isAwaited(childSessionId) {
+        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, by) {
+        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";
+/** 树级名额：Lua 里做「读比较写」，并发 `tryIncr` 不超发。 */
+export class RedisTreeBudget {
+    redis;
+    keys;
+    ttlSeconds;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.keys = redisKeys(options);
+        this.ttlSeconds = options.ttlSeconds ?? 86_400;
+    }
+    async tryIncr(rootSessionId, limit) {
+        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) {
+        await this.redis.eval(DECR_LUA, 1, this.keys.liveSubs(rootSessionId));
+    }
+    /** 与进程内实现一致：n ≤ 0 直接删键。 */
+    async set(rootSessionId, n) {
+        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);
+    }
+}
+//# sourceMappingURL=coordination.js.map

package/dist/coordination.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@qjp88995/agent-runtime` 的 Redis 适配：多实例部署时替换进程内的总线与协调件。
+ *
+ * 换的是五个端口——`StreamBus`、`SessionLock`、`WakeChannel`、`SubagentAwaitLease`、`TreeBudget`。
+ * 存储类端口（跑次、消息、会话、问题、厂商文件）不在这里：它们归宿主的数据库。
+ */
+import type { Redis } from 'ioredis';
+import type { LoggerFactory } from '@qjp88995/agent-runtime';
+import { RedisSessionLock, RedisSubagentAwaitLease, 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, 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;
+    /** 停总线定时器、关唤醒频道的订阅连接。不关 `redis` 本身（它是宿主的）。 */
+    dispose(): Promise<void>;
+}
+/**
+ * 一组 Redis 实现，键名与 `createInProcessPorts()` 的对应项相同，宿主可以直接覆盖：
+ *
+ * ```ts
+ * const ports = { ...createInProcessPorts(), ...(await createRedisPorts(redis)) };
+ * ```
+ *
+ * `redis` 是宿主的共享连接（锁、租约、名额、写会话流都用它）；唤醒频道与每个会话订阅
+ * 各自 `duplicate()` 一条。等唤醒频道订阅就绪才返回。
+ */
+export declare function createRedisPorts(redis: Redis, options?: RedisPortsOptions): Promise<RedisPorts>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,uBAAuB,EACvB,KAAK,8BAA8B,EACnC,eAAe,EACf,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,uBAAuB,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,gDAAgD;IAChD,GAAG,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,uBAAuB,CAAC;IACpC,UAAU,EAAE,eAAe,CAAC;IAC5B,8CAA8C;IAC9C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAerB"}

package/dist/index.js

@@ -0,0 +1,32 @@
+import { RedisSessionLock, RedisSubagentAwaitLease, RedisTreeBudget, RedisWakeChannel, } from './coordination.js';
+import { RedisStreamBus } from './stream-bus.js';
+export { RedisSessionLock, RedisSubagentAwaitLease, RedisTreeBudget, RedisWakeChannel, } from './coordination.js';
+export { redisKeys } from './keys.js';
+export { RedisStreamBus } from './stream-bus.js';
+/**
+ * 一组 Redis 实现，键名与 `createInProcessPorts()` 的对应项相同，宿主可以直接覆盖：
+ *
+ * ```ts
+ * const ports = { ...createInProcessPorts(), ...(await createRedisPorts(redis)) };
+ * ```
+ *
+ * `redis` 是宿主的共享连接（锁、租约、名额、写会话流都用它）；唤醒频道与每个会话订阅
+ * 各自 `duplicate()` 一条。等唤醒频道订阅就绪才返回。
+ */
+export async function createRedisPorts(redis, options = {}) {
+    const { keyPrefix, logger } = options;
+    const wake = await RedisWakeChannel.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 }),
+        async dispose() {
+            bus.dispose();
+            await wake.dispose();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAA8B,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EACL,gBAAgB,EAEhB,uBAAuB,EAEvB,eAAe,EAEf,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAwC,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,cAAc,EAA8B,MAAM,iBAAiB,CAAC;AAkB7E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAY,EACZ,UAA6B,EAAE;IAE/B,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,KAAK,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;IACrE,OAAO;QACL,GAAG;QACH,IAAI,EAAE,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC;QAChD,IAAI;QACJ,UAAU,EAAE,IAAI,uBAAuB,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QACrE,UAAU,EAAE,IAAI,eAAe,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC;QACrD,KAAK,CAAC,OAAO;YACX,GAAG,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 键与频道名。缺省与 agent-base 线上用的一字不差——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;
+}
+export declare function redisKeys(options?: RedisKeyOptions): RedisKeys;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9C;AAED,wBAAgB,SAAS,CAAC,OAAO,GAAE,eAAoB,GAAG,SAAS,CAUlE"}

package/dist/keys.js

@@ -0,0 +1,12 @@
+export function redisKeys(options = {}) {
+    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}`,
+    };
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,SAAS,CAAC,UAA2B,EAAE;IACrD,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAClC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE;QACrC,WAAW,EAAE,GAAG,CAAC,iBAAiB;QAClC,WAAW,EAAE,GAAG,CAAC,oBAAoB;QACrC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAAE;QAC/C,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE;QAC9C,aAAa,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE;KAC7C,CAAC;AACJ,CAAC"}

package/dist/stream-bus.d.ts

@@ -0,0 +1,80 @@
+import type { Redis } from 'ioredis';
+import { type AgentEvent, InProcessStreamBus, type InProcessStreamBusOptions, type SessionStreamEntry } from '@qjp88995/agent-runtime';
+import { type RedisKeyOptions } from './keys.js';
+export interface RedisStreamBusOptions extends RedisKeyOptions, InProcessStreamBusOptions {
+    /** 写侧合并窗口；`null` 关掉合并（一条事件一条条目）。缺省 50ms。 */
+    batchMs?: number | null;
+    /** 落库后的退役宽限期。缺省 30s。 */
+    retireGraceMs?: number;
+    /** 会话流的 MAXLEN 兜底。缺省 10000。 */
+    maxLen?: number;
+    /** 会话流的 TTL（每写一条刷新）。缺省 1 小时；轮次登记表在进程里也活这么久。 */
+    streamTtlSeconds?: number;
+    /** 一次 XREAD 阻塞多久后回来检查 abort。缺省 5s。 */
+    xreadBlockMs?: number;
+}
+/**
+ * 多实例事件总线：**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 declare class RedisStreamBus extends InProcessStreamBus {
+    private readonly redis;
+    private readonly keys;
+    private readonly batchMs;
+    private readonly graceMs;
+    private readonly maxLen;
+    private readonly streamTtlSeconds;
+    private readonly xreadBlockMs;
+    private readonly pendingByRoot;
+    private readonly entriesByRun;
+    private readonly timers;
+    private readonly runTableTimer;
+    constructor(redis: Redis, options?: RedisStreamBusOptions);
+    publish(event: AgentEvent): void;
+    publishSessionEvent(event: AgentEvent): void;
+    retireUpTo(runId: string, uptoSeq: number): void;
+    /** 宽限期后执行；`dispose()` 会清掉还没到点的。 */
+    private later;
+    /**
+     * 会话面入口。序列化在进入 fire-and-forget 链之前同步做完（见 `xaddSession`），非 JSON-safe
+     * 载荷不会经 `publish` 冒进 `runTurn`。
+     */
+    private enqueueSession;
+    private flushPending;
+    /** 写一条并登记；返回的 promise 在登记完（或失败被吞）后落定，从不 reject。 */
+    private xaddSession;
+    private deleteEntries;
+    /** 轮次登记表兜底清理：正常路径由 run-finish / error 清；崩溃或别的实例收尾的轮次靠这里。 */
+    private sweepRunTables;
+    /**
+     * 每个订阅一条独立连接（XREAD BLOCK 会占住连接）；`signal` abort 时断开它，在途的 XREAD 随之结束。
+     */
+    subscribeSession(rootSessionId: string, fromId: string | undefined, signal: AbortSignal): AsyncIterable<SessionStreamEntry>;
+    /**
+     * 停掉定时器：攒着的 delta 立刻写出去（不丢），还没到点的退役放弃（条目由 TTL / MAXLEN 兜底）。
+     * 不关宿主给的连接。
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=stream-bus.d.ts.map

package/dist/stream-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-bus.d.ts","sourceRoot":"","sources":["../src/stream-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,KAAK,eAAe,EAA6B,MAAM,WAAW,CAAC;AA+E5E,MAAM,WAAW,qBACf,SAAQ,eAAe,EAAE,yBAAyB;IAClD,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IAalD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAZxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;gBAG5B,KAAK,EAAE,KAAK,EAC7B,OAAO,GAAE,qBAA0B;IAiB5B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAKhC,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAI5C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzD,mCAAmC;IACnC,OAAO,CAAC,KAAK;IASb;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,YAAY;IAQpB,mDAAmD;IACnD,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,aAAa;IAiBrB,4DAA4D;IAC5D,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACa,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,WAAW,GAClB,aAAa,CAAC,kBAAkB,CAAC;IA2CpC;;;OAGG;IACM,OAAO,IAAI,IAAI;CAOzB"}