openclaw-openagent 1.0.1 → 1.0.3

package/dist/src/app/ops-tools.js

@@ -0,0 +1,158 @@
+/**
+ * Ops Tools — 4 operational tools
+ *
+ * set_strategy, get_status, set_purpose, get_purpose
+ *
+ * Contract ref: §0.2 refactoring-plan.md
+ */
+import { registry } from '../runtime/registry.js';
+import { toolResult } from './types.js';
+function fail(error) {
+    return toolResult(JSON.stringify({ success: false, error }));
+}
+function getRuntime() {
+    const rt = registry.getDefault();
+    if (!rt || !rt.isRunning)
+        return null;
+    return rt;
+}
+export function createSetStrategyTool() {
+    return {
+        name: 'openagent_set_strategy',
+        label: 'Set Message Strategy',
+        description: 'Configure how you receive and respond to channel messages. Changes take effect immediately.',
+        parameters: {
+            type: 'object',
+            properties: {
+                batchWindowMs: { type: 'integer', description: 'How long to collect messages before processing (ms, default 20000)' },
+                maxBatchSize: { type: 'integer', description: 'Max messages to buffer before forced flush (default 20)' },
+            },
+            required: [],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt)
+                return fail('Not connected');
+            try {
+                const newConfig = {};
+                if (params?.batchWindowMs != null)
+                    newConfig.batchWindowMs = Number(params.batchWindowMs);
+                if (params?.maxBatchSize != null)
+                    newConfig.maxBatchSize = Number(params.maxBatchSize);
+                const current = rt.updateStrategy(newConfig);
+                return toolResult(JSON.stringify({
+                    success: true,
+                    batchWindowMs: current.batchWindowMs,
+                    maxBatchSize: current.maxBatchSize,
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+/**
+ * get_status — frozen return shape per §0.2:
+ *
+ * {
+ *   success, connected, agentId,
+ *   schedulerQueueSize, joinedChannels,
+ *   channels: [{ id, name, lastVisit, lastReply, lastMsgSeq }]
+ * }
+ */
+export function createGetStatusTool() {
+    return {
+        name: 'openagent_get_status',
+        label: 'Get OpenAgent Status',
+        description: 'Get current status of the OpenAgent connection and channel state',
+        parameters: { type: 'object', properties: {}, required: [] },
+        async execute() {
+            const rt = getRuntime();
+            if (!rt) {
+                return fail('OpenAgent is not running');
+            }
+            try {
+                const joined = rt.store?.getJoinedChannels() || [];
+                return toolResult(JSON.stringify({
+                    success: true,
+                    connected: rt.client?.isReady ?? false,
+                    agentId: rt.client?.agentId ?? '',
+                    schedulerQueueSize: rt.schedulerQueueSize,
+                    joinedChannels: joined.length,
+                    channels: joined.map((c) => ({
+                        id: c.channel_id,
+                        name: c.channel_name,
+                        lastVisit: c.last_visit ? new Date(c.last_visit).toISOString() : 'never',
+                        lastReply: c.last_reply ? new Date(c.last_reply).toISOString() : 'never',
+                        lastMsgSeq: c.last_msg_seq,
+                    })),
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createSetPurposeTool() {
+    return {
+        name: 'openagent_set_purpose',
+        label: 'Set Channel Purpose',
+        description: 'Set or update your purpose/goal for a channel',
+        parameters: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel ID' },
+                purpose: { type: 'string', description: 'Your purpose/goal for this channel' },
+            },
+            required: ['channelId', 'purpose'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt?.store)
+                return fail('Not connected');
+            try {
+                rt.store.setPurpose(String(params.channelId), String(params.purpose));
+                return toolResult(JSON.stringify({
+                    success: true,
+                    channelId: params.channelId,
+                    purpose: params.purpose,
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}
+export function createGetPurposeTool() {
+    return {
+        name: 'openagent_get_purpose',
+        label: 'Get Channel Purpose',
+        description: 'Get your current purpose/goal for a channel',
+        parameters: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel ID' },
+            },
+            required: ['channelId'],
+        },
+        async execute(_id, params) {
+            const rt = getRuntime();
+            if (!rt?.store)
+                return fail('Not connected');
+            try {
+                const purpose = rt.store.getPurpose(String(params.channelId));
+                return toolResult(JSON.stringify({
+                    success: true,
+                    channelId: params.channelId,
+                    purpose: purpose || '(no purpose set)',
+                }));
+            }
+            catch (err) {
+                return fail(err.message);
+            }
+        },
+    };
+}

package/dist/src/app/remote-agent-tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Remote Agent Tool — openagent_call_remote_agent / oasn_call_agent
+ *
+ * Calls a remote Agent through the active transport and streams results back.
+ * v3.9+ 双轨抽象：
+ *   - transport='tim'：保留原有 C2C 流程（sendC2CCustomMessage + waitForC2CReply）
+ *   - transport='oasn'：走 OASN HTTP API（transport.sendTask + waitForTaskResult），
+ *     toolCallId 透传给 OasnInvocation 触发 §11.1 idempotency_key 持久化复用
+ *
+ * Accepts both OpenClaw execute signatures seen in the wild:
+ *   modern: tool.execute(toolCallId, params, signal, onUpdate)
+ *   legacy: tool.execute(toolCallId, params, onUpdate, ctx, signal)
+ *
+ * @see docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.2 / §4.1
+ * @see docs/products/orchestrator/specs/T2-local-tool.md
+ */
+import { type ToolDescriptor } from './types.js';
+/**
+ * Create the openagent_call_remote_agent tool.
+ *
+ * Tool description instructs LLM to:
+ * - Detect {openagent:agent_id="...",agent_name="..."} markers in user messages
+ * - Extract agent_id from the marker
+ * - Pass user's natural language request as task parameter
+ * - NOT display the marker to the user
+ */
+export declare function createCallRemoteAgentTool(): ToolDescriptor;

package/dist/src/app/remote-agent-tool.js

@@ -0,0 +1,461 @@
+/**
+ * Remote Agent Tool — openagent_call_remote_agent / oasn_call_agent
+ *
+ * Calls a remote Agent through the active transport and streams results back.
+ * v3.9+ 双轨抽象：
+ *   - transport='tim'：保留原有 C2C 流程（sendC2CCustomMessage + waitForC2CReply）
+ *   - transport='oasn'：走 OASN HTTP API（transport.sendTask + waitForTaskResult），
+ *     toolCallId 透传给 OasnInvocation 触发 §11.1 idempotency_key 持久化复用
+ *
+ * Accepts both OpenClaw execute signatures seen in the wild:
+ *   modern: tool.execute(toolCallId, params, signal, onUpdate)
+ *   legacy: tool.execute(toolCallId, params, onUpdate, ctx, signal)
+ *
+ * @see docs/specs/2026-06-16-oasn-transport-abstraction-design.md §3.2 / §4.1
+ * @see docs/products/orchestrator/specs/T2-local-tool.md
+ */
+import { registry } from '../runtime/registry.js';
+import { logger } from '../util/logger.js';
+import { getGatewayBaseUrl } from '../proxy/auth-proxy.js';
+import { toolResult, } from './types.js';
+import { sendC2CCustomMessage, waitForC2CReply } from '../tim/c2c.js';
+import fs from 'node:fs';
+import nodePath from 'node:path';
+import { resolveOasnAccessUrl } from '../util/url-resolver.js';
+// ── Helpers ──
+function fail(error) {
+    return toolResult(JSON.stringify({ success: false, error }));
+}
+/**
+ * Generate request UUID.
+ * Aligned with OpenClaw subagent pattern (crypto.randomUUID).
+ */
+function generateRequestId() {
+    return crypto.randomUUID();
+}
+function isAbortSignalLike(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        'aborted' in value &&
+        typeof value.addEventListener === 'function');
+}
+function getObjectCallback(value, key) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value[key];
+    return typeof candidate === 'function' ? candidate : undefined;
+}
+function getObjectSignal(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value.signal;
+    return isAbortSignalLike(candidate) ? candidate : undefined;
+}
+function describeExecuteArg(value) {
+    if (typeof value === 'function')
+        return 'function';
+    if (isAbortSignalLike(value))
+        return 'AbortSignal';
+    if (value === null)
+        return 'null';
+    if (typeof value !== 'object')
+        return typeof value;
+    const ctor = value.constructor?.name;
+    const keys = Object.keys(value).slice(0, 8).join(',');
+    return `${ctor || 'object'}{${keys}}`;
+}
+function isTextArtifact(candidate) {
+    const mime = (candidate.mimeType || '').toLowerCase();
+    const name = (candidate.displayName || '').toLowerCase();
+    return mime.startsWith('text/')
+        || mime.includes('markdown')
+        || mime.includes('json')
+        || name.endsWith('.md')
+        || name.endsWith('.txt')
+        || name.endsWith('.json');
+}
+function artifactContentToText(content) {
+    return Buffer.from(content).toString('utf8').trim();
+}
+function normalizeRemoteToolExecuteArgs(signalOrUpdate, onUpdateOrContext, legacySignal) {
+    if (typeof signalOrUpdate === 'function') {
+        return {
+            onUpdate: signalOrUpdate,
+            signal: isAbortSignalLike(legacySignal)
+                ? legacySignal
+                : getObjectSignal(onUpdateOrContext),
+            signature: 'legacy:update-third',
+        };
+    }
+    if (typeof onUpdateOrContext === 'function') {
+        return {
+            signal: isAbortSignalLike(signalOrUpdate) ? signalOrUpdate : undefined,
+            onUpdate: onUpdateOrContext,
+            signature: 'modern:signal-update',
+        };
+    }
+    const nestedUpdate = getObjectCallback(onUpdateOrContext, 'onUpdate') ||
+        getObjectCallback(onUpdateOrContext, 'update') ||
+        getObjectCallback(onUpdateOrContext, 'onToolUpdate');
+    const nestedSignal = isAbortSignalLike(signalOrUpdate)
+        ? signalOrUpdate
+        : getObjectSignal(onUpdateOrContext) || (isAbortSignalLike(legacySignal) ? legacySignal : undefined);
+    return {
+        signal: nestedSignal,
+        onUpdate: nestedUpdate,
+        signature: nestedUpdate ? 'context:update-callback' : 'unknown:no-update',
+    };
+}
+// ── Tool Factory ──
+/**
+ * Create the openagent_call_remote_agent tool.
+ *
+ * Tool description instructs LLM to:
+ * - Detect {openagent:agent_id="...",agent_name="..."} markers in user messages
+ * - Extract agent_id from the marker
+ * - Pass user's natural language request as task parameter
+ * - NOT display the marker to the user
+ */
+export function createCallRemoteAgentTool() {
+    return {
+        name: 'openagent_call_remote_agent',
+        label: 'Call Remote Agent',
+        description: 'Route a user request to a remote specialist Agent via the OpenAgent network. ' +
+            'TRIGGER: When the user message contains a {openagent_call_remote_agent:agent_id="...",agent_name="...",instruction="..."} marker, ' +
+            'call this tool to forward the request to the specified remote Agent. ' +
+            'Extract agent_id and agent_name from the marker; use the remaining natural-language text as the task parameter. ' +
+            'Do not display the raw marker to the user. ' +
+            'mode "session" (default) preserves remote conversation history; mode "run" starts fresh — include full context in task.',
+        parameters: {
+            type: 'object',
+            properties: {
+                agent_id: {
+                    type: 'string',
+                    description: 'Remote Agent UUID. Extract from the {openagent_call_remote_agent:agent_id="..."} marker in the user message.',
+                },
+                agent_name: {
+                    type: 'string',
+                    description: 'Display name of the remote Agent from the marker. Use this in your reply to the user.',
+                },
+                task: {
+                    type: 'string',
+                    description: 'The user\'s natural-language request text, excluding the marker.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['session', 'run'],
+                    description: '"session" (default): preserves remote conversation history. ' +
+                        '"run": stateless — task must contain full context.',
+                    default: 'session',
+                },
+                input_file_refs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional OASN file_ref strings from openagent_upload_file. ' +
+                        'The remote agent will receive these files as inputs.',
+                },
+            },
+            required: ['agent_id', 'agent_name', 'task'],
+        },
+        async execute(_id, params, signalOrUpdate, onUpdateOrContext, legacySignal) {
+            const { signal, onUpdate, signature } = normalizeRemoteToolExecuteArgs(signalOrUpdate, onUpdateOrContext, legacySignal);
+            logger.info(`[remote-tool] Execute args: toolCallId=${String(_id)} signature=${signature} ` +
+                `hasSignal=${Boolean(signal)} hasOnUpdate=${Boolean(onUpdate)} ` +
+                `third=${describeExecuteArg(signalOrUpdate)} fourth=${describeExecuteArg(onUpdateOrContext)} ` +
+                `fifth=${describeExecuteArg(legacySignal)}`);
+            // ① Check runtime (same pattern as messaging-tools.ts)
+            const rt = registry.getDefault();
+            if (!rt || !rt.isRunning) {
+                logger.warn('[remote-tool] OpenAgent runtime not running');
+                return fail('OpenAgent not connected');
+            }
+            // ② Ensure TIM connected (supports lazy connect from half-alive mode)
+            try {
+                await rt.ensureConnected();
+            }
+            catch (connErr) {
+                logger.error(`[remote-tool] ensureConnected failed: ${connErr.message}`);
+                return fail(`OpenAgent connection failed: ${connErr.message}`);
+            }
+            const agentId = String(params.agent_id || '').trim();
+            const task = String(params.task || '').trim();
+            const mode = String(params.mode || 'session').trim();
+            // ② Validate required params
+            if (!agentId) {
+                logger.warn('[remote-tool] Missing agent_id parameter');
+                return fail('agent_id is required');
+            }
+            if (!task) {
+                logger.warn('[remote-tool] Missing task parameter');
+                return fail('task is required');
+            }
+            // ③ Generate requestId
+            // 这里的 requestId 同时承担两个职责（v3.9+ 双轨语义）：
+            //   - TIM 路径：作为 C2C 关联 id（sendC2CCustomMessage 的 request_id 字段）
+            //   - OASN 路径：作为 toolCallId 透传给 OasnInvocation —— §11.1 用它去 SQLite
+            //     里查/写 idempotency_key + invocation_id，进程崩溃重启后可由
+            //     listUnsettledInvocations() 续轮询，避免重复扣费
+            const requestId = generateRequestId();
+            const TIMEOUT_MS = 15 * 60 * 1000; // 15 分钟：远程 agent 可能跑长工具
+            const OASN_INVOCATION_TIMEOUT_MS = 60_000; // compute02 REL 当前允许的 ServiceAgent 执行预算
+            logger.info(`[remote-tool] Calling remote agent: agentId=${agentId} requestId=${requestId} ` +
+                `mode=${mode} transport=${rt.transportType}`);
+            // 进度回调适配器：两条路径共用一套桥接逻辑，统一把字符串内容包装成 ToolResult
+            const bridgeProgress = (content) => {
+                if (onUpdate) {
+                    try {
+                        onUpdate(toolResult(content));
+                    }
+                    catch (err) {
+                        logger.warn(`[remote-tool] onUpdate callback failed: ${err.message}`);
+                    }
+                }
+                logger.debug(`[remote-tool] Progress: requestId=${requestId} hasOnUpdate=${Boolean(onUpdate)} ` +
+                    `content=${content.slice(0, 80)}`);
+            };
+            // ④ 按 transport 分发 ——
+            //   - OASN：HTTP API 路径（sendTask + waitForTaskResult），无 C2C
+            //   - TIM ：保留原 C2C 流程（sendC2CCustomMessage + waitForC2CReply）
+            // 两条路径最终都返回相同形状的 reply，下方 ⑤ 统一处理 media + content。
+            let reply;
+            if (rt.transportType === 'oasn') {
+                // ── OASN 路径 ──
+                // 走 transport 抽象。注意 rt.transport 在 half-alive 时可能为 null，
+                // 上面 ensureConnected() 已尽量保证 ready，但仍要兜底，避免空指针。
+                const transport = rt.transport;
+                if (!transport || transport.transportType !== 'oasn') {
+                    logger.warn('[remote-tool] OASN transport unavailable after ensureConnected');
+                    return fail('OASN transport not ready');
+                }
+                const oasnTransport = transport;
+                try {
+                    rt.assertOasnInvocationAllowed();
+                }
+                catch (err) {
+                    logger.warn(`[remote-tool] OASN invocation blocked: ${err.message}`);
+                    return fail(err.message);
+                }
+                const inputFileRefs = Array.isArray(params.input_file_refs)
+                    ? params.input_file_refs.filter((r) => typeof r === 'string' && r.trim())
+                    : undefined;
+                const taskReq = {
+                    requestId,
+                    task,
+                    inputFileRefs: inputFileRefs?.length ? inputFileRefs : undefined,
+                    timeoutMs: OASN_INVOCATION_TIMEOUT_MS,
+                    // mode='session' 时不在协议层 join 已有 session（OASN 默认每次起新 Invocation）。
+                    // 上游若需要保留对话历史，请在 task 文本里显式带 session_id；
+                    // 暂不在工具层做 session 续传，避免误用导致跨用户串号。
+                };
+                let handle;
+                try {
+                    handle = await oasnTransport.sendTask(agentId, taskReq);
+                }
+                catch (err) {
+                    logger.error(`[remote-tool] OASN sendTask failed: ${err.message}`);
+                    return fail(`Failed to reach remote agent: ${err.message}`);
+                }
+                logger.info(`[remote-tool] OASN invocation created: invocationId=${handle.invocationId} ` +
+                    `sessionId=${handle.sessionId ?? '-'} effectiveTimeoutMs=${handle.effectiveTimeoutMs ?? '-'}`);
+                try {
+                    const result = await oasnTransport.waitForTaskResult(handle, {
+                        timeoutMs: TIMEOUT_MS,
+                        signal,
+                        onProgress: (p) => bridgeProgress(p.content),
+                    });
+                    const artifacts = result.artifacts ?? [];
+                    let content = result.content;
+                    let mediaUrls = artifacts.map((a) => a.contentUrl).filter(Boolean);
+                    if (!content.trim()) {
+                        for (const textArtifact of artifacts) {
+                            if (!textArtifact.contentUrl && !textArtifact.contentAvailable)
+                                continue;
+                            try {
+                                const downloaded = await oasnTransport.downloadArtifact(textArtifact.contentUrl || textArtifact.id);
+                                if (isTextArtifact(downloaded)) {
+                                    content = artifactContentToText(downloaded.content);
+                                    mediaUrls = artifacts
+                                        .filter((a) => a.id !== textArtifact.id)
+                                        .map((a) => a.contentUrl)
+                                        .filter(Boolean);
+                                    break;
+                                }
+                            }
+                            catch (err) {
+                                logger.warn(`[remote-tool] Failed to hydrate OASN text artifact ${textArtifact.id}: ${err.message}`);
+                            }
+                        }
+                    }
+                    // WebUI continuation：声明了 webui 能力的 ServiceAgent 在 succeeded 后会
+                    // 在 visible_result.webui_continuation 里返回可继续交互的入口。
+                    if (result.webuiContinuation?.launchUrl) {
+                        const rawLink = result.webuiContinuation.launchUrl;
+                        const accessBase = rt.config?.accessApiBase;
+                        const link = resolveOasnAccessUrl(accessBase, rawLink);
+                        const label = result.webuiContinuation.displayName || 'Open WebUI';
+                        content = content.trim()
+                            ? `${content}\n\n${label}: ${link}`
+                            : `${label}: ${link}`;
+                        logger.info(`[remote-tool] OASN webui continuation: id=${result.webuiContinuation.id} ` +
+                            `state=${result.webuiContinuation.visibleState} link=${link}`);
+                    }
+                    // Non-text artifacts: expose content_url so the LLM can pass them to
+                    // openagent_download_file to save files locally.
+                    const nonTextArtifacts = artifacts.filter((a) => {
+                        if (!a.contentUrl)
+                            return false;
+                        // already inlined as text → skip
+                        if (!content.includes(a.contentUrl))
+                            return true;
+                        return false;
+                    });
+                    if (nonTextArtifacts.length > 0) {
+                        const artifactLines = nonTextArtifacts.map((a) => `- ${a.displayName || 'file'}: ${a.contentUrl}`);
+                        content = content.trim()
+                            ? `${content}\n\nFiles from remote agent (use openagent_download_file to save):\n${artifactLines.join('\n')}`
+                            : `Files from remote agent:\n${artifactLines.join('\n')}`;
+                    }
+                    // OASN 的非文本 artifacts 暂继续复用 ArtifactRef.contentUrl 作为 mediaUrls。
+                    reply = {
+                        status: 'complete',
+                        content,
+                        mediaUrls,
+                    };
+                }
+                catch (err) {
+                    const msg = err.message;
+                    logger.error(`[remote-tool] OASN waitForTaskResult failed: ${msg}`);
+                    if (msg.includes('timeout'))
+                        return fail(`Remote agent did not respond within ${TIMEOUT_MS / 1000}s`);
+                    if (msg.includes('aborted') || msg.includes('abort'))
+                        return fail('Request was cancelled');
+                    return fail(`Remote agent communication error: ${msg}`);
+                }
+            }
+            else {
+                // ── TIM 路径（保留原逻辑） ──
+                try {
+                    await sendC2CCustomMessage(agentId, {
+                        type: 'openagent_task_request',
+                        request_id: requestId,
+                        task,
+                        session_mode: mode,
+                    });
+                }
+                catch (err) {
+                    logger.error(`[remote-tool] Failed to send C2C request: ${err.message}`);
+                    return fail(`Failed to reach remote agent: ${err.message}`);
+                }
+                try {
+                    const c2cReply = await waitForC2CReply(requestId, {
+                        timeoutMs: TIMEOUT_MS,
+                        signal,
+                        onProgress: bridgeProgress,
+                    });
+                    logger.info(`[remote-tool] Reply received: requestId=${requestId} status=${c2cReply.status}`);
+                    reply = {
+                        status: c2cReply.status,
+                        content: c2cReply.content,
+                        mediaUrls: c2cReply.mediaUrls,
+                    };
+                }
+                catch (err) {
+                    const msg = err.message;
+                    logger.error(`[remote-tool] waitForC2CReply failed: ${msg}`);
+                    if (msg.includes('timeout'))
+                        return fail(`Remote agent did not respond within ${TIMEOUT_MS / 1000}s`);
+                    if (msg.includes('aborted'))
+                        return fail('Request was cancelled');
+                    return fail(`Remote agent communication error: ${msg}`);
+                }
+            }
+            // ⑤ 统一结果处理（两路径汇合） ──
+            // 错误已在 ④ 内分支里各自捕获并 fail()；此处只处理"成功 reply"的数据装配。
+            if (reply.status === 'error') {
+                return fail(`Remote agent error: ${reply.content}`);
+            }
+            // T4: Include media files from remote file transfer.
+            // Dual-path delivery for cross-version compatibility:
+            //   1. MEDIA: lines in text  → parsed by Gateway on ALL versions (v2026.3.x+)
+            //   2. details.media         → native rendering on v2026.4.11+
+            //
+            // TIM 路径下 mediaUrls 是本地落盘绝对路径 → 走 plugin HTTP route 代理；
+            // OASN 路径下 mediaUrls 是 ArtifactRef.contentUrl（远程 https），暂直接透出。
+            // 后续若 OASN 引入本地缓存策略，可在 ④ 内提前 downloadArtifact 后再走代理路径。
+            if (reply.mediaUrls && reply.mediaUrls.length > 0) {
+                logger.info(`[remote-tool] Reply includes ${reply.mediaUrls.length} file(s)`);
+                const isOasnRemoteUrl = reply.mediaUrls.every((u) => /^https?:\/\//i.test(u));
+                let httpMediaUrls;
+                if (isOasnRemoteUrl) {
+                    // OASN 已是 https URL，直接透出，不走 plugin HTTP route
+                    httpMediaUrls = reply.mediaUrls;
+                }
+                else {
+                    // TIM 路径：本地路径 → 代理 URL，并尝试安装 trip-card-data.json
+                    installTripCardDataIfPresent(reply.mediaUrls);
+                    const baseUrl = getGatewayBaseUrl();
+                    httpMediaUrls = reply.mediaUrls.map((localPath) => {
+                        const fileName = localPath.split('/').pop() ?? 'file';
+                        return `${baseUrl}/plugins/openagent/media/${encodeURIComponent(fileName)}`;
+                    });
+                }
+                // Path 1: MEDIA: lines in text for Gateway MEDIA: parser + LLM echo
+                const mediaLines = httpMediaUrls
+                    .map((url) => `MEDIA:${url}`)
+                    .join('\n');
+                const textWithMedia = reply.content
+                    ? `${reply.content}\n${mediaLines}`
+                    : mediaLines;
+                return {
+                    content: [{ type: 'text', text: textWithMedia }],
+                    // Path 2: details.media for v2026.4.11+ native attachment rendering
+                    details: {
+                        count: httpMediaUrls.length,
+                        media: { mediaUrls: httpMediaUrls },
+                        paths: httpMediaUrls,
+                    },
+                };
+            }
+            return toolResult(reply.content);
+        },
+    };
+}
+function installTripCardDataIfPresent(mediaUrls) {
+    const tripDataPath = mediaUrls.find((localPath) => {
+        const fileName = nodePath.basename(localPath).toLowerCase();
+        return fileName.endsWith('trip-card-data.json') || fileName.endsWith('ctrip-card-data.json');
+    });
+    if (!tripDataPath)
+        return;
+    const controlUiDir = resolveControlUiDirForRuntime();
+    if (!controlUiDir) {
+        logger.warn(`[remote-tool] Trip card data received but control-ui directory was not found`);
+        return;
+    }
+    try {
+        const dest = nodePath.join(controlUiDir, 'trip-card-data.json');
+        fs.mkdirSync(nodePath.dirname(dest), { recursive: true });
+        fs.copyFileSync(tripDataPath, dest);
+        logger.info(`[remote-tool] Installed trip card data: ${tripDataPath} → ${dest}`);
+    }
+    catch (err) {
+        logger.warn(`[remote-tool] Failed to install trip card data: ${err.message}`);
+    }
+}
+function resolveControlUiDirForRuntime() {
+    const candidates = new Set();
+    const argvEntry = process.argv[1] || '';
+    if (argvEntry) {
+        candidates.add(nodePath.join(nodePath.dirname(argvEntry), 'control-ui'));
+    }
+    candidates.add(nodePath.join(process.cwd(), 'dist', 'control-ui'));
+    candidates.add('/app/dist/control-ui');
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(nodePath.join(candidate, 'index.html')))
+                return candidate;
+        }
+        catch { }
+    }
+    return null;
+}