openclaw-openagent 1.0.0

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

@@ -0,0 +1,476 @@
+/**
+ * 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 { OasnTransport, TaskHandle, TaskRequest } from '../transport/types.js';
+import fs from 'node:fs';
+import nodePath from 'node:path';
+
+// ── 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();
+}
+
+function normalizeRemoteToolExecuteArgs(
+  signalOrUpdate?: AbortSignal | ToolUpdateCallback,
+  onUpdateOrContext?: ToolUpdateCallback | unknown,
+  legacySignal?: AbortSignal,
+): { signal?: AbortSignal; onUpdate?: ToolUpdateCallback; signature: string } {
+  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 as ToolUpdateCallback,
+      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(): 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="...",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',
+        },
+      },
+      required: ['agent_id', 'agent_name', 'task'],
+    },
+
+    async execute(
+      _id: unknown,
+      params: ToolParams,
+      signalOrUpdate?: AbortSignal | ToolUpdateCallback,
+      onUpdateOrContext?: ToolUpdateCallback | unknown,
+      legacySignal?: AbortSignal,
+    ): Promise<ToolResult> {
+      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 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();
+
+      // ② 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: 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 taskReq: TaskRequest = {
+          requestId,
+          task,
+          timeoutMs: OASN_INVOCATION_TIMEOUT_MS,
+          // mode='session' 时不在协议层 join 已有 session（OASN 默认每次起新 Invocation）。
+          // 上游若需要保留对话历史，请在 task 文本里显式带 session_id；
+          // 暂不在工具层做 session 续传，避免误用导致跨用户串号。
+        };
+
+        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 ?? '-'}`,
+        );
+
+        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 as Error).message}`,
+                );
+              }
+            }
+          }
+
+          // OASN 的非文本 artifacts 暂继续复用 ArtifactRef.contentUrl 作为 mediaUrls。
+          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: MEDIA: lines in text for Gateway MEDIA: parser + LLM echo
+        const mediaLines = httpMediaUrls
+          .map((url: string) => `MEDIA:${url}`)
+          .join('\n');
+        const textWithMedia = reply.content
+          ? `${reply.content}\n${mediaLines}`
+          : mediaLines;
+
+        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;
+}

package/src/app/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared tool types
+ *
+ * Return format aligned with OpenClaw SDK's AgentToolResult:
+ * @see https://docs.openclaw.ai (Plugin SDK → Building Plugins)
+ * @see docs/reference/openclaw/v2026.3.23/dist/plugin-sdk/src/agents/tools/common.d.ts
+ */
+
+export interface ToolParams {
+  [key: string]: unknown;
+}
+
+/** SDK-compatible tool result (matches AgentToolResult structure) */
+export interface ToolResult {
+  content: Array<{ type: 'text'; text: string }>;
+  /** Optional details for rich media. Matches OpenClaw AgentToolResult<TDetails>. */
+  details?: {
+    media?: { mediaUrls: string[] };
+    [key: string]: unknown;
+  };
+}
+
+export type ToolUpdateCallback = (partialResult: ToolResult) => void;
+
+export interface ToolDescriptor {
+  name: string;
+  label: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, {
+      type: string;
+      description: string;
+      enum?: string[];
+      default?: unknown;
+    }>;
+    required: string[];
+  };
+  /**
+   * Execute the tool.
+   *
+   * OpenClaw runtime usually calls:
+   *   tool.execute(toolCallId, params, signal, onUpdate)
+   *
+   * Older adapters used:
+   *   tool.execute(toolCallId, params, onUpdate, ctx, signal)
+   *
+   * The wider signature lets streaming tools normalize both shapes while
+   * existing 2-param tools continue to work unchanged.
+   *
+   * @see docs/reference/openclaw/v2026.3.23/dist/pi-embedded-CswW9luA.js L169823
+   */
+  execute: (
+    _id: unknown,
+    params: ToolParams,
+    signalOrUpdate?: AbortSignal | ToolUpdateCallback,
+    onUpdateOrContext?: ToolUpdateCallback | unknown,
+    legacySignal?: AbortSignal,
+  ) => Promise<ToolResult>;
+}
+
+export type ToolFactory = () => ToolDescriptor;
+
+/** Helper: create a successful text result in SDK format */
+export function toolResult(text: string): ToolResult {
+  return { content: [{ type: 'text', text }] };
+}