hyacinth-ai 0.9.6

package/dist/channels/builtin/tui-channel.d.ts

@@ -0,0 +1,33 @@
+import type { ChannelHandler, ChannelEvent, ChannelReply, ChannelConfig, ChannelStatus, ChannelMessageEvent, AgentFactory, ReplyFn } from '../interface.js';
+/**
+ * TUI Channel — 将终端界面包装为标准渠道
+ *
+ * 这是一个轻量包装，不包含 blessed 渲染逻辑。
+ * blessed UI 代码仍留在 tui.ts 中，只是输入/输出通过此渠道桥接。
+ */
+export declare class TuiChannel implements ChannelHandler {
+    readonly id = "tui";
+    readonly name = "TUI Terminal";
+    readonly description = "\u5185\u5EFA\u7EC8\u7AEF\u7528\u6237\u754C\u9762\uFF0C\u901A\u8FC7 blessed \u6E32\u67D3";
+    readonly pluginId: undefined;
+    private status;
+    private eventHandler;
+    start(config: ChannelConfig): Promise<void>;
+    stop(): Promise<void>;
+    onEvent(handler: (event: ChannelEvent) => Promise<void>): void;
+    /**
+     * 发送用户输入消息（由 tui.ts 的 input handler 调用）
+     */
+    sendMessage(sessionId: string, content: string): Promise<void>;
+    /**
+     * 发送 Agent 回复到 TUI（由 ChannelManager 的 MessageProcessor 调用）
+     */
+    reply(_sessionId: string, reply: ChannelReply): Promise<void>;
+    getStatus(): ChannelStatus;
+    /** Agent 回复回调（tui.ts 设置此函数来输出到屏幕） */
+    onReply: ((content: string) => void) | null;
+    /** 消息处理回调（由 tui.ts 设置，TUI 使用主 loop 处理消息） */
+    onHandleMessage: ((event: ChannelMessageEvent, replyFn: ReplyFn) => Promise<void>) | null;
+    handleMessage(event: ChannelMessageEvent, replyFn: ReplyFn, _agentFactory: AgentFactory): Promise<void>;
+}
+//# sourceMappingURL=tui-channel.d.ts.map

package/dist/channels/builtin/tui-channel.js

@@ -0,0 +1,61 @@
+/**
+ * TUI Channel — 将终端界面包装为标准渠道
+ *
+ * 这是一个轻量包装，不包含 blessed 渲染逻辑。
+ * blessed UI 代码仍留在 tui.ts 中，只是输入/输出通过此渠道桥接。
+ */
+export class TuiChannel {
+    id = 'tui';
+    name = 'TUI Terminal';
+    description = '内建终端用户界面，通过 blessed 渲染';
+    pluginId = undefined;
+    status = 'registered';
+    eventHandler = null;
+    async start(config) {
+        this.status = 'active';
+    }
+    async stop() {
+        this.status = 'stopped';
+    }
+    onEvent(handler) {
+        this.eventHandler = handler;
+    }
+    /**
+     * 发送用户输入消息（由 tui.ts 的 input handler 调用）
+     */
+    async sendMessage(sessionId, content) {
+        if (!this.eventHandler)
+            return;
+        await this.eventHandler({
+            type: 'message',
+            sessionId,
+            userId: 'tui-user',
+            content,
+            channel: this.id,
+            metadata: { source: 'tui' },
+        });
+    }
+    /**
+     * 发送 Agent 回复到 TUI（由 ChannelManager 的 MessageProcessor 调用）
+     */
+    async reply(_sessionId, reply) {
+        // 输出到终端（由 tui.ts 注册的回调处理）
+        if (this.onReply) {
+            this.onReply(reply.content);
+        }
+    }
+    getStatus() {
+        return this.status;
+    }
+    // ── TUI 专属回调（由 tui.ts 设置） ──
+    /** Agent 回复回调（tui.ts 设置此函数来输出到屏幕） */
+    onReply = null;
+    /** 消息处理回调（由 tui.ts 设置，TUI 使用主 loop 处理消息） */
+    onHandleMessage = null;
+    async handleMessage(event, replyFn, _agentFactory) {
+        if (this.onHandleMessage) {
+            await this.onHandleMessage(event, replyFn);
+        }
+    }
+}
+//# sourceMappingURL=tui-channel.js.map

package/dist/channels/builtin/tui-ws-session.d.ts

@@ -0,0 +1,16 @@
+import type { AgentFactory } from '../interface.js';
+import { type WsLike } from './webui-output-handler.js';
+export declare class TuiWsSession {
+    readonly sessionId: string;
+    private ws;
+    private outputHandler;
+    private loop;
+    private _initialized;
+    private isProcessing;
+    constructor(ws: WsLike, sessionId: string);
+    initialize(agentFactory: AgentFactory): Promise<void>;
+    handleMessage(raw: Buffer): Promise<void>;
+    private send;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=tui-ws-session.d.ts.map

package/dist/channels/builtin/tui-ws-session.js

@@ -0,0 +1,90 @@
+// ============================================================
+// TuiWsSession — TUI over WebSocket 会话管理
+// ============================================================
+//
+// 当 TUI 客户端通过 WebSocket 连接到 serve 后端时使用。
+// 与 WebUIWsSession 结构相同，专用于 TUI 渠道。
+// ============================================================
+import { WebUIOutputHandler } from './webui-output-handler.js';
+import { createLogger } from '../../logging/logger.js';
+const logger = createLogger('tui-ws-session');
+export class TuiWsSession {
+    sessionId;
+    ws;
+    outputHandler;
+    loop = null;
+    _initialized = false;
+    isProcessing = false;
+    constructor(ws, sessionId) {
+        this.ws = ws;
+        this.sessionId = sessionId;
+        this.outputHandler = new WebUIOutputHandler(ws);
+    }
+    async initialize(agentFactory) {
+        try {
+            const result = await agentFactory.createAgent({
+                sessionId: this.sessionId,
+                outputHandler: this.outputHandler,
+            });
+            this.loop = result.loop;
+            this._initialized = true;
+            this.send({ type: 'connected', sessionId: this.sessionId });
+            logger.info('TUI WS session initialized', { sessionId: this.sessionId });
+        }
+        catch (err) {
+            logger.error('TUI WS session init failed', err instanceof Error ? err : new Error(String(err)));
+            this.send({ type: 'error', message: `Init failed: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    async handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        if (!this._initialized) {
+            this.send({ type: 'error', message: 'Initializing...' });
+            return;
+        }
+        switch (msg.type) {
+            case 'chat':
+                if (!msg.content?.trim() || !this.loop || this.isProcessing)
+                    return;
+                this.isProcessing = true;
+                try {
+                    await this.loop.run(msg.content);
+                    const turnInfo = this.loop.getTurnInfo(this.loop.turnNumber, 0);
+                    this.send({ type: 'turn_info', ...turnInfo });
+                }
+                catch (err) {
+                    this.send({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+                }
+                finally {
+                    this.isProcessing = false;
+                }
+                break;
+            case 'stop':
+                if (this.loop && typeof this.loop.requestStop === 'function') {
+                    this.loop.requestStop();
+                }
+                break;
+            case 'permission':
+                this.outputHandler.resolvePermission(msg.result ?? 'no');
+                break;
+        }
+    }
+    send(msg) {
+        if (this.ws.readyState === 1) {
+            try {
+                this.ws.send(JSON.stringify(msg));
+            }
+            catch { }
+        }
+    }
+    async close() {
+        this.loop = null;
+    }
+}
+//# sourceMappingURL=tui-ws-session.js.map

package/dist/channels/builtin/webui-output-handler.d.ts

@@ -0,0 +1,30 @@
+import type { OutputHandler, TurnInfo } from '../../orchestrator/loop.js';
+/** WebSocket 最小接口（避免静态依赖 ws 库） */
+export interface WsLike {
+    send(data: string): void;
+    readyState: number;
+}
+export declare class WebUIOutputHandler implements OutputHandler {
+    private ws;
+    private permissionResolve;
+    constructor(ws: WsLike);
+    onText(content: string): void;
+    onThinking(content: string): void;
+    onToolUse(name: string, inputSummary: string, toolId?: string): void;
+    onToolResult(content: string, isError: boolean, toolId?: string): void;
+    onDiff(toolId: string, filePath: string, diffLines: Array<{
+        kind: string;
+        text: string;
+    }>): void;
+    onStatus(message: string, level: 'info' | 'warn' | 'error'): void;
+    onTurnStart(): void;
+    onFlush(): void;
+    onInterrupt(): void;
+    onPermissionRequest(toolName: string, input: Record<string, unknown>): Promise<'yes' | 'no' | 'always'>;
+    /** 发送回合状态更新 */
+    sendTurnInfo(info: TurnInfo): void;
+    /** 响应权限请求（来自 WebSocket 消息） */
+    resolvePermission(result: 'yes' | 'no' | 'always'): void;
+    private send;
+}
+//# sourceMappingURL=webui-output-handler.d.ts.map

package/dist/channels/builtin/webui-output-handler.js

@@ -0,0 +1,93 @@
+// ============================================================
+// WsOutputHandler — OutputHandler → WebSocket 适配器
+// ============================================================
+//
+// 将 AgentLoop 的 OutputHandler 回调转换为 WebSocket JSON 消息。
+// 供 TUI-over-WS 等渠道使用。
+// ============================================================
+// ws 库的 OPEN 常量
+const WS_OPEN = 1;
+export class WebUIOutputHandler {
+    ws;
+    permissionResolve = null;
+    constructor(ws) {
+        this.ws = ws;
+    }
+    // ── OutputHandler 实现 ─────────────────────────────────────
+    onText(content) {
+        this.send({ type: 'text', content });
+    }
+    onThinking(content) {
+        this.send({ type: 'thinking', content });
+    }
+    onToolUse(name, inputSummary, toolId) {
+        this.send({
+            type: 'tool_use',
+            id: toolId ?? `tool_${Date.now()}`,
+            name,
+            inputSummary,
+        });
+    }
+    onToolResult(content, isError, toolId) {
+        this.send({
+            type: 'tool_result',
+            id: toolId ?? '',
+            content,
+            isError,
+        });
+    }
+    onDiff(toolId, filePath, diffLines) {
+        this.send({ type: 'diff', id: toolId, filePath, diffLines });
+    }
+    onStatus(message, level) {
+        this.send({ type: 'status', message, level });
+    }
+    onTurnStart() {
+        this.send({ type: 'turn_start' });
+    }
+    onFlush() {
+        this.send({ type: 'flush' });
+    }
+    onInterrupt() {
+        this.send({ type: 'interrupt' });
+    }
+    onPermissionRequest(toolName, input) {
+        this.send({ type: 'permission', toolName, input });
+        return new Promise((resolve) => {
+            this.permissionResolve = resolve;
+        });
+    }
+    // ── 扩展方法 ───────────────────────────────────────────────
+    /** 发送回合状态更新 */
+    sendTurnInfo(info) {
+        this.send({
+            type: 'turn_info',
+            turnCount: info.turnCount,
+            maxTurns: info.maxTurns,
+            tokensUsed: info.tokensUsed,
+            maxTokens: info.maxContextTokens ?? 200000,
+            cacheHitRate: info.cacheHitRate ?? null,
+            compressCount: 0,
+        });
+    }
+    /** 响应权限请求（来自 WebSocket 消息） */
+    resolvePermission(result) {
+        if (this.permissionResolve) {
+            const resolve = this.permissionResolve;
+            this.permissionResolve = null;
+            resolve(result);
+        }
+    }
+    // ── 内部方法 ──────────────────────────────────────────────
+    send(msg) {
+        if (this.ws.readyState === WS_OPEN) {
+            try {
+                this.ws.send(JSON.stringify(msg));
+            }
+            catch {
+                // 连接已断开，忽略发送错误
+            }
+        }
+    }
+}
+//# sourceMappingURL=webui-output-handler.js.map

package/dist/channels/index.d.ts

@@ -0,0 +1,5 @@
+export type { ChannelHandler, ChannelConfig, ChannelEvent, ChannelMessageEvent, ChannelConnectedEvent, ChannelDisconnectedEvent, ChannelErrorEvent, ChannelReply, ChannelState, ChannelStatus, AgentFactory, ReplyFn, } from './interface.js';
+export { ChannelManager } from './manager.js';
+export { MessageQueue, QueueMessageMode } from './message-queue.js';
+export type { QueueItem } from './message-queue.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/index.js

@@ -0,0 +1,3 @@
+export { ChannelManager } from './manager.js';
+export { MessageQueue, QueueMessageMode } from './message-queue.js';
+//# sourceMappingURL=index.js.map

package/dist/channels/interface.d.ts

@@ -0,0 +1,148 @@
+export interface ChannelConfig {
+    /** 用户自定义配置项 */
+    [key: string]: unknown;
+    /** 是否启用此渠道 */
+    enabled?: boolean;
+}
+/** 渠道收到的事件 */
+export type ChannelEvent = ChannelMessageEvent | ChannelConnectedEvent | ChannelDisconnectedEvent | ChannelErrorEvent;
+/** 用户消息事件 */
+export interface ChannelMessageEvent {
+    type: 'message';
+    sessionId: string;
+    userId: string;
+    content: string;
+    channel: string;
+    /** 图片数据（base64 + MIME）。各渠道自行下载后填入，可选 */
+    images?: Array<{
+        data: string;
+        media_type: string;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+/** 渠道连接成功 */
+export interface ChannelConnectedEvent {
+    type: 'connected';
+    channel: string;
+}
+/** 渠道断开连接 */
+export interface ChannelDisconnectedEvent {
+    type: 'disconnected';
+    channel: string;
+}
+/** 渠道错误 */
+export interface ChannelErrorEvent {
+    type: 'error';
+    channel: string;
+    error: string;
+}
+/** Agent 回复给渠道的消息 */
+export interface ChannelReply {
+    content: string;
+    images?: Array<{
+        data: string;
+        media_type: string;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+/** 输出处理器（渠道消息收集用） */
+export interface ChannelOutputHandler {
+    onText?(content: string): void;
+    onToolUse?(name: string, inputSummary: string): void;
+    onStatus?(message: string, level?: string): void;
+    onTurnStart?(): void;
+    onFlush?(): void;
+    onInterrupt?(): void;
+}
+/** AgentLoop 运行接口 */
+export interface ChannelSessionRunner {
+    run(input: string): Promise<void>;
+    setOutputHandler(handler: ChannelOutputHandler): void;
+}
+/** AgentLoop 创建工厂（由 gateway 注入，渠道通过此接口创建 AgentLoop） */
+export interface AgentFactory {
+    createAgent(options: {
+        sessionId?: string;
+        outputHandler: ChannelOutputHandler;
+        channelsInfo?: unknown;
+        /** 渠道标识 */
+        channel?: string;
+    }): Promise<{
+        loop: ChannelSessionRunner;
+    }>;
+}
+/** 回复函数类型 */
+export type ReplyFn = (reply: ChannelReply) => Promise<void>;
+/**
+ * ChannelHandler — 所有渠道必须实现此接口。
+ *
+ * 生命周期：
+ *   1. register → 注册到 ChannelManager
+ *   2. start() → 启动渠道（建连、监听）
+ *   3. onEvent() → 渠道收到消息时调用注册的回调
+ *   4. reply() → Gateway 调此方法向用户发送回复
+ *   5. stop() → 停止渠道
+ */
+export interface ChannelHandler {
+    /** 唯一渠道 ID */
+    readonly id: string;
+    /** 显示名称 */
+    readonly name: string;
+    /** 简短描述 */
+    readonly description: string;
+    /** 是否由插件注册（vs 内置渠道） */
+    readonly pluginId?: string;
+    /**
+     * 启动渠道
+     * 渠道在此方法中建立连接、启动监听、注册路由等
+     */
+    start(config: ChannelConfig): Promise<void>;
+    /**
+     * 停止渠道
+     * 渠道在此方法中断开连接、清理资源
+     */
+    stop(): Promise<void>;
+    /**
+     * 订阅事件
+     * Gateway 调用此方法，传入事件处理函数。
+     * 渠道在收到消息时调用 handler(event)。
+     */
+    onEvent(handler: (event: ChannelEvent) => Promise<void>): void;
+    /**
+     * 发送回复
+     * Gateway 调用此方法，将 Agent 的回复发回给用户。
+     */
+    reply(sessionId: string, reply: ChannelReply): Promise<void>;
+    /**
+     * 处理消息（渠道自行管理 session、AgentLoop、回复）
+     * Gateway 不再在统一回调中分支处理不同渠道
+     */
+    handleMessage(event: ChannelMessageEvent, replyFn: ReplyFn, agentFactory: AgentFactory): Promise<void>;
+    /**
+     * 配置热更新（可选）
+     * Gateway 配置监听检测到变更时调用
+     */
+    updateConfig?(newConfig: Record<string, unknown>): Promise<void>;
+    /**
+     * 处理 TUI 子命令（可选）。
+     * 当用户在 TUI 中输入 /<channelId>/<subCmd> 时，框架将 cmdPath
+     * 路由到此方法。渠道根据 cmdPath 自行分发。
+     *
+     * @param cmdPath 完整命令路径，如 "clawbot/login"
+     * @param args 命令后的剩余参数
+     * @returns 要渲染到 TUI 的文本，或 null 表示不处理此命令
+     */
+    handleTuiCommand?(cmdPath: string, args: string): Promise<string | null>;
+    /**
+     * 获取渠道状态
+     */
+    getStatus(): ChannelStatus;
+}
+export type ChannelStatus = 'registered' | 'starting' | 'active' | 'stopped' | 'error';
+export interface ChannelState {
+    handler: ChannelHandler;
+    status: ChannelStatus;
+    error?: string;
+    config: ChannelConfig;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/channels/interface.js

@@ -0,0 +1,15 @@
+// ============================================================
+// Channel — 渠道抽象层
+// ============================================================
+//
+// 一个 Channel 是 agent 与外部世界之间的消息管道。
+// 用户可以来自 TUI、HTTP webhook、企业微信、飞书、钉钉……
+// 框架不关心消息来源，只关心收发接口。
+//
+// 渠道可以是：
+//   - 内置渠道（TUI、HTTP webhook）— 框架自带
+//   - 插件渠道（企微、飞书、微信、Telegram…）— 通过 PluginApi.registerChannel() 注册
+//   - MCP 渠道 — 通过 MCP Server 暴露
+// ============================================================
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/channels/manager.d.ts

@@ -0,0 +1,43 @@
+import type { ChannelHandler, ChannelConfig, ChannelReply, ChannelState, ChannelStatus, AgentFactory } from './interface.js';
+export declare class ChannelManager {
+    private channels;
+    private started;
+    /** 注册一个渠道处理器 */
+    register(handler: ChannelHandler, config?: ChannelConfig): void;
+    /** 批量注册 */
+    registerAll(entries: Array<{
+        handler: ChannelHandler;
+        config?: ChannelConfig;
+    }>): void;
+    /** 获取所有已注册渠道 */
+    getAll(): ChannelState[];
+    /** 获取指定渠道 */
+    get(id: string): ChannelState | undefined;
+    /** 获取活跃渠道 */
+    getActive(): ChannelState[];
+    /**
+     * 启动所有启用的渠道
+     * 每个渠道自行处理消息（通过 handler.handleMessage）
+     */
+    startAll(agentFactory: AgentFactory, enabledIds?: string[]): Promise<void>;
+    /** 启动单个渠道 */
+    startChannel(state: ChannelState, agentFactory: AgentFactory): Promise<void>;
+    /** 停止所有渠道 */
+    stopAll(): Promise<void>;
+    /** 停止单个渠道 */
+    stopChannel(state: ChannelState): Promise<void>;
+    /** 重启指定渠道 */
+    restart(id: string, agentFactory: AgentFactory): Promise<void>;
+    /**
+     * 通过指定渠道主动发送消息
+     */
+    send(channelId: string, sessionId: string, reply: ChannelReply): Promise<void>;
+    getStatusSummary(): Array<{
+        id: string;
+        name: string;
+        status: ChannelStatus;
+    }>;
+    /** 是否已启动 */
+    isStarted(): boolean;
+}
+//# sourceMappingURL=manager.d.ts.map