@ynhcj/xiaoyi-channel 0.0.2 → 0.0.3-next

package/dist/src/tools/upload-photo-tool.js

@@ -0,0 +1,223 @@
+import { getXYWebSocketManager } from "../client.js";
+import { sendCommand } from "../formatter.js";
+import { getCurrentSessionContext } from "./session-manager.js";
+import { logger } from "../utils/logger.js";
+/**
+ * XY upload photo tool - uploads local photos to get publicly accessible URLs.
+ * Requires mediaUris from search_photo_gallery tool as prerequisite.
+ *
+ * Prerequisites:
+ * 1. Call search_photo_gallery tool first to get mediaUris of photos
+ * 2. Use the mediaUris (maximum 5 at a time) to get public URLs
+ */
+export const uploadPhotoTool = {
+    name: "upload_photo",
+    label: "Upload Photo",
+    description: `工具能力描述：将手机本地文件回传并获取可公网访问的 URL。
+  
+  前置工具调用：此工具使用前必须先调用 search_photo_gallery 工具获取照片的 mediaUri或者thumbnailUri
+  工具参数说明：
+  a. 入参中的mediaUris中的mediaUri必须与search_photo_gallery结果中对应的mediaUri或者thumbnailUri完全保持一致，不要自行修改，必须是file:://开头的路径。
+  b. 优先使用search_photo_gallery结果中的thumbnailUri作为入参，thumbnailUri是缩略图，清晰度与文件大小都非常合适展示给用户，如果thumbnailUri不存在或者用户要求使用原图，则使用search_photo_gallery结果中对应的mediaUri
+  c. mediaUris 是照片在手机本地的 URI 数组（从 search_photo_gallery 工具响应中获取）。限制：每次最多支持传入 3 条 mediaUri。
+  
+  注意事项：
+  a. 操作超时时间为60秒,请勿重复调用此工具,如果超时或失败,最多重试一次。
+  b. 此工具返回的图片链接为用户公网可访问的链接，如果需要后续操作需要下载到本地，如果需要返回给用户查看则直接以图片markdown的形式返回给用户`,
+    parameters: {
+        type: "object",
+        properties: {
+            mediaUris: {
+                // 不指定 type，允许传入数组或 JSON 字符串
+                // 具体的类型验证和转换在 execute 函数内部进行
+                description: "照片在手机本地的 URI 数组，必须先通过 search_photo_gallery 工具获取。每次最多支持 3 条 URI。",
+            },
+        },
+        required: ["mediaUris"],
+    },
+    async execute(toolCallId, params) {
+        logger.log(`[UPLOAD_PHOTO_TOOL] 🚀 Starting execution`);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - toolCallId: ${toolCallId}`);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - params (raw):`, JSON.stringify(params));
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - params.mediaUris type:`, typeof params.mediaUris);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - timestamp: ${new Date().toISOString()}`);
+        // ===== 参数规范化：兼容数组和 JSON 字符串 =====
+        let mediaUris = null;
+        if (!params.mediaUris) {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Missing parameter: mediaUris`);
+            throw new Error("Missing required parameter: mediaUris");
+        }
+        // 情况1: 已经是数组
+        if (Array.isArray(params.mediaUris)) {
+            logger.log(`[UPLOAD_PHOTO_TOOL] ✅ mediaUris is already an array`);
+            mediaUris = params.mediaUris;
+        }
+        // 情况2: 是字符串，尝试解析为 JSON 数组
+        else if (typeof params.mediaUris === 'string') {
+            logger.log(`[UPLOAD_PHOTO_TOOL] 🔄 mediaUris is a string, attempting to parse as JSON...`);
+            try {
+                const parsed = JSON.parse(params.mediaUris);
+                if (Array.isArray(parsed)) {
+                    logger.log(`[UPLOAD_PHOTO_TOOL] ✅ Successfully parsed JSON string to array`);
+                    mediaUris = parsed;
+                }
+                else {
+                    logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Parsed JSON is not an array:`, typeof parsed);
+                    throw new Error("mediaUris must be an array or a JSON string representing an array");
+                }
+            }
+            catch (parseError) {
+                logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Failed to parse mediaUris as JSON:`, parseError);
+                throw new Error(`mediaUris must be a valid JSON array string. Parse error: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+            }
+        }
+        // 情况3: 其他类型，报错
+        else {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Invalid mediaUris type:`, typeof params.mediaUris);
+            throw new Error(`mediaUris must be an array or a JSON string, got ${typeof params.mediaUris}`);
+        }
+        // 验证数组非空
+        if (!mediaUris || mediaUris.length === 0) {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ mediaUris array is empty`);
+            throw new Error("mediaUris array cannot be empty");
+        }
+        logger.log(`[UPLOAD_PHOTO_TOOL] ✅ Normalized mediaUris:`, JSON.stringify(mediaUris));
+        // Validate maximum 5 URIs
+        if (mediaUris.length > 5) {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Too many mediaUris: ${mediaUris.length}`);
+            throw new Error(`最多支持 5 条 mediaUri，当前提供了 ${mediaUris.length} 条。请分批处理。`);
+        }
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - mediaUris count: ${mediaUris.length}`);
+        // Get session context
+        logger.log(`[UPLOAD_PHOTO_TOOL] 🔍 Attempting to get session context...`);
+        const sessionContext = getCurrentSessionContext();
+        if (!sessionContext) {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ FAILED: No active session found!`);
+            logger.error(`[UPLOAD_PHOTO_TOOL]   - toolCallId: ${toolCallId}`);
+            throw new Error("No active XY session found. Upload photo tool can only be used during an active conversation.");
+        }
+        logger.log(`[UPLOAD_PHOTO_TOOL] ✅ Session context found`);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - sessionId: ${sessionContext.sessionId}`);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - taskId: ${sessionContext.taskId}`);
+        logger.log(`[UPLOAD_PHOTO_TOOL]   - messageId: ${sessionContext.messageId}`);
+        const { config, sessionId, taskId, messageId } = sessionContext;
+        // Get WebSocket manager
+        logger.log(`[UPLOAD_PHOTO_TOOL] 🔌 Getting WebSocket manager...`);
+        const wsManager = getXYWebSocketManager(config);
+        logger.log(`[UPLOAD_PHOTO_TOOL] ✅ WebSocket manager obtained`);
+        // Get public URLs for the photos
+        logger.log(`[UPLOAD_PHOTO_TOOL] 🌐 Getting public URLs for photos...`);
+        const imageUrls = await getPhotoUrls(wsManager, config, sessionId, taskId, messageId, mediaUris);
+        logger.log(`[UPLOAD_PHOTO_TOOL] 🎉 Successfully retrieved ${imageUrls.length} photo URLs`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        imageUrls,
+                        count: imageUrls.length,
+                        message: `成功获取 ${imageUrls.length} 张照片的公网访问 URL`
+                    }),
+                },
+            ],
+        };
+    },
+};
+/**
+ * Get public URLs for photos using mediaUris
+ * Returns array of publicly accessible image URLs
+ */
+async function getPhotoUrls(wsManager, config, sessionId, taskId, messageId, mediaUris) {
+    logger.log(`[UPLOAD_PHOTO_TOOL] 📦 Building ImageUploadForClaw command...`);
+    // Build imageInfos array from mediaUris
+    const imageInfos = mediaUris.map(mediaUri => ({ mediaUri }));
+    const command = {
+        header: {
+            namespace: "Common",
+            name: "Action",
+        },
+        payload: {
+            cardParam: {},
+            executeParam: {
+                executeMode: "background",
+                intentName: "ImageUploadForClaw",
+                bundleName: "com.huawei.hmos.vassistant",
+                needUnlock: true,
+                actionResponse: true,
+                appType: "OHOS_APP",
+                timeOut: 5,
+                intentParam: {
+                    imageInfos: imageInfos,
+                },
+                permissionId: [],
+                achieveType: "INTENT",
+            },
+            responses: [
+                {
+                    resultCode: "",
+                    displayText: "",
+                    ttsText: "",
+                },
+            ],
+            needUploadResult: true,
+            noHalfPage: false,
+            pageControlRelated: false,
+        },
+    };
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ⏰ Timeout: No response for ImageUploadForClaw within 60 seconds`);
+            wsManager.off("data-event", handler);
+            reject(new Error("获取照片URL超时（60秒）"));
+        }, 60000);
+        const handler = (event) => {
+            logger.log(`[UPLOAD_PHOTO_TOOL] 📨 Received data event:`, JSON.stringify(event));
+            if (event.intentName === "ImageUploadForClaw") {
+                logger.log(`[UPLOAD_PHOTO_TOOL] 🎯 ImageUploadForClaw event received`);
+                logger.log(`[UPLOAD_PHOTO_TOOL]   - status: ${event.status}`);
+                clearTimeout(timeout);
+                wsManager.off("data-event", handler);
+                if (event.status === "success" && event.outputs) {
+                    logger.log(`[UPLOAD_PHOTO_TOOL] ✅ Image URL retrieval completed successfully`);
+                    const result = event.outputs.result;
+                    let imageUrls = result?.imageUrls || [];
+                    // Decode Unicode escape sequences in URLs
+                    // Replace \u003d with = and \u0026 with &
+                    imageUrls = imageUrls.map((url) => {
+                        const decodedUrl = url
+                            .replace(/\\u003d/g, '=')
+                            .replace(/\\u0026/g, '&');
+                        logger.log(`[UPLOAD_PHOTO_TOOL] 🔄 Decoded URL: ${url} -> ${decodedUrl}`);
+                        return decodedUrl;
+                    });
+                    logger.log(`[UPLOAD_PHOTO_TOOL] 📊 Retrieved and decoded ${imageUrls.length} image URLs`);
+                    resolve(imageUrls);
+                }
+                else {
+                    logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Image URL retrieval failed`);
+                    logger.error(`[UPLOAD_PHOTO_TOOL]   - status: ${event.status}`);
+                    reject(new Error(`获取照片URL失败: ${event.status}`));
+                }
+            }
+        };
+        logger.log(`[UPLOAD_PHOTO_TOOL] 📡 Registering data-event handler for ImageUploadForClaw`);
+        wsManager.on("data-event", handler);
+        logger.log(`[UPLOAD_PHOTO_TOOL] 📤 Sending ImageUploadForClaw command...`);
+        sendCommand({
+            config,
+            sessionId,
+            taskId,
+            messageId,
+            command,
+        })
+            .then(() => {
+            logger.log(`[UPLOAD_PHOTO_TOOL] ✅ ImageUploadForClaw command sent successfully`);
+        })
+            .catch((error) => {
+            logger.error(`[UPLOAD_PHOTO_TOOL] ❌ Failed to send ImageUploadForClaw command:`, error);
+            clearTimeout(timeout);
+            wsManager.off("data-event", handler);
+            reject(error);
+        });
+    });
+}

package/dist/src/tools/xiaoyi-gui-tool.d.ts

@@ -0,0 +1,6 @@
+/**
+ * XiaoYi GUI tool - executes phone app interactions through GUI agent.
+ * Simulates user interactions on phone screen (click, swipe, input, navigation, etc.)
+ * to complete tasks that cannot be done through internet APIs.
+ */
+export declare const xiaoyiGuiTool: any;

package/dist/src/tools/xiaoyi-gui-tool.js

@@ -0,0 +1,151 @@
+// XiaoYi GUI tool implementation - simulates phone screen interactions
+import { getXYWebSocketManager } from "../client.js";
+import { sendCommand } from "../formatter.js";
+import { getCurrentSessionContext } from "./session-manager.js";
+import { logger } from "../utils/logger.js";
+/**
+ * XiaoYi GUI tool - executes phone app interactions through GUI agent.
+ * Simulates user interactions on phone screen (click, swipe, input, navigation, etc.)
+ * to complete tasks that cannot be done through internet APIs.
+ */
+export const xiaoyiGuiTool = {
+    name: "xiaoyi_gui_agent",
+    label: "XiaoYi GUI Agent",
+    description: `通过模拟人在手机屏幕上的交互行为（点击、滑动、输入、页面导航等），自动完成手机APP中的各类任务。
+
+该工具操作方式类似真实用户在手机上的操作，因此可以完成许多无法通过互联网API实现的任务，例如：
+- 任务需要真实操作手机APP界面
+- 数据仅存在于APP内部
+- 无法通过互联网API获取数据
+- 需要完成用户行为（签到、关注、购买等）
+- 需要在APP中发布或发送内容
+- 需要修改APP或手机设置
+
+注意事项：
+- 操作超时时间为3分钟（180秒）
+- 该工具执行时间较长，请勿重复调用
+- 该工具执行期间不要执行别的工具调用，必须等到该工具有结果返回或者超时之后才能执行别的操作，无论是新的文本回复还是下一步的工具调用，在此工具执行期间必须严格等待
+- 如果超时或失败，最多重试一次
+- 如果用户指令中包含备忘录读写，日程查看，不需要将这类操作放在gui tool的query参数中，需要使用预置的note相关工具与calendar相关工具完成相关操作`,
+    parameters: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "操作手机的指令以及期望返回的结果。",
+            },
+        },
+        required: ["query"],
+    },
+    async execute(toolCallId, params) {
+        logger.log(`[XIAOYI_GUI_TOOL] 🚀 Starting execution`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - toolCallId: ${toolCallId}`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - query: ${params.query}`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - timestamp: ${new Date().toISOString()}`);
+        // Validate parameters
+        if (!params.query || typeof params.query !== "string") {
+            logger.error(`[XIAOYI_GUI_TOOL] ❌ FAILED: Invalid query parameter`);
+            throw new Error("Missing or invalid required parameter: query must be a non-empty string");
+        }
+        // Get session context
+        logger.log(`[XIAOYI_GUI_TOOL] 🔍 Attempting to get session context...`);
+        const sessionContext = getCurrentSessionContext();
+        if (!sessionContext) {
+            logger.error(`[XIAOYI_GUI_TOOL] ❌ FAILED: No active session found!`);
+            logger.error(`[XIAOYI_GUI_TOOL]   - toolCallId: ${toolCallId}`);
+            throw new Error("No active XY session found. XiaoYi GUI tool can only be used during an active conversation.");
+        }
+        logger.log(`[XIAOYI_GUI_TOOL] ✅ Session context found`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - sessionId: ${sessionContext.sessionId}`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - taskId (interactionId): ${sessionContext.taskId}`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - messageId: ${sessionContext.messageId}`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - agentId: ${sessionContext.agentId}`);
+        const { config, sessionId, taskId, messageId } = sessionContext;
+        // Get WebSocket manager
+        logger.log(`[XIAOYI_GUI_TOOL] 🔌 Getting WebSocket manager...`);
+        const wsManager = getXYWebSocketManager(config);
+        logger.log(`[XIAOYI_GUI_TOOL] ✅ WebSocket manager obtained`);
+        // Build InvokeJarvisGUIAgentRequest command
+        logger.log(`[XIAOYI_GUI_TOOL] 📦 Building InvokeJarvisGUIAgentRequest command...`);
+        const command = {
+            header: {
+                namespace: "ClawAgent",
+                name: "InvokeJarvisGUIAgentRequest",
+            },
+            payload: {
+                query: params.query,
+                sessionId: sessionId,
+                interactionId: taskId, // taskId corresponds to interactionId
+            },
+        };
+        logger.log(`[XIAOYI_GUI_TOOL] 📋 Command details:`, JSON.stringify(command, null, 2));
+        // Send command and wait for response (5 minute timeout)
+        logger.log(`[XIAOYI_GUI_TOOL] ⏳ Setting up promise to wait for GUI agent response...`);
+        logger.log(`[XIAOYI_GUI_TOOL]   - Timeout: 300 seconds (5 minutes)`);
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                logger.error(`[XIAOYI_GUI_TOOL] ⏰ Timeout: No response received within 300 seconds (5 minutes)`);
+                wsManager.off("gui-agent-response", handler);
+                reject(new Error("XiaoYi GUI Agent 操作超时（5分钟）"));
+            }, 180000); // 5 minutes timeout
+            // Listen for GUI agent response events
+            const handler = (event) => {
+                logger.log(`[XIAOYI_GUI_TOOL] 📨 Received event:`, JSON.stringify(event));
+                // Check if this is the InvokeJarvisGUIAgentResponse we're waiting for
+                if (event.header?.namespace === "ClawAgent" &&
+                    event.header?.name === "InvokeJarvisGUIAgentResponse") {
+                    logger.log(`[XIAOYI_GUI_TOOL] 🎯 InvokeJarvisGUIAgentResponse event received`);
+                    logger.log(`[XIAOYI_GUI_TOOL]   - isFinal: ${event.payload?.isFinal}`);
+                    // According to the spec, we only get one response (isFinal: true)
+                    if (event.payload?.isFinal === true) {
+                        clearTimeout(timeout);
+                        wsManager.off("gui-agent-response", handler);
+                        const streamContent = event.payload?.streamInfo?.streamContent;
+                        if (streamContent) {
+                            logger.log(`[XIAOYI_GUI_TOOL] ✅ GUI Agent operation completed successfully`);
+                            logger.log(`[XIAOYI_GUI_TOOL]   - streamContent: ${streamContent}`);
+                            resolve({
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: streamContent,
+                                    }
+                                ]
+                            });
+                        }
+                        else {
+                            logger.error(`[XIAOYI_GUI_TOOL] ❌ Response missing streamContent`);
+                            logger.error(`[XIAOYI_GUI_TOOL]   - payload:`, JSON.stringify(event.payload));
+                            reject(new Error("XiaoYi GUI Agent 响应格式错误：缺少 streamContent"));
+                        }
+                    }
+                    else if (event.payload?.isFinal === false) {
+                        // According to spec, we shouldn't get intermediate responses, but log if we do
+                        logger.log(`[XIAOYI_GUI_TOOL] 📝 Intermediate response received (isFinal: false), waiting for final...`);
+                    }
+                }
+            };
+            // Register event handler
+            // Note: The WebSocket manager needs to emit 'gui-agent-response' when receiving this type of response
+            logger.log(`[XIAOYI_GUI_TOOL] 📡 Registering gui-agent-response handler on WebSocket manager`);
+            wsManager.on("gui-agent-response", handler);
+            // Send the command
+            logger.log(`[XIAOYI_GUI_TOOL] 📤 Sending InvokeJarvisGUIAgentRequest command...`);
+            sendCommand({
+                config,
+                sessionId,
+                taskId,
+                messageId,
+                command,
+            }).then(() => {
+                logger.log(`[XIAOYI_GUI_TOOL] ✅ Command sent successfully, waiting for response...`);
+                logger.log(`[XIAOYI_GUI_TOOL]   - This may take up to 5 minutes depending on the task complexity`);
+            }).catch((error) => {
+                logger.error(`[XIAOYI_GUI_TOOL] ❌ Failed to send command:`, error);
+                clearTimeout(timeout);
+                wsManager.off("gui-agent-response", handler);
+                reject(error);
+            });
+        });
+    },
+};

package/dist/src/types.d.ts

@@ -75,7 +75,11 @@ export interface A2AArtifact {
     artifactId: string;
     parts: A2AArtifactPart[];
 }
-export type A2AArtifactPart = A2ATextPart | A2ADataPart | A2ACommandPart;
+export interface A2AReasoningTextPart {
+    kind: "reasoningText";
+    reasoningText: string;
+}
+export type A2AArtifactPart = A2ATextPart | A2ADataPart | A2ACommandPart | A2AReasoningTextPart;
 export interface A2ACommandPart {
     kind: "command";
     command: A2ACommand;
@@ -155,14 +159,6 @@ export interface FileUploadCompleteRequest {
 export interface FileUploadCompleteResponse {
     fileId: string;
 }
-export interface PushMessageRequest {
-    apiKey: string;
-    apiId: string;
-    pushId: string;
-    sessionId: string;
-    title: string;
-    content: string;
-}
 export type ServerIdentifier = "server1" | "server2";
 export interface SessionBinding {
     sessionId: string;

package/dist/src/utils/config-manager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Manages dynamic configuration updates that can change at runtime.
+ * Specifically handles pushId which can be updated per-session.
+ */
+declare class ConfigManager {
+    private sessionPushIds;
+    private globalPushId;
+    /**
+     * Update push ID for a specific session.
+     */
+    updatePushId(sessionId: string, pushId: string): void;
+    /**
+     * Get push ID for a session (falls back to global if not found).
+     */
+    getPushId(sessionId?: string): string | null;
+    /**
+     * Clear push ID for a session.
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Clear all cached push IDs.
+     */
+    clear(): void;
+}
+export declare const configManager: ConfigManager;
+export {};

package/dist/src/utils/config-manager.js

@@ -0,0 +1,56 @@
+// Dynamic configuration manager for runtime updates
+import { logger } from "./logger.js";
+/**
+ * Manages dynamic configuration updates that can change at runtime.
+ * Specifically handles pushId which can be updated per-session.
+ */
+class ConfigManager {
+    sessionPushIds = new Map();
+    globalPushId = null;
+    /**
+     * Update push ID for a specific session.
+     */
+    updatePushId(sessionId, pushId) {
+        if (!pushId) {
+            logger.warn(`[ConfigManager] Attempted to set empty pushId for session ${sessionId}`);
+            return;
+        }
+        const previous = this.sessionPushIds.get(sessionId);
+        if (previous !== pushId) {
+            logger.log(`[ConfigManager] ✨ Updated pushId for session ${sessionId}`);
+            logger.log(`[ConfigManager]   - Previous: ${previous ? previous.substring(0, 20) + '...' : 'none'}`);
+            logger.log(`[ConfigManager]   - New:      ${pushId.substring(0, 20)}...`);
+            logger.log(`[ConfigManager]   - Full new pushId: ${pushId}`);
+            this.sessionPushIds.set(sessionId, pushId);
+            this.globalPushId = pushId; // Also update global for backward compatibility
+        }
+    }
+    /**
+     * Get push ID for a session (falls back to global if not found).
+     */
+    getPushId(sessionId) {
+        if (sessionId) {
+            const sessionPushId = this.sessionPushIds.get(sessionId);
+            if (sessionPushId) {
+                return sessionPushId;
+            }
+        }
+        return this.globalPushId;
+    }
+    /**
+     * Clear push ID for a session.
+     */
+    clearSession(sessionId) {
+        this.sessionPushIds.delete(sessionId);
+        logger.debug(`[ConfigManager] Cleared pushId for session ${sessionId}`);
+    }
+    /**
+     * Clear all cached push IDs.
+     */
+    clear() {
+        this.sessionPushIds.clear();
+        this.globalPushId = null;
+        logger.debug(`[ConfigManager] Cleared all cached pushIds`);
+    }
+}
+export const configManager = new ConfigManager();

package/dist/src/websocket.d.ts

@@ -1,12 +1,39 @@
 import { EventEmitter } from "events";
 import type { RuntimeEnv } from "openclaw/plugin-sdk";
 import type { XYChannelConfig, OutboundWebSocketMessage } from "./types.js";
+/**
+ * Diagnostics for a single WebSocket connection
+ */
+export interface ConnectionDiagnostic {
+    exists: boolean;
+    readyState: string;
+    stateConnected: boolean;
+    stateReady: boolean;
+    reconnectAttempts: number;
+    lastHeartbeat: number;
+    heartbeatActive: boolean;
+    hasReconnectTimer: boolean;
+    listenerCount: number;
+    isOrphan: boolean;
+}
+/**
+ * Full diagnostics for WebSocket manager
+ */
+export interface ManagerDiagnostics {
+    cacheKey: string;
+    server1: ConnectionDiagnostic;
+    server2: ConnectionDiagnostic;
+    isShuttingDown: boolean;
+    totalEventListeners: number;
+}
 /**
  * Manages dual WebSocket connections to XY servers.
  * Implements session-to-server binding for message routing.
  *
  * Events:
  * - 'message': (message: A2AJsonRpcRequest, sessionId: string, serverId: ServerIdentifier) => void
+ * - 'data-event': (event: A2ADataEvent) => void
+ * - 'gui-agent-response': (event: any) => void
  * - 'connected': (serverId: ServerIdentifier) => void
  * - 'disconnected': (serverId: ServerIdentifier) => void
  * - 'error': (error: Error, serverId: ServerIdentifier) => void
@@ -26,7 +53,12 @@ export declare class XYWebSocketManager extends EventEmitter {
     private isShuttingDown;
     private log;
     private error;
+    private onHealthEvent?;
     constructor(config: XYChannelConfig, runtime?: RuntimeEnv);
+    /**
+     * Set health event callback to report activity to OpenClaw framework.
+     */
+    setHealthEventCallback(callback: () => void): void;
     /**
      * Check if config matches the current instance.
      */
@@ -48,6 +80,15 @@ export declare class XYWebSocketManager extends EventEmitter {
      * Check if at least one server is ready.
      */
     isReady(): boolean;
+    /**
+     * Get detailed connection diagnostics for monitoring and debugging.
+     * Helps identify orphan connections and connection leaks.
+     */
+    getConnectionDiagnostics(): ManagerDiagnostics;
+    /**
+     * Get diagnostic info for a single server connection.
+     */
+    private getServerDiagnostic;
     /**
      * Connect to a specific server.
      */