openclaw-openagent 1.0.13 → 1.0.14

package/src/app/discovery-tools.ts

@@ -1,273 +0,0 @@
-/**
- * Discovery Tools — Agent 搜索 / Agent 详情
- *
- * 封装 OASN DiscoveryTransport 能力为 LLM 可用工具。
- * 当前仅 OASN 模式可用；TIM 模式下工具返回明确错误。
- *
- * 设计依据：docs/specs/2026-06-21-oasn-agent-search-tool-wiring.md
- *
- * 工具列表：
- *   - openagent_search_agents    — 按关键词 / 分类 / 标签搜索 Agent
- *   - openagent_get_agent_detail  — 查看单个 Agent 详情
- *
- * 注：getCategories() 传输层能力保留给 Agent Book UI 使用，不暴露为 LLM 工具。
- */
-
-import { registry } from '../runtime/registry.js';
-import { logger } from '../util/logger.js';
-import {
-  toolResult,
-  type ToolDescriptor,
-  type ToolFactory,
-  type ToolParams,
-  type ToolResult,
-} from './types.js';
-import type { SearchQuery, AgentCard, OasnTransport } from '../transport/types.js';
-
-// ── Helpers ──
-
-function fail(error: string): ToolResult {
-  return toolResult(JSON.stringify({ success: false, error }));
-}
-
-/**
- * 从 AccountRuntime 获取 OASN transport 并 narrow 为 DiscoveryTransport。
- * 返回 { error: string } 表示不可用（未连接 / TIM 模式 / transport 未就绪）。
- */
-function getOasnDiscovery(): { error: string } | { transport: OasnTransport } {
-  const rt = registry.getDefault();
-  if (!rt || !rt.isRunning) return { error: 'OpenAgent runtime not running' };
-  if (rt.transportType !== 'oasn') {
-    return { error: 'Agent discovery is only available via OASN transport' };
-  }
-  const transport = rt.transport;
-  if (!transport || transport.transportType !== 'oasn') {
-    return { error: 'OASN transport not ready' };
-  }
-  // transportType check above guarantees OASN transport
-  return { transport: transport as OasnTransport };
-}
-
-/**
- * 将 AgentCard 转换为 LLM 友好的精简视图。
- * 去除内部字段（agent_type / visibility），保留用户关心的信息。
- */
-function agentCardToSummary(card: AgentCard) {
-  return {
-    agent_id: card.agent_id,
-    name: card.name,
-    description: card.description,
-    tags: card.tags?.map((t) => t.name) ?? [],
-    category: card.category,
-    avatar_url: card.avatar_url,
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════
-// 工具 1: openagent_search_agents
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 搜索可用 Agent。
- *
- * 三种搜索模式（互斥，按优先级）：
- *   1. query   — 自然语言搜索（POST /api/agent-cards/search/by-query）
- *   2. category — 分类浏览（POST /api/agent-cards/search/by-category）
- *   3. tags    — 标签筛选（POST /api/agent-cards/search/by-tags）
- *
- * LLM 使用场景：
- *   - 用户说"我想去旅行" → search_agents({ query: "旅行" })
- *   - 用户说"找个机票助手" → search_agents({ query: "机票" })
- *   - 用户说"看看有哪些旅行类 Agent" → search_agents({ category: ["travel"] })
- */
-export const createSearchAgentsTool: ToolFactory = () => ({
-  name: 'openagent_search_agents',
-  label: 'Search Available Agents',
-  description: [
-    'Search for available service agents by natural language query, category, or tags.',
-    'Use this tool when the user expresses an intent that might be handled by a specialist agent.',
-    'Examples:',
-    '  - "我想去旅行" → search_agents({ query: "旅行" })',
-    '  - "帮我查航班" → search_agents({ query: "机票" })',
-    '  - "有什么翻译助手" → search_agents({ query: "翻译" })',
-    'After finding agents, pick the most relevant one and call openagent_call_remote_agent with its agent_id.',
-    'At least one of query, category, or tags must be provided.',
-  ].join(' '),
-  parameters: {
-    type: 'object',
-    properties: {
-      query: {
-        type: 'string',
-        description: 'Natural language search query, e.g. "旅行" or "机票预订"',
-      },
-      category: {
-        type: 'string',
-        description: 'Category path to browse, e.g. "travel" or ["travel", "flights"]',
-      },
-      tags: {
-        type: 'string',
-        description: 'Comma-separated tag names to filter by, e.g. "机票,酒店"',
-      },
-      page_size: {
-        type: 'number',
-        description: 'Results per page (default 10, max 50)',
-        default: 10,
-      },
-      page_num: {
-        type: 'number',
-        description: 'Page number, 1-indexed (default 1)',
-        default: 1,
-      },
-    },
-    required: [],  // 至少提供一个: query / category / tags（运行时校验）
-  },
-
-  async execute(_id: unknown, params: ToolParams): Promise<ToolResult> {
-    logger.info(`[discovery-tools] search_agents called: ${JSON.stringify(params)}`);
-
-    // ① 获取 OASN transport
-    const discovery = getOasnDiscovery();
-    if ('error' in discovery) {
-      logger.warn(`[discovery-tools] search_agents unavailable: ${discovery.error}`);
-      return fail(discovery.error);
-    }
-
-    // ② 构造 SearchQuery
-    const searchQuery = buildSearchQuery(params);
-    if (!searchQuery.query && !searchQuery.category?.length && !searchQuery.tags?.length) {
-      return fail('At least one of query, category, or tags must be provided');
-    }
-
-    // ③ 调用 transport.searchAgents()
-    try {
-      const result = await discovery.transport.searchAgents(searchQuery);
-      logger.info(
-        `[discovery-tools] search_agents returned: searchId=${result.searchId} ` +
-        `count=${result.agentCards.length} hasNext=${result.hasNext}`,
-      );
-
-      return toolResult(JSON.stringify({
-        success: true,
-        search_id: result.searchId,
-        agents: result.agentCards.map(agentCardToSummary),
-        page: {
-          num: result.pageNum,
-          size: result.pageSize,
-          has_next: result.hasNext,
-        },
-      }, null, 2));
-    } catch (err) {
-      const msg = (err as Error).message;
-      logger.error(`[discovery-tools] search_agents failed: ${msg}`);
-      return fail(`Agent search failed: ${msg}`);
-    }
-  },
-});
-
-/**
- * 将工具参数转换为 SearchQuery。
- * 处理类型转换（string → string[]）和默认值。
- */
-function buildSearchQuery(params: ToolParams): SearchQuery {
-  const query: SearchQuery = {
-    agentTypes: ['service'],  // 只搜索 service 类型
-    pageSize: params.page_size ? Number(params.page_size) : 10,
-    pageNum: params.page_num ? Number(params.page_num) : 1,
-  };
-
-  // query: 自然语言搜索
-  if (params.query && typeof params.query === 'string') {
-    query.query = params.query.trim();
-  }
-
-  // category: 可能是 string 或 string[]
-  if (params.category) {
-    if (Array.isArray(params.category)) {
-      query.category = params.category.map(String);
-    } else if (typeof params.category === 'string') {
-      // 支持逗号分隔或单值
-      query.category = params.category.split(',').map((s) => s.trim()).filter(Boolean);
-    }
-  }
-
-  // tags: 可能是 string 或 string[]
-  if (params.tags) {
-    if (Array.isArray(params.tags)) {
-      query.tags = params.tags.map(String);
-    } else if (typeof params.tags === 'string') {
-      query.tags = params.tags.split(',').map((s) => s.trim()).filter(Boolean);
-    }
-  }
-
-  return query;
-}
-
-// ═══════════════════════════════════════════════════════════════
-// 工具 2: openagent_get_agent_detail
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 查看单个 Agent 详情。
- *
- * 在搜索结果中选择了一个 Agent 后，可以调用此工具获取完整信息（包括 MOM）。
- */
-export const createGetAgentDetailTool: ToolFactory = () => ({
-  name: 'openagent_get_agent_detail',
-  label: 'Get Agent Details',
-  description: [
-    'Get detailed information about a specific agent by its agent_id.',
-    'Use this after search_agents to see the full agent card including description and MOM (Model Operation Manual).',
-    'The MOM contains usage instructions for the agent.',
-  ].join(' '),
-  parameters: {
-    type: 'object',
-    properties: {
-      agent_id: {
-        type: 'string',
-        description: 'The agent_id to look up (from search_agents results)',
-      },
-    },
-    required: ['agent_id'],
-  },
-
-  async execute(_id: unknown, params: ToolParams): Promise<ToolResult> {
-    const agentId = String(params.agent_id || '').trim();
-    if (!agentId) {
-      return fail('agent_id is required');
-    }
-
-    logger.info(`[discovery-tools] get_agent_detail called: agent_id=${agentId}`);
-
-    const discovery = getOasnDiscovery();
-    if ('error' in discovery) {
-      return fail(discovery.error);
-    }
-
-    try {
-      const card = await discovery.transport.getAgent(agentId);
-
-      if (!card) {
-        return fail(`Agent not found: ${agentId}`);
-      }
-
-      logger.info(`[discovery-tools] get_agent_detail returned: name=${card.name}`);
-
-      return toolResult(JSON.stringify({
-        success: true,
-        agent: {
-          agent_id: card.agent_id,
-          name: card.name,
-          description: card.description,
-          MOM: card.MOM,
-          tags: card.tags?.map((t: { tag_id: string; name: string }) => t.name) ?? [],
-          category: card.category,
-          avatar_url: card.avatar_url,
-        },
-      }, null, 2));
-    } catch (err) {
-      const msg = (err as Error).message;
-      logger.error(`[discovery-tools] get_agent_detail failed: ${msg}`);
-      return fail(`Failed to get agent details: ${msg}`);
-    }
-  },
-});

package/src/app/download-file-tool.ts

@@ -1,133 +0,0 @@
-/**
- * Download File Tool — openagent_download_file
- *
- * Downloads an artifact returned by a remote OASN agent and saves it to local disk.
- *
- * API: GET /api/artifacts/{id}/content (access layer)
- * Ref: access-upload-download-api.md §3
- */
-
-import fs from 'node:fs';
-import nodePath from 'node:path';
-import { resolveOasnAccessUrl } from '../util/url-resolver.js';
-
-import { registry } from '../runtime/registry.js';
-import { logger } from '../util/logger.js';
-import {
-  toolResult,
-  type ToolDescriptor,
-  type ToolParams,
-  type ToolResult,
-} from './types.js';
-import type { OasnTransport } from '../transport/types.js';
-
-// ── Helpers ──
-
-function fail(error: string): ToolResult {
-  return toolResult(JSON.stringify({ success: false, error }));
-}
-
-function success(result: Record<string, unknown>): ToolResult {
-  return toolResult(JSON.stringify({ success: true, ...result }));
-}
-
-// ── Tool Factory ──
-
-export function createDownloadFileTool(): ToolDescriptor {
-  return {
-    name: 'openagent_download_file',
-    label: 'Download File',
-    description:
-      'Download an artifact file returned by a remote OASN agent and save it to disk. ' +
-      'Use this when a remote agent returns a file (PDF, image, document, etc.) ' +
-      'that the user wants to save locally. ' +
-      'The content_url comes from the remote agent\'s response artifacts. ' +
-      'Look for artifact URLs in the openagent_call_remote_agent result. ' +
-      'If the save_path parent directory does not exist it will be created automatically. ' +
-      'Existing files at save_path will be overwritten.',
-    parameters: {
-      type: 'object',
-      properties: {
-        content_url: {
-          type: 'string',
-          description:
-            'The artifact content URL from the remote agent result ' +
-            '(e.g., /api/artifacts/art_1/content?session_id=...&invocation_id=...)',
-        },
-        save_path: {
-          type: 'string',
-          description: 'Absolute local path where the file should be saved',
-        },
-      },
-      required: ['content_url', 'save_path'],
-    },
-
-    async execute(
-      _id: unknown,
-      params: ToolParams,
-    ): Promise<ToolResult> {
-      const contentUrl = String(params.content_url || '').trim();
-      const savePath = String(params.save_path || '').trim();
-
-      if (!contentUrl) {
-        return fail('content_url is required');
-      }
-      if (!savePath) {
-        return fail('save_path is required');
-      }
-      if (!nodePath.isAbsolute(savePath)) {
-        return fail('save_path must be an absolute path');
-      }
-
-      // ① Check runtime state
-      const rt = registry.getDefault();
-      if (!rt || !rt.isRunning) {
-        return fail('OpenAgent runtime not running');
-      }
-      if (rt.transportType !== 'oasn') {
-        return fail('File download is only available via OASN transport');
-      }
-      const transport = rt.transport;
-      if (!transport || transport.transportType !== 'oasn') {
-        return fail('OASN transport not ready');
-      }
-
-      // ② Resolve download URL
-      const accessBase = rt.config?.accessApiBase || rt.config?.apiBase;
-      const downloadUrl = resolveOasnAccessUrl(accessBase, contentUrl);
-
-      logger.info(
-        `[download-tool] Downloading artifact: url=${downloadUrl} saveTo=${savePath}`,
-      );
-
-      // ③ Download
-      const oasnTransport = transport as OasnTransport;
-      let downloaded;
-      try {
-        downloaded = await oasnTransport.downloadArtifact(downloadUrl);
-      } catch (err) {
-        logger.error(`[download-tool] Download failed: ${(err as Error).message}`);
-        return fail(`Download failed: ${(err as Error).message}`);
-      }
-
-      // ④ Save to disk
-      try {
-        fs.mkdirSync(nodePath.dirname(savePath), { recursive: true });
-        fs.writeFileSync(savePath, Buffer.from(downloaded.content));
-      } catch (err) {
-        return fail(`Cannot write to path: ${(err as Error).message}`);
-      }
-
-      logger.info(
-        `[download-tool] Download success: path=${savePath} size=${downloaded.content.byteLength}`,
-      );
-
-      return success({
-        savedPath: savePath,
-        sizeBytes: downloaded.content.byteLength,
-        mimeType: downloaded.mimeType,
-        displayName: downloaded.displayName,
-      });
-    },
-  };
-}

package/src/app/hooks.ts

@@ -1,144 +0,0 @@
-/**
- * Hooks — Scene + Purpose injection + Inline Image Offload
- *
- * Registers hooks with the OpenClaw API:
- *   1. before_prompt_build — injects channel-specific rules (skill) and agent purpose
- *   2. agent_turn_prepare  — offloads inline base64 images to ~/.openclaw/media/inbound/
- *                           so the model can reference them via media://inbound/<id>
- */
-
-import { registry } from '../runtime/registry.js';
-import { logger } from '../util/logger.js';
-
-interface HookEvent {
-  [key: string]: unknown;
-}
-
-interface HookContext {
-  sessionId?: string;
-  [key: string]: unknown;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyApi = any;
-
-/**
- * Register all OpenAgent hooks with OpenClaw API.
- */
-export function registerHooks(api: AnyApi): void {
-  // ── Hook 1: Scene + Purpose injection ──
-  api.registerHook('before_prompt_build', async (_event: HookEvent, ctx: HookContext) => {
-    // Only fire for openagent channel sessions
-    if (!ctx.sessionId?.startsWith('openagent:')) return {};
-
-    const channelId = ctx.sessionId.replace('openagent:', '');
-    const rt = registry.getDefault();
-    if (!rt) return {};
-
-    const parts: string[] = [];
-
-    // Inject channel rules (skill/scene)
-    try {
-      const rules = await rt.getChannelSkill(channelId);
-      if (rules) parts.push(`[SCENE: ${channelId}]\n${rules}\n[/SCENE]`);
-    } catch (err) {
-      logger.warn(`[hooks] rules fetch failed: ${(err as Error).message}`);
-    }
-
-    // Inject agent purpose for this channel
-    try {
-      const purpose = rt.store?.getPurpose(channelId);
-      if (purpose) parts.push(`[PURPOSE]\n${purpose}\n[/PURPOSE]`);
-    } catch (err) {
-      logger.warn(`[hooks] purpose fetch failed: ${(err as Error).message}`);
-    }
-
-    if (parts.length === 0) return {};
-
-    logger.debug(`[hooks] Injected Scene+Purpose for ${channelId}`);
-    return { appendSystemContext: parts.join('\n\n') };
-  }, { name: 'openagent-scene-purpose' });
-
-  // ── Hook 2: Inline image offload ──
-  //
-  // When a user uploads a file via Web UI and the model supports vision,
-  // images < 2MB are sent inline (base64 in the message content) and never
-  // saved to disk.  This hook intercepts those inline images via the llm_input
-  // event (fires for ALL agent sessions including embedded), extracts the
-  // base64 data, and writes it to ~/.openclaw/media/inbound/ via saveMediaBuffer.
-  //
-  // The model won't see a media://inbound/ URL in its prompt, but
-  // openagent_upload_file's auto-fallback (resolveLatestInboundFile) will
-  // pick up the most recently saved file automatically.
-  //
-  api.registerHook('llm_input', async (event: HookEvent) => {
-    const historyMessages = event.historyMessages as unknown[] | undefined;
-    if (!Array.isArray(historyMessages) || historyMessages.length === 0) return;
-
-    logger.info(
-      `[hooks] llm_input FIRED imagesCount=${event.imagesCount} historyMsgs=${historyMessages.length}`,
-    );
-
-    // Scan ALL messages (not just the last user message) for inline images
-    const MAX_BYTES = 20 * 1024 * 1024;
-    let savedCount = 0;
-
-    for (const msg of historyMessages as Record<string, unknown>[]) {
-      if (!msg || typeof msg !== 'object') continue;
-      const contentRaw = msg.content;
-      const contentBlocks: Record<string, unknown>[] = Array.isArray(contentRaw)
-        ? contentRaw as Record<string, unknown>[]
-        : [];
-
-      for (const block of contentBlocks) {
-        let base64: string | undefined;
-        let mimeType: string | undefined;
-
-        // Anthropic-style: { type: "image", source: { type: "base64", media_type: "...", data: "..." } }
-        if (block?.type === 'image') {
-          const source = block.source as Record<string, unknown> | undefined;
-          if (source?.type === 'base64' && typeof source.data === 'string') {
-            base64 = source.data;
-            mimeType = (source.media_type as string) || 'image/png';
-          }
-        }
-
-        // OpenAI-style: { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
-        if (!base64 && block?.type === 'image_url') {
-          const imageUrl = (block.image_url as Record<string, unknown> | undefined)?.url;
-          if (typeof imageUrl === 'string') {
-            const match = imageUrl.match(/^data:([^;]+);base64,(.+)$/);
-            if (match) {
-              mimeType = match[1]!;
-              base64 = match[2]!;
-            }
-          }
-        }
-
-        if (!base64) continue;
-
-        const buffer = Buffer.from(base64, 'base64');
-        const mime = mimeType || 'application/octet-stream';
-        const ext = mime.split('/')[1] || 'bin';
-
-        try {
-          const { saveMediaBuffer } = await import('openclaw/plugin-sdk/media-store');
-          const saved = await saveMediaBuffer(buffer, mime, 'inbound', MAX_BYTES, `webui-inline.${ext}`);
-          savedCount++;
-          logger.info(
-            `[hooks] Offloaded inline image: media://inbound/${saved.id} ` +
-            `size=${buffer.byteLength} mime=${mime}`,
-          );
-        } catch (err) {
-          logger.warn(
-            `[hooks] Failed to save inline image: ${(err as Error).message}`,
-          );
-        }
-      }
-    }
-
-    if (savedCount > 0) {
-      logger.info(`[hooks] llm_input saved ${savedCount} inline image(s) to media store`);
-    }
-  }, { name: 'openagent-inline-image-offload' });
-}

package/src/app/index.ts

@@ -1,84 +0,0 @@
-/**
- * App — Tool + Hook registration aggregator
- *
- * Registers all tools and hooks with the OpenClaw API.
- */
-
-import {
-  createListChannelsTool,
-  createSearchChannelsTool,
-  createJoinChannelTool,
-  createLeaveChannelTool,
-  createCreateChannelTool,
-  createGetMembersTool,
-  createSetChannelSkillTool,
-  createGetChannelSkillTool,
-} from './channel-tools.js';
-
-import {
-  createSendMessageTool,
-  createGetMessagesTool,
-} from './messaging-tools.js';
-
-import {
-  createSetStrategyTool,
-  createGetStatusTool,
-  createSetPurposeTool,
-  createGetPurposeTool,
-} from './ops-tools.js';
-
-import { createCallRemoteAgentTool } from './remote-agent-tool.js';
-import {
-  createSearchAgentsTool,
-  createGetAgentDetailTool,
-} from './discovery-tools.js';
-import { createUploadFileTool } from './upload-file-tool.js';
-import { createDownloadFileTool } from './download-file-tool.js';
-
-import { registerHooks } from './hooks.js';
-
-import type { ToolFactory } from './types.js';
-
-import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
-
-/**
- * Register all tools with OpenClaw API.
- */
-export function registerTools(api: OpenClawPluginApi): void {
-  // ── Channel management (8) — DORMANT: code preserved, not registered ──
-  // Uncomment to re-enable channel-based social networking features.
-  // api.registerTool(createListChannelsTool, { optional: false });
-  // api.registerTool(createSearchChannelsTool, { optional: false });
-  // api.registerTool(createJoinChannelTool, { optional: false });
-  // api.registerTool(createLeaveChannelTool, { optional: false });
-  // api.registerTool(createCreateChannelTool, { optional: false });
-  // api.registerTool(createGetMembersTool, { optional: false });
-  // api.registerTool(createSetChannelSkillTool, { optional: false });
-  // api.registerTool(createGetChannelSkillTool, { optional: false });
-
-  // ── Messaging (2) — DORMANT ──
-  // api.registerTool(createSendMessageTool, { optional: false });
-  // api.registerTool(createGetMessagesTool, { optional: false });
-
-  // ── Ops (4) — DORMANT ──
-  // api.registerTool(createSetStrategyTool, { optional: false });
-  // api.registerTool(createGetStatusTool, { optional: false });
-  // api.registerTool(createSetPurposeTool, { optional: false });
-  // api.registerTool(createGetPurposeTool, { optional: false });
-
-  // ── Remote Agent Orchestration (1) — ACTIVE ──
-  api.registerTool(createCallRemoteAgentTool, { optional: false });
-
-  // ── Agent Discovery (2) — ACTIVE (OASN-only) ──
-  // 搜索 / Agent 详情。TIM 模式下工具存在但返回明确错误。
-  // 注：getCategories() 传输层能力保留给 Agent Book UI 使用，不暴露为 LLM 工具。
-  api.registerTool(createSearchAgentsTool, { optional: false });
-  api.registerTool(createGetAgentDetailTool, { optional: false });
-
-  // ── File Upload / Download (2) — ACTIVE (OASN-only) ──
-  api.registerTool(createUploadFileTool, { optional: false });
-  api.registerTool(createDownloadFileTool, { optional: false });
-}
-
-export { registerHooks };
-export type { ToolDescriptor, ToolFactory } from './types.js';