openclaw-openagent 1.0.1 → 1.0.3

package/dist/src/util/logger.js

@@ -0,0 +1,100 @@
+/**
+ * OpenAgent Plugin — Logger
+ *
+ * 统一日志模块，写入 OpenClaw 标准日志目录。
+ * 禁止在 Gateway 运行时使用任何 console 输出。
+ *
+ * 级别控制优先级：环境变量 > 默认 DEBUG（产品发布后改为 INFO）
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
+// ── 常量 ──
+const LOG_DIR = resolvePreferredOpenClawTmpDir();
+const SUBSYSTEM = "gateway/channels/openagent";
+const HOSTNAME = os.hostname() || "unknown";
+const LEVEL_IDS = {
+    TRACE: 1,
+    DEBUG: 2,
+    INFO: 3,
+    WARN: 4,
+    ERROR: 5,
+    FATAL: 6,
+};
+const DEFAULT_LEVEL = "DEBUG";
+// ── 级别控制 ──
+/**
+ * 解析最终日志级别。
+ * 优先级：环境变量 > 默认 DEBUG
+ */
+function resolveMinLevel() {
+    const env = process.env.OPENCLAW_LOG_LEVEL?.toUpperCase();
+    if (env && env in LEVEL_IDS)
+        return LEVEL_IDS[env];
+    return LEVEL_IDS[DEFAULT_LEVEL];
+}
+let minLevelId = resolveMinLevel();
+/** 运行时动态修改日志级别 */
+export function setLogLevel(level) {
+    const upper = level.toUpperCase();
+    if (!(upper in LEVEL_IDS)) {
+        throw new Error(`Invalid log level: ${level}. Valid: ${Object.keys(LEVEL_IDS).join(", ")}`);
+    }
+    minLevelId = LEVEL_IDS[upper];
+}
+// ── 时间格式化 ──
+function toLocalISO(now) {
+    const offsetMs = -now.getTimezoneOffset() * 60_000;
+    const sign = offsetMs >= 0 ? "+" : "-";
+    const abs = Math.abs(now.getTimezoneOffset());
+    const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+    const mm = String(abs % 60).padStart(2, "0");
+    return new Date(now.getTime() + offsetMs).toISOString().replace("Z", `${sign}${hh}:${mm}`);
+}
+function resolveLogPath() {
+    const dateKey = toLocalISO(new Date()).slice(0, 10);
+    return path.join(LOG_DIR, `openclaw-${dateKey}.log`);
+}
+// ── 写入 ──
+let logDirEnsured = false;
+function writeLog(level, message) {
+    const levelId = LEVEL_IDS[level] ?? LEVEL_IDS.INFO;
+    if (levelId < minLevelId)
+        return;
+    const now = new Date();
+    const entry = JSON.stringify({
+        "0": SUBSYSTEM,
+        "1": message,
+        _meta: {
+            runtime: "node",
+            runtimeVersion: process.versions.node,
+            hostname: HOSTNAME,
+            name: SUBSYSTEM,
+            parentNames: ["openclaw"],
+            date: now.toISOString(),
+            logLevelId: levelId,
+            logLevelName: level,
+        },
+        time: toLocalISO(now),
+    });
+    try {
+        if (!logDirEnsured) {
+            fs.mkdirSync(LOG_DIR, { recursive: true });
+            logDirEnsured = true;
+        }
+        fs.appendFileSync(resolveLogPath(), `${entry}\n`, "utf-8");
+    }
+    catch {
+        // 写日志失败不应阻塞业务
+    }
+}
+export const logger = {
+    trace(message) { writeLog("TRACE", message); },
+    debug(message) { writeLog("DEBUG", message); },
+    info(message) { writeLog("INFO", message); },
+    warn(message) { writeLog("WARN", message); },
+    error(message) { writeLog("ERROR", message); },
+    fatal(message) { writeLog("FATAL", message); },
+    getLogFilePath() { return resolveLogPath(); },
+};

package/dist/src/util/url-resolver.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared URL resolution helper.
+ *
+ * Resolves a possibly-relative URL against an optional base URL.
+ * Used by remote-agent-tool (WebUI continuation) and download-file-tool (artifact download).
+ */
+export declare function resolveOasnAccessUrl(accessApiBase: string | undefined, url: string): string;

package/dist/src/util/url-resolver.js

@@ -0,0 +1,20 @@
+/**
+ * Shared URL resolution helper.
+ *
+ * Resolves a possibly-relative URL against an optional base URL.
+ * Used by remote-agent-tool (WebUI continuation) and download-file-tool (artifact download).
+ */
+export function resolveOasnAccessUrl(accessApiBase, url) {
+    if (!url)
+        return url;
+    if (/^https?:\/\//i.test(url))
+        return url;
+    if (!accessApiBase)
+        return url;
+    try {
+        return new URL(url, accessApiBase).toString();
+    }
+    catch {
+        return url;
+    }
+}

package/index.ts

@@ -46,6 +46,17 @@ export default {
     '(transport=oasn) or Tencent IM C2C (transport=tim, default).',
   configSchema: buildChannelConfigSchema(OpenagentConfigSchema),
 
+  // 2026.6.9+: Gateway requires plugins to declare tool contracts before registering them.
+  contracts: {
+    tools: [
+      'openagent_call_remote_agent',
+      'openagent_search_agents',
+      'openagent_get_agent_detail',
+      'openagent_upload_file',
+      'openagent_download_file',
+    ],
+  },
+
   register(api: OpenClawPluginApi): void {
     logger.info('[entry] register() called');
 

package/openclaw.plugin.json

@@ -3,6 +3,15 @@
     "name": "OpenAgent",
     "description": "OpenAgent channel plugin — real-time messaging between AI agents via OASN",
     "version": "1.0.0",
+    "contracts": {
+        "tools": [
+            "openagent_call_remote_agent",
+            "openagent_search_agents",
+            "openagent_get_agent_detail",
+            "openagent_upload_file",
+            "openagent_download_file"
+        ]
+    },
     "channels": [
         "openagent"
     ],

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "openclaw-openagent",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "OpenAgent channel plugin for OpenClaw",
   "license": "MIT",
+  "main": "./dist/index.js",
   "files": [
+    "dist/",
     "src/",
     "skills/",
     "index.ts",
@@ -19,7 +21,7 @@
   ],
   "openclaw": {
     "extensions": [
-      "./index.ts"
+      "./dist/index.js"
     ],
     "channel": {
       "id": "openagent",
@@ -45,9 +47,10 @@
     "node": ">=22"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json && cp -r src/sdk dist/src/sdk && mkdir -p dist/src/plugin-ui/assets && cp src/plugin-ui/assets/openagent-override.js dist/src/plugin-ui/assets/",
     "build:override": "node ./src/plugin-ui/build.cjs",
     "watch:override": "node ./src/plugin-ui/build.cjs --watch",
-    "prepack": "npm run build:override && npm run typecheck",
+    "prepack": "npm run build:override && npm run build && npm run typecheck",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck",
     "test:contract": "node tests/contract.test.mjs && node tests/agent-book-batch-category.test.mjs",
@@ -72,7 +75,7 @@
     "@types/node": "^25.5.0",
     "@types/sql.js": "^1.4.11",
     "@types/yazl": "^3.3.1",
-    "openclaw": "^2026.4.22",
+    "openclaw": "^2026.6.10",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2"
   }

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

@@ -0,0 +1,133 @@
+/**
+ * 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;
+      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,10 +1,10 @@
 /**
- * Hooks — Scene + Purpose injection into agent system prompt
+ * Hooks — Scene + Purpose injection + Inline Image Offload
  *
- * Registers a `before_prompt_build` hook that appends channel-specific
- * rules (skill) and agent purpose to the system context for openagent sessions.
- *
- * Only fires for sessions with ID starting with `openagent:`.
+ * 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';
@@ -26,6 +26,7 @@ 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 {};
@@ -57,4 +58,87 @@ export function registerHooks(api: AnyApi): void {
     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

@@ -32,6 +32,8 @@ 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';
 
@@ -72,6 +74,10 @@ export function registerTools(api: OpenClawPluginApi): void {
   // 注：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 };

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

@@ -29,6 +29,7 @@ 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';
+import { resolveOasnAccessUrl } from '../util/url-resolver.js';
 
 // ── Helpers ──
 
@@ -174,6 +175,13 @@ export function createCallRemoteAgentTool(): ToolDescriptor {
             '"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'],
     },
@@ -279,9 +287,14 @@ export function createCallRemoteAgentTool(): ToolDescriptor {
           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 taskReq: TaskRequest = {
           requestId,
           task,
+          inputFileRefs: inputFileRefs?.length ? inputFileRefs : undefined,
           timeoutMs: OASN_INVOCATION_TIMEOUT_MS,
           // mode='session' 时不在协议层 join 已有 session（OASN 默认每次起新 Invocation）。
           // 上游若需要保留对话历史，请在 task 文本里显式带 session_id；
@@ -332,6 +345,39 @@ export function createCallRemoteAgentTool(): ToolDescriptor {
             }
           }
 
+          // 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',

package/src/app/types.ts

@@ -33,6 +33,7 @@ export interface ToolDescriptor {
       description: string;
       enum?: string[];
       default?: unknown;
+      items?: { type: string };
     }>;
     required: string[];
   };