@lingxiao-office/sdk 1.0.0

package/dist/core/MessageBus.d.ts

@@ -0,0 +1,247 @@
+import { EventEmitter } from './EventEmitter.js';
+import type { Transport, TransportEnvelope } from './transport/Transport.js';
+/**
+ * 消息类型定义 —— BusMessage 判别联合(完全结构化)。
+ * 旧 `{type: string; payload: unknown}` 已升级为按 type 收窄 payload 的判别联合,
+ * 详见 BusMessageTypes.ts。这里 re-export 保持现有 `import { BusMessage } from './MessageBus.js'` 不破。
+ */
+import { type BusMessage, type BusMessageType, type BusMessagePayloadMap } from './BusMessageTypes.js';
+export type { BusMessage, BusMessageType, BusMessagePayloadMap } from './BusMessageTypes.js';
+/**
+ * 消息优先级枚举
+ * P0_CRITICAL: task_complete, task_failed, worker_recovery, user_intervention, force_terminate
+ * P1_HIGH: permission_request, permission_response, agent_error, message
+ * P2_NORMAL: default, regular messages
+ * P3_LOW: supervision_probe
+ */
+export declare enum MessagePriority {
+    P0_CRITICAL = 0,
+    P1_HIGH = 1,
+    P2_NORMAL = 2,
+    P3_LOW = 3
+}
+/**
+ * 优先级邮箱 — 四个桶分别存放不同优先级的消息
+ */
+export interface PriorityInbox {
+    p0: BusMessage[];
+    p1: BusMessage[];
+    p2: BusMessage[];
+    p3: BusMessage[];
+    /** Timestamp of last poll/dequeue operation — used for stale inbox detection */
+    lastAccessTime: number;
+}
+/** Keys that correspond to priority message buckets (excludes metadata fields) */
+export type PriorityBucketKey = 'p0' | 'p1' | 'p2' | 'p3';
+/**
+ * 优先级计数
+ */
+export interface PriorityCounts {
+    p0: number;
+    p1: number;
+    p2: number;
+    p3: number;
+}
+/**
+ * 消息处理器类型
+ */
+export type MessageHandler = (message: BusMessage) => void | Promise<void>;
+export interface MessageHandlerFailure {
+    messageId: string;
+    to: string;
+    handlerRecipient: string;
+    type: string;
+    error: string;
+    timestamp: number;
+}
+export interface ReliableSendOptions {
+    sessionId?: string;
+    retries?: number;
+    backoffMs?: number;
+}
+export type ReliableSendResult = {
+    ok: true;
+    messageId: string;
+    attempts: number;
+} | {
+    ok: false;
+    attempts: number;
+    error: string;
+};
+/**
+ * 根据消息类型自动分类优先级
+ */
+export declare function classifyPriority(type: string): MessagePriority;
+export declare function isReliableCriticalMessageType(type: string): boolean;
+/**
+ * 消息总线 - 用于 Agent 间通信
+ * 支持四级优先级队列，P0 消息可立即唤醒等待者
+ */
+export declare class MessageBus {
+    private handlers;
+    private messageHistory;
+    private inboxes;
+    private waiters;
+    private p0Waiters;
+    /** 等待 ACK 的回调: messageId -> { resolve, timeoutId, deadline } */
+    private pendingAcks;
+    private handlerFailures;
+    private maxHistorySize;
+    private maxHistoryBytes;
+    private historyBytes;
+    private emitter;
+    private cleanupTimer?;
+    private transport;
+    private nextSeq;
+    constructor(maxHistorySize?: number, emitter?: EventEmitter, maxHistoryBytes?: number, transport?: Transport);
+    /**
+     * 生成唯一消息 ID
+     */
+    private generateId;
+    /**
+     * 创建空的优先级邮箱
+     */
+    private createEmptyInbox;
+    /**
+     * 获取优先级桶的 key
+     */
+    private priorityKey;
+    private estimatePayloadBytes;
+    private ensureMessageSize;
+    private enforceInboxBudget;
+    register(recipient: string): void;
+    /**
+     * 注销收件人，清理其所有状态（inbox、waiters、handlers、p0Waiters）
+     */
+    unregister(recipient: string): void;
+    /**
+     * 获取收件人邮箱（展平为单一数组，按优先级排序）
+     */
+    private getFlattenedInbox;
+    /**
+     * 同一 P0 桶内，用户介入永远优先于自治/worker 事件。
+     * FIFO 仍在 user_intervention 子集内保持，避免连续用户输入倒序。
+     */
+    private orderBucketMessages;
+    /**
+     * 发送消息
+     * @param from 发送者 ID
+     * @param to 接收者 ID (或 '*' 表示广播)
+     * @param type 消息类型
+     * @param payload 消息内容
+     * @returns 消息 ID
+     */
+    send<K extends BusMessageType>(from: string, to: string, type: K, payload: BusMessagePayloadMap[K]): string;
+    send(message: BusMessage): string;
+    sendReliable<K extends BusMessageType>(from: string, to: string, type: K, payload: BusMessagePayloadMap[K], options?: ReliableSendOptions): Promise<ReliableSendResult>;
+    getTransport(): Transport;
+    sendTransportEnvelope(type: TransportEnvelope['type'], payload: unknown): void;
+    private handleTransportEnvelope;
+    /**
+     * 内部消息投递 — 路由到正确的优先级桶并唤醒等待者
+     */
+    private deliverMessage;
+    private shouldRouteViaTransport;
+    /**
+     * 广播消息（发送给所有订阅者）
+     */
+    broadcast<K extends BusMessageType>(from: string, type: K, payload: BusMessagePayloadMap[K]): string;
+    /**
+     * 分发消息到对应的处理器
+     */
+    private dispatch;
+    private recordHandlerFailure;
+    getHandlerFailures(limit?: number): MessageHandlerFailure[];
+    /**
+     * 订阅消息
+     * @param recipient 接收者 ID (或 '*' 接收所有消息)
+     * @param handler 消息处理器
+     */
+    subscribe(recipient: string, handler: MessageHandler): () => void;
+    /**
+     * 取消订阅
+     */
+    unsubscribe(recipient: string, handler: MessageHandler): void;
+    /**
+     * 获取消息历史
+     * @param recipient 过滤接收者（可选）
+     * @param from 过滤发送者（可选）
+     * @param limit 限制数量
+     */
+    getHistory(recipient?: string, from?: string, limit?: number): BusMessage[];
+    /**
+     * 轮询获取新消息 — 按优先级顺序 P0 → P1 → P2 → P3
+     * @param recipient 接收者 ID
+     * @param from 最后一条消息的时间戳（可选）
+     */
+    poll(recipient: string, from?: number): BusMessage[];
+    /**
+     * 只消费指定类型的消息，保留其他消息在收件箱中。
+     * 用于 Leader 在执行自治动作前抢占式抽取 user_intervention。
+     */
+    pollByType(recipient: string, types: string[]): BusMessage[];
+    /**
+     * 查看当前收件箱快照（不消费消息）— 按优先级排序
+     */
+    peek(recipient: string): BusMessage[];
+    removeMessages(recipient: string, messageIds: string[]): number;
+    pollAfterSeq(recipient: string, afterSeq?: number): BusMessage[];
+    /**
+     * 获取两个 Agent 之间的消息
+     */
+    getConversation(agentA: string, agentB: string, limit?: number): BusMessage[];
+    /**
+     * 清空历史
+     */
+    clearHistory(): void;
+    /**
+     * 获取各优先级的待处理消息数量
+     */
+    getPendingPriorityCounts(recipient: string): PriorityCounts;
+    /**
+     * 发送消息并等待接收方 ACK 确认
+     * @returns { delivered: true, ackTime: number } 如果收到 ACK
+     * @returns { delivered: false } 如果超时未收到 ACK
+     */
+    sendWithAck<K extends BusMessageType>(from: string, to: string, type: K, payload: BusMessagePayloadMap[K], timeout?: number): Promise<{
+        delivered: boolean;
+        ackTime?: number;
+    }>;
+    /**
+     * 接收方调用：确认收到消息
+     */
+    acknowledge(recipient: string, messageId: string): void;
+    /**
+     * 获取等待消息（阻塞直到收到消息或超时）
+     * @param recipient 接收者 ID
+     * @param timeout 超时时间（毫秒）
+     */
+    waitForMessage(recipient: string, timeout?: number): Promise<BusMessage | null>;
+    /**
+     * 等待 P0 关键消息 — 收到 P0 消息时立即 resolve
+     * 用于 Leader 主循环的即时唤醒
+     * @param recipient 接收者 ID
+     * @param timeout 超时时间（毫秒）
+     */
+    waitForCriticalMessage(recipient: string, timeout?: number): Promise<BusMessage | null>;
+    /**
+     * 等待特定类型的消息
+     */
+    waitForMessageType(recipient: string, type: string, timeout?: number): Promise<BusMessage | null>;
+    /**
+     * 获取订阅者数量
+     */
+    getSubscriberCount(recipient?: string): number;
+    destroy(): void;
+    cleanupStaleInboxesForTest(): void;
+    setInboxLastAccessTimeForTest(recipient: string, lastAccessTime: number): void;
+    /**
+     * 清理过大的 inbox 以及 dead inbox（超过 STALE_INBOX_MS 未被 poll）。
+     * 同时清理超期的 pendingAcks 条目。
+     */
+    private cleanupStaleInboxes;
+}
+export declare function createMessageBus(maxHistorySize?: number, emitter?: EventEmitter, maxHistoryBytes?: number, transport?: Transport): MessageBus;
+export declare function getMessageBus(): MessageBus;
+export default MessageBus;
+//# sourceMappingURL=MessageBus.d.ts.map

package/dist/core/MessageBus.d.ts.map

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