rol-websocket-channel 1.0.9 → 1.1.2

package/src/admin/methods/artifacts.ts

@@ -0,0 +1,977 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ensureDir, pathExists, readJsonFile } from '../lib/fs.ts';
+import { ensureInside } from '../lib/paths.ts';
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
+import type { JsonValue, MethodContext, MethodHandler } from '../types.ts';
+
+type ArtifactCategory =
+  | 'image'
+  | 'video'
+  | 'document'
+  | 'archive'
+  | 'other';
+
+type ArtifactStorageStatus = 'local_only' | 'uploaded';
+
+interface ArtifactRecord {
+  id: string;
+  fileName: string;
+  relativePath: string;
+  localPath: string;
+  category: ArtifactCategory;
+  mimeType: string;
+  ext: string | null;
+  sizeBytes: number;
+  storageStatus: ArtifactStorageStatus;
+  source: string;
+  previewable: boolean;
+  createdAt: string;
+  updatedAt: string;
+  objectKey?: string | null;
+  fileUrl?: string | null;
+  uploadedAt?: string | null;
+  record?: JsonValue;
+}
+
+interface ArtifactScanParams {
+  refresh?: boolean;
+}
+
+interface ArtifactGetContentParams {
+  artifactId?: string;
+  relativePath?: string;
+  maxInlineBytes?: number;
+}
+
+interface ArtifactEnsureUploadedParams {
+  artifactId?: string;
+  relativePath?: string;
+  presignedPostBody?: Record<string, JsonValue>;
+  baseUrl?: string;
+  authToken?: string;
+}
+
+interface ArtifactPresignedPostParams {
+  body: Record<string, JsonValue>;
+  baseUrl?: string;
+  authToken?: string;
+}
+
+interface ArtifactCreateRecordParams {
+  endpoint: string;
+  body: Record<string, JsonValue>;
+  baseUrl?: string;
+  authToken?: string;
+}
+
+interface ArtifactMarkUploadedParams {
+  artifactId?: string;
+  relativePath?: string;
+  objectKey?: string;
+  fileUrl?: string;
+  record?: JsonValue;
+}
+
+interface OpenClawConfig {
+  plugins?: {
+    entries?: Record<string, {
+      config?: {
+        apiCoreBot?: {
+          baseUrl?: string;
+          authToken?: string;
+        };
+      };
+    }>;
+  };
+}
+
+const INLINE_CONTENT_LIMIT_BYTES = 10 * 1024 * 1024;
+const MIN_ARTIFACT_SIZE_BYTES = 1;
+const ARTIFACT_MANIFEST_FILE = 'artifacts.json';
+const IGNORE_EXTENSIONS = new Set(['.tmp', '.part', '.crdownload']);
+const IGNORE_FILE_NAMES = new Set(['.ds_store', 'thumbs.db', ARTIFACT_MANIFEST_FILE]);
+const IGNORE_DIRECTORY_NAMES = new Set([
+  '.git',
+  '.cache',
+  'cache',
+  'caches',
+  'tmp',
+  'temp',
+  'logs',
+  'log',
+  'node_modules',
+  'sessions',
+  'session',
+  'history'
+]);
+
+const CATEGORY_BY_EXTENSION: Record<string, ArtifactCategory> = {
+  '.png': 'image',
+  '.jpg': 'image',
+  '.jpeg': 'image',
+  '.webp': 'image',
+  '.gif': 'image',
+  '.svg': 'image',
+  '.mp4': 'video',
+  '.mov': 'video',
+  '.webm': 'video',
+  '.avi': 'video',
+  '.mkv': 'video',
+  '.m4v': 'video',
+  '.pdf': 'document',
+  '.doc': 'document',
+  '.docx': 'document',
+  '.zip': 'archive',
+  '.7z': 'archive',
+  '.tar': 'archive',
+  '.gz': 'archive',
+  '.rar': 'archive'
+};
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.avi': 'video/x-msvideo',
+  '.mkv': 'video/x-matroska',
+  '.m4v': 'video/x-m4v',
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.zip': 'application/zip',
+  '.7z': 'application/x-7z-compressed',
+  '.tar': 'application/x-tar',
+  '.gz': 'application/gzip',
+  '.rar': 'application/vnd.rar'
+};
+
+interface WorkspacePaths {
+  workspaceRoot: string;
+  manifestPath: string;
+}
+
+interface PresignedPostUploadTarget {
+  uploadUrl: string;
+  fields: Record<string, string>;
+  objectKey: string | null;
+  fileUrl: string | null;
+}
+
+export const listArtifacts: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectOptionalObject(params) as unknown as ArtifactScanParams;
+  const refresh = objectParams.refresh !== false;
+  const manifest = refresh
+    ? await refreshArtifactManifest(context)
+    : await readOrRefreshArtifactManifest(context);
+
+  return {
+    scope: 'workspace',
+    count: manifest.items.length,
+    manifestPath: manifest.manifestPath,
+    workspaceRoot: manifest.workspacePaths.workspaceRoot,
+    items: manifest.items.map(artifactToJsonValue)
+  };
+};
+
+export const refreshArtifacts: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectOptionalObject(params) as unknown as ArtifactScanParams;
+  const manifest = await refreshArtifactManifest(context);
+
+  return {
+    ok: true,
+    scope: 'workspace',
+    count: manifest.items.length,
+    manifestPath: manifest.manifestPath,
+    workspaceRoot: manifest.workspacePaths.workspaceRoot,
+    items: manifest.items.map(artifactToJsonValue)
+  };
+};
+
+export const getArtifactContent: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ArtifactGetContentParams;
+  const maxInlineBytes = normalizeMaxInlineBytes(objectParams.maxInlineBytes);
+  const artifact = await resolveArtifact(objectParams, context);
+
+  if (artifact.sizeBytes > maxInlineBytes) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'Artifact is too large for inline transfer',
+      {
+        artifactId: artifact.id,
+        sizeBytes: artifact.sizeBytes,
+        maxInlineBytes
+      }
+    );
+  }
+
+  const content = await fs.readFile(artifact.localPath);
+
+  return {
+    scope: 'workspace',
+    artifact: {
+      ...artifactToJsonValue(artifact),
+      contentBase64: content.toString('base64')
+    }
+  };
+};
+
+export const ensureArtifactUploaded: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ArtifactEnsureUploadedParams;
+  const artifact = await resolveArtifact(objectParams, context);
+
+  if (artifact.storageStatus === 'uploaded' && artifact.fileUrl) {
+    return {
+      ok: true,
+      scope: 'workspace',
+      uploaded: false,
+      artifactId: artifact.id,
+      objectKey: artifact.objectKey ?? null,
+      downloadUrl: artifact.fileUrl,
+      item: artifactToJsonValue(artifact)
+    };
+  }
+
+  const endpointConfig = await resolveApiCoreBotEndpoint(
+    context.openclawRoot,
+    objectParams.baseUrl,
+    objectParams.authToken
+  );
+  const presignedPostBody = buildPresignedPostBody(objectParams.presignedPostBody, artifact);
+  const presignedResponse = await postJson(
+    `${endpointConfig.baseUrl}/api-core-bot/front/s3/get-presigned-post`,
+    presignedPostBody,
+    endpointConfig.authToken
+  );
+  const uploadTarget = resolvePresignedPostUploadTarget(presignedResponse);
+  await uploadArtifactToPresignedPost(uploadTarget, artifact);
+
+  const objectKey = uploadTarget.objectKey ?? artifact.objectKey ?? null;
+  const fileUrl = uploadTarget.fileUrl ?? artifact.fileUrl ?? buildPublicFileUrl(uploadTarget.uploadUrl, objectKey);
+  if (!fileUrl) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      'Unable to determine uploaded artifact download URL',
+      {
+        artifactId: artifact.id,
+        objectKey
+      }
+    );
+  }
+
+  const manifest = await readOrRefreshArtifactManifest(context);
+  const updated = await persistUploadedArtifact(
+    manifest.manifestPath,
+    manifest.items,
+    artifact.id,
+    {
+      objectKey,
+      fileUrl,
+      record: artifact.record
+    }
+  );
+
+  return {
+    ok: true,
+    scope: 'workspace',
+    uploaded: true,
+    artifactId: artifact.id,
+    objectKey,
+    downloadUrl: fileUrl,
+    item: artifactToJsonValue(updated)
+  };
+};
+
+export const getArtifactPresignedPost: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ArtifactPresignedPostParams;
+  const body = isObject(objectParams.body as JsonValue) ? objectParams.body : null;
+  if (!body) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Missing required parameter: body');
+  }
+
+  const endpointConfig = await resolveApiCoreBotEndpoint(context.openclawRoot, objectParams.baseUrl, objectParams.authToken);
+  const response = await postJson(
+    `${endpointConfig.baseUrl}/api-core-bot/front/s3/get-presigned-post`,
+    body,
+    endpointConfig.authToken
+  );
+
+  return {
+    ok: true,
+    endpoint: '/api-core-bot/front/s3/get-presigned-post',
+    data: response
+  };
+};
+
+export const createArtifactRecord: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ArtifactCreateRecordParams;
+  const body = isObject(objectParams.body as JsonValue) ? objectParams.body : null;
+  if (!body) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Missing required parameter: body');
+  }
+
+  const endpoint = expectString(objectParams.endpoint, 'endpoint');
+  if (!endpoint.startsWith('/api-core-bot/front/')) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'endpoint must start with /api-core-bot/front/'
+    );
+  }
+
+  const endpointConfig = await resolveApiCoreBotEndpoint(context.openclawRoot, objectParams.baseUrl, objectParams.authToken);
+  const response = await postJson(
+    `${endpointConfig.baseUrl}${endpoint}`,
+    body,
+    endpointConfig.authToken
+  );
+
+  return {
+    ok: true,
+    endpoint,
+    data: response
+  };
+};
+
+export const markArtifactUploaded: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ArtifactMarkUploadedParams;
+  const objectKey = optionalTrimmedString(objectParams.objectKey);
+  const fileUrl = optionalTrimmedString(objectParams.fileUrl);
+
+  if (!objectKey && !fileUrl) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'At least one of objectKey or fileUrl is required'
+    );
+  }
+
+  const manifest = await readOrRefreshArtifactManifest(context);
+  const artifact = findArtifact(manifest.items, objectParams);
+  if (!artifact) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Artifact not found', {
+      artifactId: objectParams.artifactId,
+      relativePath: objectParams.relativePath
+    });
+  }
+
+  const updated = await persistUploadedArtifact(
+    manifest.manifestPath,
+    manifest.items,
+    artifact.id,
+    {
+      objectKey: objectKey ?? artifact.objectKey ?? null,
+      fileUrl: fileUrl ?? artifact.fileUrl ?? null,
+      record: objectParams.record === undefined ? artifact.record : objectParams.record
+    }
+  );
+
+  return {
+    ok: true,
+    scope: 'workspace',
+    artifactId: artifact.id,
+    item: artifactToJsonValue(updated)
+  };
+};
+
+export function classifyArtifactCategory(fileName: string): ArtifactCategory {
+  const ext = path.extname(fileName).toLowerCase();
+  return CATEGORY_BY_EXTENSION[ext] ?? 'other';
+}
+
+export function shouldIgnoreArtifactFile(fileName: string): boolean {
+  const normalized = fileName.trim().toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+
+  if (normalized.startsWith('.')) {
+    return true;
+  }
+
+  if (IGNORE_FILE_NAMES.has(normalized)) {
+    return true;
+  }
+
+  const ext = path.extname(normalized);
+  return IGNORE_EXTENSIONS.has(ext);
+}
+
+async function refreshArtifactManifest(
+  context: MethodContext
+): Promise<{ manifestPath: string; items: ArtifactRecord[]; workspacePaths: WorkspacePaths }> {
+  const workspacePaths = await ensureWorkspacePaths(context.openclawRoot);
+  const { workspaceRoot, manifestPath } = workspacePaths;
+
+  const existing = await readExistingManifest(manifestPath);
+  const existingByPath = new Map(existing.map((item) => [item.relativePath, item]));
+  const files = await collectArtifactFiles(workspaceRoot);
+  const items: ArtifactRecord[] = [];
+
+  for (const fullPath of files) {
+    const stat = await fs.stat(fullPath);
+    if (!stat.isFile() || stat.size < MIN_ARTIFACT_SIZE_BYTES) {
+      continue;
+    }
+
+    const relativePath = path.relative(workspaceRoot, fullPath).replace(/\\/g, '/');
+    const existingItem = existingByPath.get(relativePath);
+    const fileName = path.basename(fullPath);
+    if (!shouldIncludeArtifactFile(fileName)) {
+      continue;
+    }
+
+    const ext = normalizeExtension(fileName);
+    const createdAt = normalizeTimestamp(stat.birthtime, stat.mtime);
+    const updatedAt = stat.mtime.toISOString();
+
+    items.push({
+      id: existingItem?.id ?? buildArtifactId(relativePath),
+      fileName,
+      relativePath,
+      localPath: fullPath,
+      category: classifyArtifactCategory(fileName),
+      mimeType: MIME_BY_EXTENSION[ext ?? ''] ?? 'application/octet-stream',
+      ext,
+      sizeBytes: stat.size,
+      storageStatus: existingItem?.storageStatus ?? 'local_only',
+      source: existingItem?.source ?? 'generated',
+      previewable: isPreviewableCategory(classifyArtifactCategory(fileName)),
+      createdAt: existingItem?.createdAt ?? createdAt,
+      updatedAt,
+      objectKey: existingItem?.objectKey ?? null,
+      fileUrl: existingItem?.fileUrl ?? null,
+      uploadedAt: existingItem?.uploadedAt ?? null,
+      record: existingItem?.record
+    });
+  }
+
+  items.sort((a, b) => a.fileName.localeCompare(b.fileName));
+  await writeArtifactManifest(manifestPath, items);
+
+  return { manifestPath, items, workspacePaths };
+}
+
+async function readOrRefreshArtifactManifest(
+  context: MethodContext
+): Promise<{ manifestPath: string; items: ArtifactRecord[]; workspacePaths: WorkspacePaths }> {
+  const workspacePaths = await ensureWorkspacePaths(context.openclawRoot);
+  const { manifestPath } = workspacePaths;
+  if (!(await pathExists(manifestPath))) {
+    return await refreshArtifactManifest(context);
+  }
+
+  const items = await readExistingManifest(manifestPath);
+  return { manifestPath, items, workspacePaths };
+}
+
+async function readExistingManifest(manifestPath: string): Promise<ArtifactRecord[]> {
+  if (!(await pathExists(manifestPath))) {
+    return [];
+  }
+
+  const parsed = await readJsonFile<JsonValue>(manifestPath);
+  if (!Array.isArray(parsed)) {
+    return [];
+  }
+
+  const items: ArtifactRecord[] = [];
+  for (const item of parsed) {
+    if (isArtifactRecord(item)) {
+      items.push(item);
+    }
+  }
+
+  return items;
+}
+
+async function writeArtifactManifest(manifestPath: string, items: ArtifactRecord[]): Promise<void> {
+  await fs.writeFile(
+    manifestPath,
+    JSON.stringify(items.map((item) => artifactToJsonValue(item)), null, 2),
+    'utf8'
+  );
+}
+
+async function persistUploadedArtifact(
+  manifestPath: string,
+  items: ArtifactRecord[],
+  artifactId: string,
+  updates: {
+    objectKey?: string | null;
+    fileUrl?: string | null;
+    record?: JsonValue;
+  }
+): Promise<ArtifactRecord> {
+  const now = new Date().toISOString();
+  let updatedArtifact: ArtifactRecord | null = null;
+
+  const updatedItems = items.map((item) => {
+    if (!isArtifactRecord(item) || item.id !== artifactId) {
+      return item;
+    }
+
+    updatedArtifact = {
+      ...item,
+      storageStatus: 'uploaded',
+      objectKey: updates.objectKey ?? item.objectKey ?? null,
+      fileUrl: updates.fileUrl ?? item.fileUrl ?? null,
+      uploadedAt: now,
+      updatedAt: now,
+      ...(updates.record === undefined ? {} : { record: updates.record })
+    };
+
+    return updatedArtifact;
+  });
+
+  await writeArtifactManifest(manifestPath, updatedItems);
+
+  if (!updatedArtifact) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'Artifact not found while persisting upload state', {
+      artifactId
+    });
+  }
+
+  return updatedArtifact;
+}
+
+async function collectArtifactFiles(rootDir: string): Promise<string[]> {
+  const files: string[] = [];
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && shouldIgnoreArtifactDirectory(entry.name)) {
+      continue;
+    }
+
+    if (entry.isFile() && shouldIgnoreArtifactFile(entry.name)) {
+      continue;
+    }
+
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectArtifactFiles(fullPath));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+async function resolveArtifact(
+  params: { artifactId?: string; relativePath?: string },
+  context: MethodContext
+): Promise<ArtifactRecord> {
+  const manifest = await readOrRefreshArtifactManifest(context);
+  const artifact = findArtifact(manifest.items, params);
+  if (!artifact) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Artifact not found', {
+      artifactId: params.artifactId,
+      relativePath: params.relativePath
+    });
+  }
+
+  const checkedPath = ensureInside(manifest.workspacePaths.workspaceRoot, artifact.localPath);
+  if (!(await pathExists(checkedPath))) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Artifact file does not exist', {
+      localPath: checkedPath
+    });
+  }
+
+  return {
+    ...artifact,
+    localPath: checkedPath
+  };
+}
+
+function findArtifact(
+  items: ArtifactRecord[],
+  selector: { artifactId?: string; relativePath?: string }
+): ArtifactRecord | null {
+  const artifactId = optionalTrimmedString(selector.artifactId);
+  const relativePath = normalizeRelativePath(optionalTrimmedString(selector.relativePath));
+
+  if (!artifactId && !relativePath) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'Either artifactId or relativePath is required'
+    );
+  }
+
+  return items.find((item) => {
+    if (artifactId && item.id === artifactId) {
+      return true;
+    }
+
+    return Boolean(relativePath && item.relativePath === relativePath);
+  }) ?? null;
+}
+
+function resolveWorkspaceRoot(openclawRoot: string): string {
+  const workspaceRoot = path.join(openclawRoot, 'workspace');
+  return ensureInside(openclawRoot, workspaceRoot);
+}
+
+async function ensureWorkspacePaths(openclawRoot: string): Promise<WorkspacePaths> {
+  const workspaceRoot = resolveWorkspaceRoot(openclawRoot);
+  const manifestPath = ensureInside(workspaceRoot, path.join(workspaceRoot, ARTIFACT_MANIFEST_FILE));
+
+  await ensureDir(workspaceRoot);
+
+  return {
+    workspaceRoot,
+    manifestPath
+  };
+}
+
+function buildArtifactId(relativePath: string): string {
+  return `art_${createHash('sha1').update(relativePath).digest('hex').slice(0, 12)}`;
+}
+
+function normalizeExtension(fileName: string): string | null {
+  const ext = path.extname(fileName).toLowerCase();
+  return ext || null;
+}
+
+function normalizeRelativePath(value: string | null): string | null {
+  if (!value) {
+    return null;
+  }
+
+  return value.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function normalizeTimestamp(created: Date, fallback: Date): string {
+  return Number.isNaN(created.getTime()) ? fallback.toISOString() : created.toISOString();
+}
+
+function normalizeMaxInlineBytes(value: number | undefined): number {
+  if (value === undefined) {
+    return INLINE_CONTENT_LIMIT_BYTES;
+  }
+
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'maxInlineBytes must be a positive number'
+    );
+  }
+
+  return Math.floor(value);
+}
+
+function isPreviewableCategory(category: ArtifactCategory): boolean {
+  return category === 'image' || category === 'video' || category === 'document';
+}
+
+function shouldIgnoreArtifactDirectory(dirName: string): boolean {
+  const normalized = dirName.trim().toLowerCase();
+  return !normalized || normalized.startsWith('.') || IGNORE_DIRECTORY_NAMES.has(normalized);
+}
+
+function shouldIncludeArtifactFile(fileName: string): boolean {
+  if (shouldIgnoreArtifactFile(fileName)) {
+    return false;
+  }
+
+  return classifyArtifactCategory(fileName) !== 'other';
+}
+
+function isArtifactRecord(value: unknown): value is ArtifactRecord {
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    return false;
+  }
+
+  const objectValue = value as Record<string, unknown>;
+  return (
+    typeof objectValue.id === 'string' &&
+    typeof objectValue.fileName === 'string' &&
+    typeof objectValue.relativePath === 'string' &&
+    typeof objectValue.localPath === 'string'
+  );
+}
+
+function artifactToJsonValue(item: ArtifactRecord): { [key: string]: JsonValue } {
+  return {
+    id: item.id,
+    fileName: item.fileName,
+    relativePath: item.relativePath,
+    localPath: item.localPath,
+    category: item.category,
+    mimeType: item.mimeType,
+    ext: item.ext,
+    sizeBytes: item.sizeBytes,
+    storageStatus: item.storageStatus,
+    source: item.source,
+    previewable: item.previewable,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    objectKey: item.objectKey ?? null,
+    fileUrl: item.fileUrl ?? null,
+    uploadedAt: item.uploadedAt ?? null,
+    record: item.record ?? null
+  };
+}
+
+function expectObject(value: JsonValue | undefined): Record<string, JsonValue> {
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
+  }
+
+  return value as Record<string, JsonValue>;
+}
+
+function expectOptionalObject(value: JsonValue | undefined): Record<string, JsonValue> {
+  if (value === undefined) {
+    return {};
+  }
+
+  return expectObject(value);
+}
+
+function buildPresignedPostBody(
+  providedBody: Record<string, JsonValue> | undefined,
+  artifact: ArtifactRecord
+): Record<string, JsonValue> {
+  const body = isObject(providedBody) ? { ...providedBody } : {};
+
+  if (body.filename === undefined) {
+    body.filename = artifact.fileName;
+  }
+
+  return body;
+}
+
+function expectString(value: JsonValue | undefined, fieldName: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      `Field '${fieldName}' must be a non-empty string`
+    );
+  }
+
+  return value.trim();
+}
+
+function optionalTrimmedString(value: JsonValue | undefined): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function isObject(value: JsonValue | undefined): value is Record<string, JsonValue> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function resolveApiCoreBotEndpoint(
+  openclawRoot: string,
+  overrideBaseUrl?: string,
+  overrideAuthToken?: string
+): Promise<{ baseUrl: string; authToken?: string }> {
+  const config = await readJsonFile<OpenClawConfig>(path.join(openclawRoot, 'openclaw.json'));
+  const pluginConfig = config.plugins?.entries?.['rol-websocket-channel']?.config?.apiCoreBot ?? {};
+  const baseUrl = (overrideBaseUrl && overrideBaseUrl.trim()) || pluginConfig.baseUrl;
+
+  if (!baseUrl || !baseUrl.trim()) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'apiCoreBot.baseUrl is not configured'
+    );
+  }
+
+  const authToken = (overrideAuthToken && overrideAuthToken.trim()) || pluginConfig.authToken;
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ''),
+    authToken
+  };
+}
+
+async function postJson(
+  url: string,
+  body: Record<string, JsonValue>,
+  authToken?: string
+): Promise<JsonValue> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json'
+  };
+
+  if (authToken && authToken.trim()) {
+    headers.Authorization = `Bearer ${authToken.trim()}`;
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body)
+  });
+
+  const payload = await response.json().catch(async () => await response.text()) as JsonValue;
+  if (!response.ok) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      `Request failed: ${response.status}`,
+      {
+        url,
+        status: response.status,
+        payload
+      }
+    );
+  }
+
+  if (isObject(payload) && payload.success === false) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      pickStringValue(payload, ['message', 'msg']) ?? 'Request failed',
+      {
+        url,
+        payload
+      }
+    );
+  }
+
+  return payload;
+}
+
+function resolvePresignedPostUploadTarget(payload: JsonValue): PresignedPostUploadTarget {
+  for (const candidate of collectPresignedPostCandidates(payload)) {
+    const uploadUrl = pickStringValue(candidate, ['url', 'uploadUrl', 'postUrl', 'presignedPostUrl']);
+    const rawFields = candidate.fields ?? candidate.formData ?? candidate.form ?? candidate.params;
+    const fields = toStringRecord(rawFields);
+
+    if (!uploadUrl || !fields) {
+      continue;
+    }
+
+    return {
+      uploadUrl,
+      fields,
+      objectKey: pickStringValue(candidate, ['objectKey', 'fileKey', 'file_key', 'source_file_key', 'key']) ?? fields.key ?? null,
+      fileUrl: pickStringValue(candidate, ['fileUrl', 'file_url', 'downloadUrl', 'source_file_url', 'location']) ?? null
+    };
+  }
+
+  throw new JsonRpcException(
+    JSON_RPC_ERRORS.internalError,
+    'Presigned post response is missing upload url or fields',
+    { payload }
+  );
+}
+
+function collectPresignedPostCandidates(payload: JsonValue): Array<Record<string, JsonValue>> {
+  const candidates: Array<Record<string, JsonValue>> = [];
+  const queue: JsonValue[] = [payload];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!isObject(current)) {
+      continue;
+    }
+
+    candidates.push(current);
+
+    for (const key of ['data', 'result', 'presignedPost']) {
+      const nested = current[key];
+      if (isObject(nested)) {
+        queue.push(nested);
+      }
+    }
+  }
+
+  return candidates;
+}
+
+function pickStringValue(
+  source: Record<string, JsonValue>,
+  keys: string[]
+): string | null {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  return null;
+}
+
+function toStringRecord(value: JsonValue | undefined): Record<string, string> | null {
+  if (!isObject(value)) {
+    return null;
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === null) {
+      continue;
+    }
+
+    if (typeof item === 'string') {
+      result[key] = item;
+      continue;
+    }
+
+    if (typeof item === 'number' || typeof item === 'boolean') {
+      result[key] = String(item);
+      continue;
+    }
+
+    return null;
+  }
+
+  return result;
+}
+
+async function uploadArtifactToPresignedPost(
+  target: PresignedPostUploadTarget,
+  artifact: ArtifactRecord
+): Promise<void> {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(target.fields)) {
+    formData.append(key, value);
+  }
+
+  const content = await fs.readFile(artifact.localPath);
+  formData.append('file', new Blob([content], { type: artifact.mimeType }), artifact.fileName);
+
+  const response = await fetch(target.uploadUrl, {
+    method: 'POST',
+    body: formData
+  });
+
+  if (!response.ok) {
+    const payload = await response.text().catch(() => '');
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      `Artifact upload failed: ${response.status}`,
+      {
+        url: target.uploadUrl,
+        status: response.status,
+        payload
+      }
+    );
+  }
+}
+
+function buildPublicFileUrl(uploadUrl: string, objectKey: string | null): string | null {
+  if (!objectKey) {
+    return null;
+  }
+
+  try {
+    const url = new URL(uploadUrl);
+    url.pathname = `${url.pathname.replace(/\/+$/, '')}/${objectKey.replace(/^\/+/, '')}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+  } catch {
+    return null;
+  }
+}