openclaw-openagent 1.0.1 → 1.0.2

package/dist/src/tim/client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TIM Client — SDK connection core
+ *
+ * Manages TIM SDK lifecycle: connect, disconnect, auto-reconnect.
+ * Emits 'message' events for incoming group chat messages.
+ * Emits 'reconnected' when auto-reconnect succeeds.
+ *
+ * Internal noise containment: all SDK calls wrapped in try/catch,
+ * known TIM noise errors logged at debug level.
+ */
+import './sdk-logger-init.js';
+import '../sdk/node-env/index.js';
+import TencentCloudChat from '../sdk/index.js';
+import { EventEmitter } from 'node:events';
+import type { TIMCredentials } from '../auth/verify.js';
+export interface RawPushMessage {
+    id: string;
+    channelId: string;
+    seq: number;
+    from: string;
+    nick: string;
+    text: string;
+    time: number;
+    mentionsMe: boolean;
+    source: 'push';
+}
+export declare class TIMClient extends EventEmitter {
+    private chat;
+    private _agentId;
+    private _credentials;
+    private _reconnecting;
+    private _ready;
+    get agentId(): string;
+    get isReady(): boolean;
+    get userSig(): string | null;
+    /**
+     * Connect to TIM SDK using verified credentials.
+     */
+    connect(credentials: TIMCredentials): Promise<void>;
+    /**
+     * Gracefully disconnect from TIM SDK.
+     */
+    disconnect(): Promise<void>;
+    private _messageHandler;
+    private _notReadyHandler;
+    private _kickedHandler;
+    private _registerListeners;
+    private _removeListeners;
+    private _autoReconnect;
+    /** @internal */
+    get _chat(): ReturnType<typeof TencentCloudChat.create> | null;
+    /** @internal */
+    get _types(): typeof TencentCloudChat.TYPES;
+}

package/dist/src/tim/client.js

@@ -0,0 +1,268 @@
+/**
+ * TIM Client — SDK connection core
+ *
+ * Manages TIM SDK lifecycle: connect, disconnect, auto-reconnect.
+ * Emits 'message' events for incoming group chat messages.
+ * Emits 'reconnected' when auto-reconnect succeeds.
+ *
+ * Internal noise containment: all SDK calls wrapped in try/catch,
+ * known TIM noise errors logged at debug level.
+ */
+import './sdk-logger-init.js'; // Must be before @tencentcloud/chat — redirects SDK logs to file
+// @ts-ignore — JS side-effect module, no types needed
+import '../sdk/node-env/index.js'; // Must be before @tencentcloud/chat — installs ws (no permessage-deflate), localStorage, rejection handler
+import TencentCloudChat from '../sdk/index.js';
+// @ts-ignore — vendor JS module, typed as unknown
+import GroupModule from '../sdk/modules/group-module.js';
+// @ts-ignore — vendor JS module, patched for Node.js
+import TIMUploadPlugin from '../sdk/modules/tim-upload-plugin.js';
+import { EventEmitter } from 'node:events';
+import { logger } from '../util/logger.js';
+// ── TIMClient ──
+export class TIMClient extends EventEmitter {
+    chat = null;
+    _agentId = '';
+    _credentials = null;
+    _reconnecting = false;
+    _ready = false;
+    get agentId() { return this._agentId; }
+    get isReady() { return this._ready; }
+    get userSig() { return this._credentials?.userSig ?? null; }
+    /**
+     * Connect to TIM SDK using verified credentials.
+     */
+    async connect(credentials) {
+        this._agentId = credentials.userId;
+        this._credentials = credentials;
+        logger.info(`[tim/client] Connecting agentId=${this._agentId}`);
+        // Create SDK instance
+        this.chat = TencentCloudChat.create({
+            SDKAppID: credentials.sdkAppId,
+            modules: { 'group-module': GroupModule },
+        });
+        this.chat.setLogLevel(0); // ALL logs — WebSocket heartbeat, transport, message push (P0-A diagnosis)
+        // Register tim-upload-plugin — enables createFileMessage/sendMessage for T4 file transfer
+        // Must be after create(), before login(). SDK_READY triggers UploadModule._init() which looks up this plugin.
+        // @see docs/audit/023-tim-upload-plugin-v1.md §4.7
+        this.chat.registerPlugin({ 'tim-upload-plugin': TIMUploadPlugin });
+        logger.info('[tim/client] tim-upload-plugin registered');
+        // Wait for SDK_READY with guaranteed timer cleanup
+        let readyTimeout;
+        const sdkReadyPromise = new Promise((resolve, reject) => {
+            readyTimeout = setTimeout(() => reject(new Error('SDK_READY timeout (15s)')), 15_000);
+            this.chat.on(TencentCloudChat.EVENT.SDK_READY, () => {
+                clearTimeout(readyTimeout);
+                this._ready = true;
+                resolve();
+            });
+        });
+        // Register event listeners
+        this._registerListeners();
+        logger.info('[tim/client] Calling TIM SDK login...');
+        try {
+            await this.chat.login({
+                userID: credentials.userId,
+                userSig: credentials.userSig,
+            });
+            await sdkReadyPromise;
+        }
+        catch (err) {
+            clearTimeout(readyTimeout);
+            this._ready = false;
+            throw err;
+        }
+        logger.info('[tim/client] SDK_READY — connected');
+    }
+    /**
+     * Gracefully disconnect from TIM SDK.
+     */
+    async disconnect() {
+        this._reconnecting = false;
+        if (this.chat) {
+            try {
+                await this.chat.logout();
+            }
+            catch { /* ignore */ }
+            this._ready = false;
+            this._removeListeners();
+            this.chat = null;
+        }
+    }
+    // ── Event Listeners ──
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _messageHandler = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _notReadyHandler = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _kickedHandler = null;
+    _registerListeners() {
+        if (!this.chat) {
+            logger.error('[tim/client] _registerListeners: chat instance is null, cannot register');
+            return;
+        }
+        logger.info('[tim/client] _registerListeners: installing SDK event handlers');
+        // Disconnect detection
+        this._notReadyHandler = () => {
+            logger.warn('[tim/client] SDK_NOT_READY — connection lost');
+            this._ready = false;
+            void this._autoReconnect();
+        };
+        this.chat.on(TencentCloudChat.EVENT.SDK_NOT_READY, this._notReadyHandler);
+        this._kickedHandler = (event) => {
+            const ev = event;
+            const reason = ev?.data?.type || 'unknown';
+            logger.warn(`[tim/client] KICKED_OUT (reason=${reason})`);
+            this._ready = false;
+            switch (reason) {
+                case 'multipleDevice':
+                case 'multipleAccount':
+                    // Multi-device/page kick: do NOT reconnect to avoid kick loop
+                    logger.warn('[tim/client] Kicked by multi-device/account login, will not reconnect');
+                    break;
+                case 'userSigExpired':
+                    // UserSig expired: old credentials are useless, notify upper layer
+                    logger.warn('[tim/client] UserSig expired, emitting credential_expired event');
+                    this.emit('credential_expired');
+                    break;
+                case 'REST_API_Kick':
+                default:
+                    // REST API kick or unknown: reconnect with existing credentials
+                    void this._autoReconnect();
+                    break;
+            }
+        };
+        this.chat.on(TencentCloudChat.EVENT.KICKED_OUT, this._kickedHandler);
+        // Push message listener
+        this._messageHandler = (event) => {
+            const ev = event;
+            const messages = ev.data;
+            logger.info(`[tim/client] MESSAGE_RECEIVED fired: ${messages?.length ?? 0} message(s)`);
+            if (!messages || messages.length === 0) {
+                logger.warn('[tim/client] MESSAGE_RECEIVED: empty data array, nothing to process');
+                return;
+            }
+            for (const msg of messages) {
+                try {
+                    // ── C2C messages → emit for c2c.ts handler, skip group logic ──
+                    if (msg.conversationType === TencentCloudChat.TYPES.CONV_C2C) {
+                        logger.info(`[tim/client] C2C msg from=${msg.from}`);
+                        this.emit('c2c_message', {
+                            from: msg.from,
+                            payload: msg.payload,
+                            type: msg.type,
+                            time: msg.time,
+                        });
+                        continue;
+                    }
+                    // Only group messages
+                    if (msg.conversationType !== TencentCloudChat.TYPES.CONV_GROUP) {
+                        logger.debug(`[tim/client] skip non-group msg type=${msg.conversationType} from=${msg.from}`);
+                        continue;
+                    }
+                    // Skip own messages
+                    if (msg.from === this._agentId) {
+                        logger.debug(`[tim/client] skip self msg from=${msg.from} to=${msg.to}`);
+                        continue;
+                    }
+                    const text = msg.payload?.text || '';
+                    if (!text) {
+                        logger.debug(`[tim/client] skip empty text msg from=${msg.from} to=${msg.to}`);
+                        continue;
+                    }
+                    const channelId = msg.to;
+                    const seq = msg.sequence;
+                    const rawMessage = {
+                        id: `${channelId}:${seq}`,
+                        channelId,
+                        seq,
+                        from: msg.from,
+                        nick: msg.nick || msg.from,
+                        text,
+                        time: msg.time * 1000,
+                        mentionsMe: Array.isArray(msg.atUserList)
+                            && (msg.atUserList.includes(this._agentId)
+                                || msg.atUserList.includes(TencentCloudChat.TYPES.MSG_AT_ALL)),
+                        source: 'push',
+                    };
+                    logger.debug(`[tim/client] PUSH msg id=${rawMessage.id} ch=${channelId} from=${rawMessage.nick}`);
+                    this.emit('message', rawMessage);
+                }
+                catch (err) {
+                    logger.debug(`[tim/client] Error processing push message: ${err.message}`);
+                }
+            }
+        };
+        this.chat.on(TencentCloudChat.EVENT.MESSAGE_RECEIVED, this._messageHandler);
+    }
+    _removeListeners() {
+        if (!this.chat)
+            return;
+        if (this._notReadyHandler) {
+            this.chat.off(TencentCloudChat.EVENT.SDK_NOT_READY, this._notReadyHandler);
+            this._notReadyHandler = null;
+        }
+        if (this._kickedHandler) {
+            this.chat.off(TencentCloudChat.EVENT.KICKED_OUT, this._kickedHandler);
+            this._kickedHandler = null;
+        }
+        if (this._messageHandler) {
+            this.chat.off(TencentCloudChat.EVENT.MESSAGE_RECEIVED, this._messageHandler);
+            this._messageHandler = null;
+        }
+    }
+    // ── Auto-reconnect ──
+    async _autoReconnect(maxRetries = 5) {
+        if (this._reconnecting) {
+            logger.debug('[tim/client] Reconnect already in progress');
+            return;
+        }
+        if (!this._credentials) {
+            logger.error('[tim/client] Cannot reconnect: missing credentials');
+            return;
+        }
+        this._reconnecting = true;
+        logger.warn('[tim/client] Starting auto-reconnect...');
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            if (!this._reconnecting) {
+                logger.info('[tim/client] Reconnect cancelled');
+                return;
+            }
+            const delay = Math.min(5000 * attempt, 25_000);
+            logger.info(`[tim/client] Reconnect attempt ${attempt}/${maxRetries} in ${delay / 1000}s...`);
+            await new Promise(r => setTimeout(r, delay));
+            try {
+                // Teardown old SDK instance
+                if (this.chat) {
+                    this._removeListeners();
+                    try {
+                        await this.chat.logout();
+                    }
+                    catch { /* ignore */ }
+                    this.chat = null;
+                }
+                this._ready = false;
+                await this.connect(this._credentials);
+                if (this._ready) {
+                    logger.info(`[tim/client] Auto-reconnect successful on attempt ${attempt}`);
+                    this._reconnecting = false;
+                    this.emit('reconnected');
+                    return;
+                }
+            }
+            catch (err) {
+                logger.error(`[tim/client] Reconnect attempt ${attempt}/${maxRetries} failed: ${err.message}`);
+            }
+        }
+        this._reconnecting = false;
+        logger.error(`[tim/client] All ${maxRetries} reconnect attempts failed`);
+    }
+    // ── Internal SDK access (for messages.ts and channels.ts) ──
+    /** @internal */
+    get _chat() {
+        return this.chat;
+    }
+    /** @internal */
+    get _types() {
+        return TencentCloudChat.TYPES;
+    }
+}

package/dist/src/tim/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * TIM — Module barrel export
+ */
+export { TIMClient, type RawPushMessage } from './client.js';
+export { sendMessage, fetchMessages, mapToHistoryMessage, type HistoryMessage, type SendResult } from './messages.js';
+export { listChannels, searchChannels, joinChannel, leaveChannel, getMembers, createChannel, getChannelSkill, setChannelSkill, type ChannelInfo, type MemberInfo, } from './channels.js';

package/dist/src/tim/index.js

@@ -0,0 +1,6 @@
+/**
+ * TIM — Module barrel export
+ */
+export { TIMClient } from './client.js';
+export { sendMessage, fetchMessages, mapToHistoryMessage } from './messages.js';
+export { listChannels, searchChannels, joinChannel, leaveChannel, getMembers, createChannel, getChannelSkill, setChannelSkill, } from './channels.js';

package/dist/src/tim/messages.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TIM Messages — Send and fetch messages via SDK
+ *
+ * v3: fetchMessages uses SDK getMessageList() instead of REST API.
+ * This fixes the v2 bug where non-admin accounts got empty results.
+ */
+import type { TIMClient } from './client.js';
+export interface HistoryMessage {
+    id: string;
+    from: string;
+    text: string;
+    time: number;
+    seq?: number;
+}
+export interface SendResult {
+    ok: boolean;
+    messageId: string;
+}
+/**
+ * Send a text message to a group channel.
+ * Includes a 10s local timeout to catch dead SDK connections.
+ *
+ * When atUserList is provided, uses TIM createTextAtMessage to set
+ * protocol-level @mentions (visible to receivers' atUserList detection).
+ * See: docs/audit/012-mention-mode-bot-to-bot-v3.4.4.md
+ */
+export declare function sendMessage(client: TIMClient, channelId: string, text: string, atUserList?: string[]): Promise<SendResult>;
+/**
+ * Fetch message history for a group channel using SDK getMessageList().
+ *
+ * v3 change: REST API → SDK getMessageList()
+ * - Filters non-text messages (system msgs, join/leave notifications)
+ * - Maps to HistoryMessage interface
+ * - seq from message.sequence (optional)
+ * - Works with normal user credentials (fixes v2 empty array bug)
+ */
+export declare function fetchMessages(client: TIMClient, channelId: string, count?: number): Promise<HistoryMessage[]>;
+/**
+ * Map a single SDK message to HistoryMessage interface.
+ * Exported for contract testing.
+ */
+export declare function mapToHistoryMessage(msg: {
+    ID?: string;
+    from?: string;
+    payload?: {
+        text?: string;
+    };
+    time?: number;
+    sequence?: number;
+}, channelId: string): HistoryMessage;

package/dist/src/tim/messages.js

@@ -0,0 +1,104 @@
+/**
+ * TIM Messages — Send and fetch messages via SDK
+ *
+ * v3: fetchMessages uses SDK getMessageList() instead of REST API.
+ * This fixes the v2 bug where non-admin accounts got empty results.
+ */
+import { logger } from '../util/logger.js';
+// ── Functions ──
+/**
+ * Send a text message to a group channel.
+ * Includes a 10s local timeout to catch dead SDK connections.
+ *
+ * When atUserList is provided, uses TIM createTextAtMessage to set
+ * protocol-level @mentions (visible to receivers' atUserList detection).
+ * See: docs/audit/012-mention-mode-bot-to-bot-v3.4.4.md
+ */
+export async function sendMessage(client, channelId, text, atUserList) {
+    const chat = client._chat;
+    if (!chat || !client.isReady) {
+        throw new Error('Not connected');
+    }
+    logger.info(`[tim/messages] sendMessage: ch=${channelId} len=${text.length} at=${atUserList?.join(',') ?? 'none'}`);
+    const message = (atUserList && atUserList.length > 0)
+        ? chat.createTextAtMessage({
+            to: channelId,
+            conversationType: client._types.CONV_GROUP,
+            payload: { text, atUserList },
+        })
+        : chat.createTextMessage({
+            to: channelId,
+            conversationType: client._types.CONV_GROUP,
+            payload: { text },
+        });
+    // CRITICAL: Timer MUST be cleared after race settles.
+    // Without clearTimeout, a successful send leaves an orphan reject()
+    // firing 10s later as an unhandled rejection → gateway crash.
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(`sendMessage timeout (10s) for channel ${channelId}`)), 10_000);
+    });
+    try {
+        const res = await Promise.race([chat.sendMessage(message), timeoutPromise]);
+        return {
+            ok: true,
+            messageId: res.data?.message?.ID || '',
+        };
+    }
+    catch (err) {
+        const code = err?.code;
+        logger.error(`[tim/messages] sendMessage failed: code=${code} msg=${err.message} ch=${channelId}`);
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+/**
+ * Fetch message history for a group channel using SDK getMessageList().
+ *
+ * v3 change: REST API → SDK getMessageList()
+ * - Filters non-text messages (system msgs, join/leave notifications)
+ * - Maps to HistoryMessage interface
+ * - seq from message.sequence (optional)
+ * - Works with normal user credentials (fixes v2 empty array bug)
+ */
+export async function fetchMessages(client, channelId, count = 20) {
+    const chat = client._chat;
+    if (!chat || !client.isReady) {
+        throw new Error('Not connected');
+    }
+    try {
+        logger.info(`[tim/messages] fetchMessages: ch=${channelId} count=${count}`);
+        const conversationID = `GROUP${channelId}`;
+        const res = await chat.getMessageList({
+            conversationID,
+            count,
+        });
+        const messageList = res.data?.messageList || [];
+        // Filter to text messages only (exclude system messages, join/leave, etc.)
+        return messageList
+            .filter(msg => msg.type === client._types.MSG_TEXT)
+            .map(msg => mapToHistoryMessage(msg, channelId));
+    }
+    catch (err) {
+        logger.error(`[tim/messages] fetchMessages error for ${channelId}: ${err.message}`);
+        throw err;
+    }
+}
+/**
+ * Map a single SDK message to HistoryMessage interface.
+ * Exported for contract testing.
+ */
+export function mapToHistoryMessage(msg, channelId) {
+    const result = {
+        id: msg.ID || `${channelId}:${msg.sequence || Date.now()}`,
+        from: msg.from || 'unknown',
+        text: msg.payload?.text || '',
+        time: (msg.time || 0) * 1000,
+    };
+    if (msg.sequence != null) {
+        result.seq = msg.sequence;
+    }
+    return result;
+}

package/dist/src/tim/sdk-logger-init.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TIM SDK Logger Bridge — 副作用模块
+ *
+ * 将腾讯云 IM SDK 的内部日志输出重定向到 OpenAgent 的 logger 组件。
+ * SDK 内部原本直接调用 console.log/warn/error，此模块通过
+ * globalThis.__OPENAGENT_SDK_LOGGER 注入自定义 logger 适配器，
+ * 使 SDK 日志走文件输出而非 stdout，避免污染 Gateway JSON 通道。
+ *
+ * 必须在 @tencentcloud/chat 之前 import（副作用 import）：
+ *   import './sdk-logger-init.js';
+ *   import TencentCloudChat from '@tencentcloud/chat';
+ */
+export {};

package/dist/src/tim/sdk-logger-init.js

@@ -0,0 +1,46 @@
+/**
+ * TIM SDK Logger Bridge — 副作用模块
+ *
+ * 将腾讯云 IM SDK 的内部日志输出重定向到 OpenAgent 的 logger 组件。
+ * SDK 内部原本直接调用 console.log/warn/error，此模块通过
+ * globalThis.__OPENAGENT_SDK_LOGGER 注入自定义 logger 适配器，
+ * 使 SDK 日志走文件输出而非 stdout，避免污染 Gateway JSON 通道。
+ *
+ * 必须在 @tencentcloud/chat 之前 import（副作用 import）：
+ *   import './sdk-logger-init.js';
+ *   import TencentCloudChat from '@tencentcloud/chat';
+ */
+// node-polyfill.js removed — SDK now uses native Node.js APIs directly
+import { logger } from '../util/logger.js';
+function formatArgs(...args) {
+    return args
+        .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
+        .join(' ');
+}
+/**
+ * SDK 内部 logger（变量 qe/Ye）期望的接口：
+ *   qe.log(...)   — 普通日志
+ *   qe.warn(...)  — 警告
+ *   qe.error(...) — 错误
+ *   qe.info(...)  — 信息
+ *   qe.debug(...) — 调试
+ */
+const sdkLoggerAdapter = {
+    log(...args) {
+        logger.debug(`[tim-sdk] ${formatArgs(...args)}`);
+    },
+    warn(...args) {
+        logger.warn(`[tim-sdk] ${formatArgs(...args)}`);
+    },
+    error(...args) {
+        logger.error(`[tim-sdk] ${formatArgs(...args)}`);
+    },
+    info(...args) {
+        logger.info(`[tim-sdk] ${formatArgs(...args)}`);
+    },
+    debug(...args) {
+        logger.debug(`[tim-sdk] ${formatArgs(...args)}`);
+    },
+};
+// 注入到 globalThis，SDK 加载时会检查此变量
+globalThis.__OPENAGENT_SDK_LOGGER = sdkLoggerAdapter;

package/dist/src/tools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAgent Tools — re-export from app/ module
+ *
+ * This file exists for backward compatibility.
+ * The actual tool implementations live in app/channel-tools.ts,
+ * app/messaging-tools.ts, and app/ops-tools.ts.
+ */
+export { registerTools } from './app/index.js';
+export type { ToolDescriptor, ToolFactory } from './app/types.js';

package/dist/src/tools.js

@@ -0,0 +1,8 @@
+/**
+ * OpenAgent Tools — re-export from app/ module
+ *
+ * This file exists for backward compatibility.
+ * The actual tool implementations live in app/channel-tools.ts,
+ * app/messaging-tools.ts, and app/ops-tools.ts.
+ */
+export { registerTools } from './app/index.js';

package/dist/src/transport/factory.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Transport 工厂 —— 按配置创建 AgentTransport 实例
+ *
+ * 设计依据：docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.1
+ *
+ * 调用方（AccountRuntime）通过 transportType 字段决定走 OASN 还是 TIM 路径，
+ * 工厂内部 lazy-import 各自的实现模块，确保「未启用的 transport 不进入运行时」。
+ *   - 选 OASN 时不加载 TIM SDK（节省启动内存 & 避免无意义的 WebSocket 探测）
+ *   - 选 TIM  时不加载 OASN HTTP 客户端（更小的攻击面）
+ *
+ * 注意：transport 实例创建后必须显式调用 ready(credentials) 才能使用，
+ * 工厂只负责实例化，不负责凭证校验和连接。
+ */
+import type { AgentTransport } from './types.js';
+import type { PendingInvocationStore } from './oasn/index.js';
+/** 工厂入参 */
+export interface CreateTransportOptions {
+    /** 选择的 transport 类型 */
+    transportType: 'oasn' | 'tim';
+    /**
+     * OASN API base URL（仅 OASN 路径必填）。
+     * 形如：`https://api.oasn.ai`，不含尾斜杠和 `/api/*` 前缀。
+     */
+    apiBase?: string;
+    /** Optional Access-layer API base URL for invocation/file/artifact endpoints. */
+    accessApiBase?: string;
+    /**
+     * Agent id（仅 OASN 路径使用，TIM 路径从 credentials.userId 拿）。
+     * 用于实例标识 + 401 撤销时定位本地存储。
+     */
+    agentId?: string;
+    /**
+     * 多账户场景下的逻辑 id。
+     * 默认与 agentId 相同；当一个 OpenClaw 实例跑多个 OASN/TIM 账号时由调用方传入。
+     */
+    accountId?: string;
+    /**
+     * §11.1 OASN-only：把 SQLite-backed PendingInvocationStore 注入 OasnInvocation。
+     *
+     *   - 不传：OasnInvocation 退化为「无持久化」模式（idempotency 仍然在内存生效，但跨进程重启丢失）
+     *   - 传入：sendTask 时按 toolCallId 复用 idempotency_key，崩溃恢复时可由
+     *           StateStore.listUnsettledInvocations 续轮询
+     *
+     * 仅当 transportType='oasn' 时有意义；TIM 路径忽略此字段。
+     */
+    pendingStore?: PendingInvocationStore;
+}
+/**
+ * 创建 transport 实例。
+ *
+ * 关键设计：返回类型是 union `AgentTransport`，调用方需用 `transportType` 字段 narrow：
+ *
+ * ```ts
+ * const t = await createTransport({ transportType: 'oasn', apiBase, agentId });
+ * if (t.transportType === 'oasn') {
+ *   // 这里 TypeScript 知道 t 是 OasnTransport —— 可以调 t.registerAgent()
+ *   await t.registerAgent('openclaw');
+ * }
+ * ```
+ *
+ * @throws 当 OASN 路径但缺少 apiBase 时
+ */
+export declare function createTransport(options: CreateTransportOptions): Promise<AgentTransport>;