openclaw-openagent 1.0.13 → 1.0.14

package/src/app/types.ts

@@ -1,68 +0,0 @@
-/**
- * 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;
-      items?: { type: string };
-    }>;
-    required: string[];
-  };
-  /**
-   * Execute the tool.
-   *
-   * OpenClaw runtime usually calls:
-   *   tool.execute(toolCallId, params, signal, onUpdate, ctx)
-   *
-   * 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,
-    contextOrSignal?: unknown,
-  ) => 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 }] };
-}

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

@@ -1,411 +0,0 @@
-/**
- * Upload File Tool — openagent_upload_file
- *
- * Uploads a local file to the OASN agent network, returning a fileRef
- * that can be passed to openagent_call_remote_agent via input_file_refs.
- *
- * Supports three input modes:
- *   - file_path: absolute path to a local file
- *   - media_ref: OpenClaw media://inbound/<id> reference (from web UI attachments)
- *   - filename_hint: original filename to scan & match from ~/.openclaw/media/inbound/
- *
- * API: POST /api/files (access layer)
- * Ref: access-upload-download-api.md §2
- */
-
-import fs from 'node:fs';
-import os from 'node:os';
-import nodePath from 'node:path';
-
-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, UploadFileParams } from '../transport/types.js';
-
-// ── Helpers ──
-
-const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB
-
-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 }));
-}
-
-/** 根据文件扩展名推断 MIME 类型 */
-function inferMimeType(filePath: string): string {
-  const ext = nodePath.extname(filePath).toLowerCase();
-  const map: Record<string, string> = {
-    '.pdf': 'application/pdf',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.svg': 'image/svg+xml',
-    '.webp': 'image/webp',
-    '.txt': 'text/plain',
-    '.md': 'text/markdown',
-    '.json': 'application/json',
-    '.csv': 'text/csv',
-    '.html': 'text/html',
-    '.css': 'text/css',
-    '.js': 'text/javascript',
-    '.ts': 'text/typescript',
-    '.py': 'text/x-python',
-    '.xml': 'application/xml',
-    '.zip': 'application/zip',
-    '.tar': 'application/x-tar',
-    '.gz': 'application/gzip',
-    '.mp3': 'audio/mpeg',
-    '.mp4': 'video/mp4',
-    '.doc': 'application/msword',
-    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    '.xls': 'application/vnd.ms-excel',
-    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    '.ppt': 'application/vnd.ms-powerpoint',
-    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  };
-  return map[ext] || 'application/octet-stream';
-}
-
-/**
- * Resolve a media://inbound/<id> reference to an absolute file path.
- * Uses OpenClaw's resolveMediaBufferPath when available, else falls back
- * to computing the path from ~/.openclaw/media/inbound/<id>.
- */
-async function resolveMediaRef(mediaRef: string): Promise<string> {
-  // Parse media://inbound/<id>
-  const match = mediaRef.match(/^media:\/\/inbound\/(.+)$/);
-  if (!match) {
-    throw new Error(`Unsupported media reference format: ${mediaRef}. Expected media://inbound/<id>`);
-  }
-  const id = match[1]!;
-
-  // Try OpenClaw SDK's resolveMediaBufferPath first
-  try {
-    const { resolveMediaBufferPath } = await import('openclaw/plugin-sdk/media-runtime');
-    return await resolveMediaBufferPath(id, 'inbound');
-  } catch {
-    // Fallback: compute path manually
-    const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
-    const resolved = nodePath.join(mediaDir, id);
-    // Security: ensure resolved path stays within mediaDir
-    if (!resolved.startsWith(mediaDir + nodePath.sep) && resolved !== mediaDir) {
-      throw new Error(`Unsafe media ID: ${id}`);
-    }
-    if (!fs.existsSync(resolved)) {
-      throw new Error(`Media file not found: ${id}. The attachment may have been sent inline (not saved to disk). Use file_path to upload a local file instead.`);
-    }
-    return resolved;
-  }
-}
-
-/** Recency window for filename_hint matching (milliseconds) */
-const FILENAME_HINT_RECENCY_MS = 5 * 60 * 1000;
-
-/**
- * Scan ~/.openclaw/media/inbound/ for recently modified files,
- * optionally filtered by a predicate. Returns candidates sorted by
- * mtime descending (most recent first).
- */
-function findRecentInboundFiles(
-  mediaDir: string,
-  filter?: (name: string) => boolean,
-): { name: string; path: string; mtimeMs: number }[] {
-  if (!fs.existsSync(mediaDir)) return [];
-
-  let entries: string[];
-  try {
-    entries = fs.readdirSync(mediaDir);
-  } catch {
-    return [];
-  }
-
-  const now = Date.now();
-  return entries
-    .filter((name) => {
-      if (name.startsWith('.')) return false;
-      if (filter && !filter(name)) return false;
-      try {
-        const stat = fs.statSync(nodePath.join(mediaDir, name));
-        return stat.isFile() && (now - stat.mtimeMs) <= FILENAME_HINT_RECENCY_MS;
-      } catch {
-        return false;
-      }
-    })
-    .map((name) => {
-      const fullPath = nodePath.join(mediaDir, name);
-      const stat = fs.statSync(fullPath);
-      return { name, path: fullPath, mtimeMs: stat.mtimeMs };
-    })
-    .sort((a, b) => b.mtimeMs - a.mtimeMs);
-}
-
-/**
- * Resolve a filename hint to an absolute file path by scanning
- * ~/.openclaw/media/inbound/ for recently modified files whose
- * names contain the hint (case-insensitive substring match).
- *
- * Handles the disk naming convention: <original-base>---<uuid>.<ext>
- * A hint of "photo.png" matches "photo---abc123.png" by extracting
- * the base name "photo" and matching it against the stored filename.
- */
-function resolveByFilenameHint(filenameHint: string): string {
-  const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
-
-  if (!fs.existsSync(mediaDir)) {
-    throw new Error(
-      `Media inbound directory not found: ${mediaDir}. ` +
-      `Ensure a file has been uploaded via the Web UI first.`,
-    );
-  }
-
-  // Normalize hint for matching against <base>---<uuid>.<ext> filenames
-  const hintLower = filenameHint.toLowerCase();
-  const lastDot = filenameHint.lastIndexOf('.');
-  const hintBaseLower = lastDot > 0
-    ? filenameHint.substring(0, lastDot).toLowerCase()
-    : hintLower;
-
-  const candidates = findRecentInboundFiles(mediaDir, (name) => {
-    const nameLower = name.toLowerCase();
-    return nameLower.includes(hintLower) || nameLower.includes(hintBaseLower);
-  });
-
-  if (candidates.length === 0) {
-    throw new Error(
-      `No recently modified file matching "${filenameHint}" found in the media inbound directory. ` +
-      `The file may have been renamed, deleted, or uploaded more than 5 minutes ago. ` +
-      `Try uploading the file again via the Web UI, or use file_path to specify an absolute path.`,
-    );
-  }
-
-  // Security: ensure resolved path stays within mediaDir
-  const resolved = candidates[0]!.path;
-  const mediaSep = mediaDir + nodePath.sep;
-  if (!resolved.startsWith(mediaSep) && resolved !== mediaDir) {
-    throw new Error(`Unsafe path resolved from filename hint: ${filenameHint}`);
-  }
-
-  return resolved;
-}
-
-/**
- * Resolve the most recently uploaded file from ~/.openclaw/media/inbound/.
- * Used as a last-resort fallback when the model sees an inline image
- * but has no filename or path information at all.
- */
-function resolveLatestInboundFile(): string {
-  const mediaDir = nodePath.join(os.homedir(), '.openclaw', 'media', 'inbound');
-
-  if (!fs.existsSync(mediaDir)) {
-    throw new Error(
-      `Media inbound directory not found: ${mediaDir}. ` +
-      `Ensure a file has been uploaded via the Web UI first.`,
-    );
-  }
-
-  const candidates = findRecentInboundFiles(mediaDir);
-
-  if (candidates.length === 0) {
-    throw new Error(
-      `No recently uploaded files found in the media inbound directory. ` +
-      `Upload a file via the Web UI first, then retry. ` +
-      `If you know the file path, use the file_path parameter instead.`,
-    );
-  }
-
-  if (candidates.length > 1) {
-    // Log a warning so the user/operator can audit unexpected matches
-    logger.warn(
-      `[upload-tool] auto-resolved latest of ${candidates.length} inbound files: ` +
-      `"${candidates[0]!.name}" (others: ${candidates.slice(1, 4).map((c) => c.name).join(', ')})`,
-    );
-  }
-
-  const resolved = candidates[0]!.path;
-  const mediaSep = mediaDir + nodePath.sep;
-  if (!resolved.startsWith(mediaSep) && resolved !== mediaDir) {
-    throw new Error('Unsafe path resolved from latest inbound file');
-  }
-
-  return resolved;
-}
-
-// ── Tool Factory ──
-
-export function createUploadFileTool(): ToolDescriptor {
-  return {
-    name: 'openagent_upload_file',
-    label: 'Upload File',
-    description:
-      'Upload a local file to the OASN agent network before calling a remote agent. ' +
-      'Use this when the user wants to send a file (document, image, code, etc.) ' +
-      'to a remote specialist agent for processing. ' +
-      'Returns a fileRef string. Pass this fileRef in the ' +
-      'openagent_call_remote_agent input_file_refs parameter so the remote agent can access the file. ' +
-      'Three input modes (use exactly one, or none to auto-detect): ' +
-      '(1) file_path: absolute local path (e.g., /Users/name/Downloads/photo.png); ' +
-      '(2) media_ref: a media://inbound/<id> URL visible in the message text; ' +
-      '(3) filename_hint: the filename as shown in the upload UI (e.g., "photo.png") — ' +
-      'use this when you see an inline image in the chat but NO media://inbound/ URL. ' +
-      'The tool will automatically scan recently uploaded files to find the match on disk. ' +
-      'If NO parameters are provided, the tool auto-resolves the most recently uploaded file ' +
-      'from the Web UI — this is the easiest option when the user just attached a file. ' +
-      'Prefer media_ref when you see a media://inbound/ URL, ' +
-      'filename_hint when you only see the inline content without a URL, ' +
-      'and file_path when the user explicitly tells you a specific path.',
-    parameters: {
-      type: 'object',
-      properties: {
-        file_path: {
-          type: 'string',
-          description: 'Absolute path to a local file (e.g., /Users/.../report.pdf). Use this for files on disk.',
-        },
-        media_ref: {
-          type: 'string',
-          description: 'OpenClaw media reference from web UI attachments (e.g., media://inbound/photo---uuid.png). Use this when the user attached a file in the chat and you see a media://inbound/ URL.',
-        },
-        filename_hint: {
-          type: 'string',
-          description:
-            'The original filename as shown in the upload UI (e.g., "photo.png", "report.pdf"). ' +
-            'Use this when you can see the file content inline but do NOT have a media://inbound/ URL. ' +
-            'The tool will scan recently uploaded files to find a match.',
-        },
-        display_name: {
-          type: 'string',
-          description: 'Optional display name for the file (defaults to filename)',
-        },
-      },
-      required: [],
-    },
-
-    async execute(
-      _id: unknown,
-      params: ToolParams,
-    ): Promise<ToolResult> {
-      const filePathRaw = String(params.file_path || '').trim();
-      const mediaRefRaw = String(params.media_ref || '').trim();
-      const filenameHint = String(params.filename_hint || '').trim();
-
-      // ① Resolve input source
-      let filePath: string;
-      let displayName: string;
-
-      if (mediaRefRaw) {
-        // media://inbound/<id> reference
-        try {
-          filePath = await resolveMediaRef(mediaRefRaw);
-          displayName = String(params.display_name || '').trim()
-            || nodePath.basename(filePath);
-        } catch (err) {
-          return fail((err as Error).message);
-        }
-      } else if (filePathRaw) {
-        // traditional file path
-        filePath = filePathRaw;
-        displayName = String(params.display_name || '').trim()
-          || nodePath.basename(filePath);
-      } else if (filenameHint) {
-        // filename hint → scan ~/.openclaw/media/inbound/ for matching file
-        try {
-          filePath = resolveByFilenameHint(filenameHint);
-          displayName = String(params.display_name || '').trim()
-            || nodePath.basename(filePath);
-        } catch (err) {
-          return fail((err as Error).message);
-        }
-      } else {
-        // fallback: auto-resolve the most recently uploaded file
-        try {
-          filePath = resolveLatestInboundFile();
-          displayName = String(params.display_name || '').trim()
-            || nodePath.basename(filePath);
-          logger.info(
-            `[upload-tool] Auto-resolved latest inbound file: ${filePath}`,
-          );
-        } catch (err) {
-          return fail((err as Error).message);
-        }
-      }
-
-      // ② 检查运行态
-      const rt = registry.getDefault();
-      if (!rt || !rt.isRunning) {
-        return fail('OpenAgent runtime not running');
-      }
-      if (rt.transportType !== 'oasn') {
-        return fail('File upload is only available via OASN transport');
-      }
-      const transport = rt.transport;
-      if (!transport || transport.transportType !== 'oasn') {
-        return fail('OASN transport not ready');
-      }
-
-      // ③ 读取文件
-      let stat: fs.Stats;
-      try {
-        stat = fs.statSync(filePath);
-      } catch {
-        return fail(`File not found: ${filePath}`);
-      }
-      if (!stat.isFile()) {
-        return fail(`Not a file: ${filePath}`);
-      }
-      if (stat.size > MAX_FILE_SIZE_BYTES) {
-        return fail(
-          `File too large: ${(stat.size / (1024 * 1024)).toFixed(1)} MB (max 100 MB)`,
-        );
-      }
-
-      let buffer: Buffer;
-      try {
-        buffer = fs.readFileSync(filePath);
-      } catch (err) {
-        return fail(`Cannot read file: ${(err as Error).message}`);
-      }
-
-      // ④ 上传
-      const mimeType = inferMimeType(filePath);
-
-      const oasnTransport = transport as OasnTransport;
-      const uploadParams: UploadFileParams = {
-        content: buffer,
-        displayName,
-        mimeType,
-      };
-
-      logger.info(
-        `[upload-tool] Uploading file: name=${displayName} size=${buffer.byteLength} mime=${mimeType}`,
-      );
-
-      let result;
-      try {
-        result = await oasnTransport.uploadFile(uploadParams);
-      } catch (err) {
-        logger.error(`[upload-tool] Upload failed: ${(err as Error).message}`);
-        return fail(`Upload failed: ${(err as Error).message}`);
-      }
-
-      logger.info(
-        `[upload-tool] Upload success: fileRef=${result.fileRef} size=${result.sizeBytes}`,
-      );
-
-      return success({
-        fileRef: result.fileRef,
-        displayName: result.displayName,
-        mimeType: result.mimeType,
-        sizeBytes: result.sizeBytes,
-        expiresAt: result.expiresAt,
-      });
-    },
-  };
-}

package/src/app/verbose-preflight.ts

@@ -1,190 +0,0 @@
-import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
-import { logger } from '../util/logger.js';
-
-type AgentEvent = {
-  runId?: unknown;
-  stream?: unknown;
-  data?: unknown;
-  [key: string]: unknown;
-};
-
-type AgentRunContext = {
-  verboseLevel?: string;
-  [key: string]: unknown;
-};
-
-type AgentEventState = {
-  listeners?: Set<(evt: AgentEvent) => void>;
-  runContextById?: Map<string, AgentRunContext>;
-};
-
-const AGENT_EVENT_STATE_KEY = Symbol.for('openclaw.agentEvents.state');
-const REMOTE_TOOL_CALL_IDS = new Set<string>();
-const REMOTE_TOOL_CALL_IDS_BY_RUN = new Map<string, Set<string>>();
-const PROMOTED_RUNS = new Set<string>();
-
-let installed = false;
-let missingStateWarned = false;
-let missingRuntimeWarned = false;
-
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
-}
-
-function readString(value: unknown): string {
-  return typeof value === 'string' ? value : '';
-}
-
-function readToolName(data: Record<string, unknown>): string {
-  const call = asRecord(data.call);
-  return (
-    readString(data.name) ||
-    readString(data.toolName) ||
-    readString(data.tool_name) ||
-    readString(call.name)
-  ).toLowerCase();
-}
-
-function readToolCallId(data: Record<string, unknown>): string {
-  const call = asRecord(data.call);
-  return (
-    readString(data.toolCallId) ||
-    readString(data.tool_call_id) ||
-    readString(data.id) ||
-    readString(call.id)
-  );
-}
-
-function isOpenagentRemoteToolName(name: string): boolean {
-  return name.includes('call_remote_agent') || name.includes('openagent_delegate');
-}
-
-function rememberRemoteToolCall(runId: string, toolCallId: string): void {
-  REMOTE_TOOL_CALL_IDS.add(toolCallId);
-  let runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
-  if (!runToolCallIds) {
-    runToolCallIds = new Set<string>();
-    REMOTE_TOOL_CALL_IDS_BY_RUN.set(runId, runToolCallIds);
-  }
-  runToolCallIds.add(toolCallId);
-}
-
-function forgetRemoteToolCall(runId: string, toolCallId: string): void {
-  REMOTE_TOOL_CALL_IDS.delete(toolCallId);
-  const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
-  if (!runToolCallIds) return;
-  runToolCallIds.delete(toolCallId);
-  if (runToolCallIds.size === 0) {
-    REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
-  }
-}
-
-function forgetRun(runId: string): void {
-  PROMOTED_RUNS.delete(runId);
-  const runToolCallIds = REMOTE_TOOL_CALL_IDS_BY_RUN.get(runId);
-  if (!runToolCallIds) return;
-  for (const toolCallId of runToolCallIds) {
-    REMOTE_TOOL_CALL_IDS.delete(toolCallId);
-  }
-  REMOTE_TOOL_CALL_IDS_BY_RUN.delete(runId);
-}
-
-function getAgentEventState(): AgentEventState | null {
-  const state = (globalThis as Record<PropertyKey, unknown>)[AGENT_EVENT_STATE_KEY];
-  if (!state || typeof state !== 'object') return null;
-  return state as AgentEventState;
-}
-
-function promoteRunVerboseLevel(runId: string, toolCallId: string, toolName: string): void {
-  const state = getAgentEventState();
-  const runContextById = state?.runContextById;
-
-  if (!(runContextById instanceof Map)) {
-    if (!missingStateWarned) {
-      missingStateWarned = true;
-      logger.warn('[verbose-preflight] OpenClaw agent event state is unavailable; OpenAgent SSE payload may be stripped');
-    }
-    return;
-  }
-
-  let ctx = runContextById.get(runId);
-  if (!ctx) {
-    ctx = {};
-    runContextById.set(runId, ctx);
-  }
-
-  if (ctx.verboseLevel !== 'full') {
-    ctx.verboseLevel = 'full';
-  }
-
-  if (!PROMOTED_RUNS.has(runId)) {
-    PROMOTED_RUNS.add(runId);
-    logger.info(`[verbose-preflight] promoted run verboseLevel=full (runId=${runId}, toolCallId=${toolCallId || 'unknown'}, tool=${toolName || 'unknown'})`);
-  }
-}
-
-function handleAgentEvent(evt: AgentEvent): void {
-  const runId = readString(evt.runId);
-  if (!runId) return;
-
-  const data = asRecord(evt.data);
-
-  if (evt.stream === 'lifecycle') {
-    const phase = readString(data.phase);
-    if (phase === 'end' || phase === 'error') {
-      forgetRun(runId);
-    }
-    return;
-  }
-
-  if (evt.stream !== 'tool') return;
-  const toolName = readToolName(data);
-  const toolCallId = readToolCallId(data);
-
-  if (toolCallId && isOpenagentRemoteToolName(toolName)) {
-    rememberRemoteToolCall(runId, toolCallId);
-  }
-
-  const shouldKeepPayload =
-    isOpenagentRemoteToolName(toolName) ||
-    (toolCallId !== '' && REMOTE_TOOL_CALL_IDS.has(toolCallId));
-
-  if (!shouldKeepPayload) return;
-
-  promoteRunVerboseLevel(runId, toolCallId, toolName);
-
-  const phase = readString(data.phase);
-  if (toolCallId && (phase === 'result' || phase === 'error' || phase === 'end')) {
-    forgetRemoteToolCall(runId, toolCallId);
-  }
-}
-
-function prioritizePreflightListener(listener: (evt: AgentEvent) => void): void {
-  const listeners = getAgentEventState()?.listeners;
-  if (!(listeners instanceof Set) || !listeners.has(listener)) return;
-
-  const rest = Array.from(listeners).filter(item => item !== listener);
-  listeners.clear();
-  listeners.add(listener);
-  for (const item of rest) listeners.add(item);
-
-  logger.debug('[verbose-preflight] listener moved before gateway subscribers');
-}
-
-export function installOpenagentVerbosePreflight(api: OpenClawPluginApi): void {
-  if (installed) return;
-
-  const onAgentEvent = api.runtime?.events?.onAgentEvent;
-  if (typeof onAgentEvent !== 'function') {
-    if (!missingRuntimeWarned) {
-      missingRuntimeWarned = true;
-      logger.warn('[verbose-preflight] api.runtime.events.onAgentEvent is unavailable; OpenAgent SSE payload preflight disabled');
-    }
-    return;
-  }
-
-  onAgentEvent(handleAgentEvent);
-  prioritizePreflightListener(handleAgentEvent);
-  installed = true;
-  logger.info('[verbose-preflight] installed');
-}