openclaw-openagent 1.0.13 → 1.0.14

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

@@ -1,762 +0,0 @@
-/**
- * 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,
-  type ToolDescriptor,
-  type ToolParams,
-  type ToolResult,
-  type ToolUpdateCallback,
-} from './types.js';
-import { sendC2CCustomMessage, waitForC2CReply } from '../tim/c2c.js';
-import type { ArtifactRef, OasnTransport, TaskHandle, TaskRequest } from '../transport/types.js';
-import fs from 'node:fs';
-import nodePath from 'node:path';
-import { resolveOasnAccessUrl, resolveOasnWebuiUrl } from '../util/url-resolver.js';
-
-// ── Helpers ──
-
-function fail(error: string): ToolResult {
-  return toolResult(JSON.stringify({ success: false, error }));
-}
-
-/**
- * Generate request UUID.
- * Aligned with OpenClaw subagent pattern (crypto.randomUUID).
- */
-function generateRequestId(): string {
-  return crypto.randomUUID();
-}
-
-function isAbortSignalLike(value: unknown): value is AbortSignal {
-  return Boolean(
-    value &&
-      typeof value === 'object' &&
-      'aborted' in value &&
-      typeof (value as { addEventListener?: unknown }).addEventListener === 'function',
-  );
-}
-
-function getObjectCallback(value: unknown, key: string): ToolUpdateCallback | undefined {
-  if (!value || typeof value !== 'object') return undefined;
-  const candidate = (value as Record<string, unknown>)[key];
-  return typeof candidate === 'function' ? candidate as ToolUpdateCallback : undefined;
-}
-
-function getObjectSignal(value: unknown): AbortSignal | undefined {
-  if (!value || typeof value !== 'object') return undefined;
-  const candidate = (value as Record<string, unknown>).signal;
-  return isAbortSignalLike(candidate) ? candidate : undefined;
-}
-
-function describeExecuteArg(value: unknown): string {
-  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 as { constructor?: { name?: string } }).constructor?.name;
-  const keys = Object.keys(value as Record<string, unknown>).slice(0, 8).join(',');
-  return `${ctor || 'object'}{${keys}}`;
-}
-
-function isTextArtifact(candidate: { displayName?: string; mimeType?: string }): boolean {
-  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: ArrayBuffer): string {
-  return Buffer.from(content).toString('utf8').trim();
-}
-
-const OPENAGENT_MEDIA_DIR = '/tmp/openclaw/openagent-media';
-
-const EXT_BY_MIME: Record<string, string> = {
-  'application/json': '.json',
-  'text/markdown': '.md',
-  'text/plain': '.txt',
-  'application/pdf': '.pdf',
-  'image/png': '.png',
-  'image/jpeg': '.jpg',
-  'image/gif': '.gif',
-  'image/webp': '.webp',
-  'application/zip': '.zip',
-  'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
-};
-
-function sanitizeMediaFileName(name: string): string {
-  const base = nodePath.basename(name || 'artifact');
-  return base
-    .replace(/[\0\r\n]/g, '')
-    .replace(/[/:\\]/g, '_')
-    .replace(/^\.+$/, 'artifact')
-    .slice(0, 180) || 'artifact';
-}
-
-function inferExtension(buffer: Buffer, mimeType: string): string {
-  const mime = mimeType.split(';')[0]?.trim().toLowerCase() || '';
-  const byMime = EXT_BY_MIME[mime];
-  if (byMime) return byMime;
-
-  if (buffer.subarray(0, 2).toString('latin1') === 'PK') {
-    const zipNames = buffer.toString('latin1');
-    if (zipNames.includes('[Content_Types].xml') && zipNames.includes('ppt/')) return '.pptx';
-    if (zipNames.includes('[Content_Types].xml') && zipNames.includes('word/')) return '.docx';
-    if (zipNames.includes('[Content_Types].xml') && zipNames.includes('xl/')) return '.xlsx';
-    return '.zip';
-  }
-
-  if (buffer.subarray(0, 4).toString('latin1') === '%PDF') return '.pdf';
-  if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return '.png';
-  if (buffer.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff]))) return '.jpg';
-  return '.bin';
-}
-
-function buildOasnMediaFileName(artifact: ArtifactRef, buffer: Buffer, downloadedName: string, downloadedMime: string): string {
-  const preferredName = downloadedName && downloadedName !== 'artifact'
-    ? downloadedName
-    : artifact.displayName && artifact.displayName !== 'artifact'
-      ? artifact.displayName
-      : artifact.id || 'artifact';
-
-  let safeName = sanitizeMediaFileName(preferredName);
-  if (!nodePath.extname(safeName)) {
-    safeName += inferExtension(buffer, downloadedMime || artifact.mimeType);
-  }
-  return safeName;
-}
-
-async function cacheOasnArtifactsForMedia(
-  oasnTransport: OasnTransport,
-  artifacts: ArtifactRef[],
-): Promise<string[]> {
-  const localPaths: string[] = [];
-
-  for (const artifact of artifacts) {
-    const ref = artifact.contentUrl || artifact.id;
-    if (!ref) continue;
-
-    try {
-      const downloaded = await oasnTransport.downloadArtifact(ref);
-      const buffer = Buffer.from(downloaded.content);
-      const fileName = buildOasnMediaFileName(
-        artifact,
-        buffer,
-        downloaded.displayName,
-        downloaded.mimeType,
-      );
-      const filePath = nodePath.join(OPENAGENT_MEDIA_DIR, fileName);
-      fs.mkdirSync(nodePath.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, buffer);
-      localPaths.push(filePath);
-      logger.info(
-        `[remote-tool] Cached OASN artifact for media: id=${artifact.id} file=${filePath} size=${buffer.byteLength}`,
-      );
-    } catch (err) {
-      logger.warn(
-        `[remote-tool] Failed to cache OASN artifact ${artifact.id || ref}: ${(err as Error).message}`,
-      );
-    }
-  }
-
-  return localPaths;
-}
-
-function mediaDownloadLabel(url: string): string {
-  let fileName = 'artifact';
-  try {
-    fileName = decodeURIComponent(new URL(url).pathname.split('/').pop() || fileName);
-  } catch {
-    fileName = decodeURIComponent(url.split('?')[0]?.split('/').pop() || fileName);
-  }
-  return sanitizeMediaFileName(fileName).replace(/[[\]\r\n]/g, ' ') || 'artifact';
-}
-
-function formatMediaDownloadLines(urls: string[]): string {
-  const lines = urls
-    .filter((url) => typeof url === 'string' && url.trim())
-    .map((url) => `- [${mediaDownloadLabel(url)}](${url})`);
-  return lines.length ? `下载链接:\n${lines.join('\n')}` : '';
-}
-
-function normalizeRemoteToolExecuteArgs(
-  signalOrUpdate?: AbortSignal | ToolUpdateCallback,
-  onUpdateOrContext?: ToolUpdateCallback | unknown,
-  contextOrSignal?: unknown,
-): { signal?: AbortSignal; onUpdate?: ToolUpdateCallback; context?: unknown; signature: string } {
-  const contextCandidate = (value: unknown): unknown | undefined => {
-    if (!value || typeof value !== 'object' || isAbortSignalLike(value)) return undefined;
-    return value;
-  };
-
-  if (typeof signalOrUpdate === 'function') {
-    return {
-      onUpdate: signalOrUpdate,
-      signal: isAbortSignalLike(contextOrSignal)
-        ? contextOrSignal
-        : getObjectSignal(onUpdateOrContext),
-      context: contextCandidate(onUpdateOrContext),
-      signature: 'legacy:update-third',
-    };
-  }
-
-  if (typeof onUpdateOrContext === 'function') {
-    return {
-      signal: isAbortSignalLike(signalOrUpdate) ? signalOrUpdate : undefined,
-      onUpdate: onUpdateOrContext as ToolUpdateCallback,
-      context: contextCandidate(contextOrSignal),
-      signature: contextCandidate(contextOrSignal) ? 'modern:signal-update-context' : 'modern:signal-update',
-    };
-  }
-
-  const nestedUpdate =
-    getObjectCallback(onUpdateOrContext, 'onUpdate') ||
-    getObjectCallback(onUpdateOrContext, 'update') ||
-    getObjectCallback(onUpdateOrContext, 'onToolUpdate');
-  const nestedSignal =
-    isAbortSignalLike(signalOrUpdate)
-      ? signalOrUpdate
-      : getObjectSignal(onUpdateOrContext) || (isAbortSignalLike(contextOrSignal) ? contextOrSignal : undefined);
-
-  return {
-    signal: nestedSignal,
-    onUpdate: nestedUpdate,
-    context: contextCandidate(contextOrSignal) || contextCandidate(onUpdateOrContext),
-    signature: nestedUpdate ? 'context:update-callback' : 'unknown:no-update',
-  };
-}
-
-function readNonEmptyString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
-}
-
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
-}
-
-function callStringGetter(target: unknown, methodName: string): string | undefined {
-  const record = readRecord(target);
-  const fn = record?.[methodName];
-  if (typeof fn !== 'function') return undefined;
-  try {
-    return readNonEmptyString(fn.call(target));
-  } catch {
-    return undefined;
-  }
-}
-
-function readNestedString(root: unknown, path: string[]): string | undefined {
-  let cur: unknown = root;
-  for (const key of path) {
-    const record = readRecord(cur);
-    if (!record) return undefined;
-    cur = record[key];
-  }
-  return readNonEmptyString(cur);
-}
-
-function resolveOpenclawSessionKey(context: unknown): string | undefined {
-  const ctx = readRecord(context);
-  if (!ctx) return undefined;
-
-  const sessionManager = ctx.sessionManager;
-  const managerSessionId = callStringGetter(sessionManager, 'getSessionId');
-  if (managerSessionId) return `session:${managerSessionId}`;
-
-  const directSessionId =
-    readNonEmptyString(ctx.sessionId) ||
-    readNonEmptyString(ctx.openclawSessionId) ||
-    readNonEmptyString(ctx.agentSessionId) ||
-    readNestedString(ctx, ['session', 'sessionId']);
-  if (directSessionId) return `session:${directSessionId}`;
-
-  const sessionFile =
-    callStringGetter(sessionManager, 'getSessionFile') ||
-    readNestedString(ctx, ['session', 'sessionFile']);
-  if (sessionFile) return `file:${sessionFile}`;
-
-  return undefined;
-}
-
-function getRememberedRemoteSessionId(
-  runtime: { store?: { getRemoteAgentSession?: (openclawSessionKey: string, targetAgentId: string) => string | null } | null },
-  openclawSessionKey: string | undefined,
-  agentId: string,
-): string | undefined {
-  if (!openclawSessionKey) return undefined;
-  try {
-    return runtime.store?.getRemoteAgentSession?.(openclawSessionKey, agentId) || undefined;
-  } catch (err) {
-    logger.warn(`[remote-tool] Failed to read remembered OASN session: ${(err as Error).message}`);
-    return undefined;
-  }
-}
-
-function rememberRemoteSessionId(
-  runtime: {
-    store?: {
-      upsertRemoteAgentSession?: (record: {
-        openclaw_session_key: string;
-        target_agent_id: string;
-        session_id: string;
-      }) => void;
-    } | null;
-  },
-  openclawSessionKey: string | undefined,
-  agentId: string,
-  sessionId: string | undefined,
-): void {
-  if (!openclawSessionKey || !sessionId) return;
-  try {
-    runtime.store?.upsertRemoteAgentSession?.({
-      openclaw_session_key: openclawSessionKey,
-      target_agent_id: agentId,
-      session_id: sessionId,
-    });
-  } catch (err) {
-    logger.warn(`[remote-tool] Failed to remember OASN session: ${(err as Error).message}`);
-  }
-}
-
-// ── 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(): ToolDescriptor {
-  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="...",agent_bio="...",instruction="..."} marker, ' +
-      'call this tool to forward the request to the specified remote Agent. ' +
-      'Extract agent_id, agent_name, and optional agent_bio 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.',
-        },
-        agent_bio: {
-          type: 'string',
-          description: 'Short description of the remote Agent from the marker. Preserve it for UI display.',
-        },
-        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: unknown,
-      params: ToolParams,
-      signalOrUpdate?: AbortSignal | ToolUpdateCallback,
-      onUpdateOrContext?: ToolUpdateCallback | unknown,
-      contextOrSignal?: unknown,
-    ): Promise<ToolResult> {
-      const { signal, onUpdate, context, signature } = normalizeRemoteToolExecuteArgs(
-        signalOrUpdate,
-        onUpdateOrContext,
-        contextOrSignal,
-      );
-      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(contextOrSignal)}`,
-      );
-
-      // ① 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 as Error).message}`);
-        return fail(`OpenAgent connection failed: ${(connErr as Error).message}`);
-      }
-
-      const agentId = String(params.agent_id || '').trim();
-      const task = String(params.task || '').trim();
-      const mode = String(params.mode || 'session').trim() === 'run' ? 'run' : 'session';
-
-      // ② 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 = 24 * 60 * 60 * 1000; // 24 小时
-
-      logger.info(
-        `[remote-tool] Calling remote agent: agentId=${agentId} requestId=${requestId} ` +
-          `mode=${mode} transport=${rt.transportType}`,
-      );
-
-      // 进度回调适配器：两条路径共用一套桥接逻辑，统一把字符串内容包装成 ToolResult
-      const bridgeProgress = (content: string) => {
-        if (onUpdate) {
-          try {
-            onUpdate(toolResult(content));
-          } catch (err) {
-            logger.warn(`[remote-tool] onUpdate callback failed: ${(err as Error).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: { status: 'complete' | 'error'; content: string; mediaUrls?: string[] };
-
-      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 as OasnTransport;
-        try {
-          rt.assertOasnInvocationAllowed();
-        } catch (err) {
-          logger.warn(`[remote-tool] OASN invocation blocked: ${(err as Error).message}`);
-          return fail((err as Error).message);
-        }
-
-        const inputFileRefs: string[] | undefined = Array.isArray(params.input_file_refs)
-          ? (params.input_file_refs as string[]).filter((r: unknown) => typeof r === 'string' && r.trim())
-          : undefined;
-        const openclawSessionKey = resolveOpenclawSessionKey(context);
-        const rememberedSessionId = mode === 'session'
-          ? getRememberedRemoteSessionId(rt, openclawSessionKey, agentId)
-          : undefined;
-        if (mode === 'session' && !openclawSessionKey) {
-          logger.warn('[remote-tool] OASN session mode requested but OpenClaw session scope is unavailable');
-        }
-
-        const taskReq: TaskRequest = {
-          requestId,
-          task,
-          sessionId: rememberedSessionId,
-          inputFileRefs: inputFileRefs?.length ? inputFileRefs : undefined,
-          timeoutMs: OASN_INVOCATION_TIMEOUT_MS,
-        };
-
-        let handle: TaskHandle;
-        try {
-          handle = await oasnTransport.sendTask(agentId, taskReq);
-        } catch (err) {
-          logger.error(`[remote-tool] OASN sendTask failed: ${(err as Error).message}`);
-          return fail(`Failed to reach remote agent: ${(err as Error).message}`);
-        }
-        logger.info(
-          `[remote-tool] OASN invocation created: invocationId=${handle.invocationId} ` +
-            `sessionId=${handle.sessionId ?? '-'} effectiveTimeoutMs=${handle.effectiveTimeoutMs ?? '-'}`,
-        );
-        if (mode === 'session') {
-          rememberRemoteSessionId(rt, openclawSessionKey, agentId, handle.sessionId);
-        }
-
-        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: string[] = [];
-          if (mode === 'session') {
-            rememberRemoteSessionId(rt, openclawSessionKey, agentId, result.webuiContinuation?.sessionId);
-          }
-
-          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);
-                  break;
-                }
-              } catch (err) {
-                logger.warn(
-                  `[remote-tool] Failed to hydrate OASN text artifact ${textArtifact.id}: ${(err as Error).message}`,
-                );
-              }
-            }
-          }
-
-          // WebUI continuation：声明了 webui 能力的 ServiceAgent 在 succeeded 后会
-          // 在 visible_result.webui_continuation 里返回可继续交互的入口。
-          const accessBase = rt.config?.accessApiBase || rt.config?.apiBase;
-          if (result.webuiContinuation?.launchUrl) {
-            const rawLink = result.webuiContinuation.launchUrl;
-            const claimUrl = rt.config?.claimUrl;
-            const link = resolveOasnWebuiUrl(accessBase, claimUrl, 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')}`;
-          }
-
-          if (artifacts.length > 0) {
-            mediaUrls = await cacheOasnArtifactsForMedia(oasnTransport, artifacts);
-          }
-
-          // Resolve OASN-relative URLs in content (remote agent may have embedded
-          // /webui/continuations/... or /api/artifacts/... in its output text).
-          if (content && accessBase) {
-            content = content.replace(
-              /(?<![a-zA-Z0-9])(\/webui\/[^\s"')\]]+|\/api\/[^\s"')\]]+)/g,
-              (match) => resolveOasnAccessUrl(accessBase, match),
-            );
-          }
-
-          // OASN artifacts are cached locally before being handed to Gateway media rendering.
-          reply = {
-            status: 'complete',
-            content,
-            mediaUrls,
-          };
-        } catch (err) {
-          const msg = (err as Error).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 as Error).message}`);
-          return fail(`Failed to reach remote agent: ${(err as Error).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 as Error).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: string[];
-        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: string) => {
-            const fileName = localPath.split('/').pop() ?? 'file';
-            return `${baseUrl}/plugins/openagent/media/${encodeURIComponent(fileName)}`;
-          });
-        }
-
-        // Path 1: explicit markdown links + MEDIA: lines for Gateway parser.
-        // The markdown block makes the link visible even when the host does not
-        // render MEDIA: attachments in assistant/tool-result bubbles.
-        const downloadLines = formatMediaDownloadLines(httpMediaUrls);
-        const mediaLines = httpMediaUrls
-          .map((url: string) => `MEDIA:${url}`)
-          .join('\n');
-        const textWithMedia = [reply.content.trim(), downloadLines, mediaLines]
-          .filter(Boolean)
-          .join('\n\n');
-
-        return {
-          content: [{ type: 'text' as const, 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: string[]): void {
-  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 as Error).message}`);
-  }
-}
-
-function resolveControlUiDirForRuntime(): string | null {
-  const candidates = new Set<string>();
-  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;
-}