metainsight-context-engine 0.0.8 → 0.0.10

package/cos-operations.ts

@@ -0,0 +1,780 @@
+/**
+ * COS Operations — Unified CRUD Operations Layer
+ *
+ * Provides all data operations (upload / search / download / delete) for the
+ * Cloud Context Engine. Built on top of the bootstrap layer (`cos-bootstrap.ts`)
+ * and routes requests to the correct dataset / COS prefix based on `category`.
+ *
+ * Architecture:
+ *   cos-bootstrap.ts  →  cos-operations.ts  →  engine.ts / index.ts
+ *   (init + low-level)    (CRUD operations)     (business logic)
+ *
+ * The constructor accepts a `BootstrapOutcome`, so consumers only need to call
+ * `bootstrap()` once and pass the result here — no duplicate initialization.
+ *
+ * Multimodal retrieval:
+ *   - Text/memory queries route to DocSearch datasets (category="memory")
+ *   - Image queries route to ImageSearch datasets (category="image")
+ *   - The search template is automatically selected per-dataset based on
+ *     the dataset's `templateId` (Official:ImageSearch → "ImageSearch").
+ *
+ * Key improvements over the old `cloud-client.ts`:
+ *   - Upload path uses the dataset's `cosPrefix` (not hardcoded `uploads/`)
+ *   - Search routes to the correct dataset name based on category
+ *   - Automatic template selection for multimodal (DocSearch / ImageSearch)
+ *   - Download support (getObject from COS)
+ *   - Delete support (deleteObject from COS)
+ */
+
+import type COS from 'cos-nodejs-sdk-v5';
+
+import type { BootstrapOutcome, ResolvedCosConfig, ResolvedDataset } from './cos-bootstrap.js';
+import { sendCIRequest } from './cos-bootstrap.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CloudSearchResult {
+  snippet: string;
+  score: number;
+  docId?: string;
+  category?: 'memory' | 'document';
+  /** Signed HTTPS URL for image results (only present for ImageSearch results). */
+  imageUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CloudUploadResult {
+  docId: string;
+  key: string;
+  status: string;
+  /** Error message when status === 'error'. */
+  error?: string;
+}
+
+export interface CloudDownloadResult {
+  content: string;
+  key: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CloudSearchOptions {
+  category?: string;
+  maxResults?: number;
+  minScore?: number;
+}
+
+export interface CloudUploadOptions {
+  category?: string;
+  docId?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * When set, overrides the default COS key construction
+   * (`{cosPrefix}{docId}.md`) and uses this value as the full COS key.
+   *
+   * Useful for placing files outside the dataset's cosPrefix directory,
+   * e.g. workspace identity files that should live at
+   * `openclaw-{agentId}/agents.md` instead of
+   * `openclaw-{agentId}/workspace/agents.md`.
+   */
+  customKey?: string;
+}
+
+export interface CloudDownloadOptions {
+  category?: string;
+}
+
+/** DocSearch result item from CI hybridsearch API. */
+interface DocResultItem {
+  Text?: string;
+  Score?: number;
+  URI?: string;
+  TextPage?: number;
+  ImageUrls?: Record<string, string>;
+}
+
+/** ImageSearch result item from CI hybridsearch API. */
+interface ImageResultItem {
+  URI?: string;
+  Score?: number;
+}
+
+// ============================================================================
+// Helpers — docId sanitization
+// ============================================================================
+
+/**
+ * Sanitize a docId so that it is safe to use as a COS object-key segment.
+ *
+ * COS (S3-compatible) interprets `/` as a directory separator, so names like
+ * `IMAP/SMTP Email Tool` would be split across folders.
+ *
+ * Strategy:
+ *   1. Prefixed docIds (containing `:`) are split at the **first** colon.
+ *      Everything after the colon is the "name" part — ALL `/` in the name
+ *      are replaced with `__`. The prefix itself never contains `/` so it
+ *      is kept as-is.
+ *
+ *   2. For non-prefixed docIds, the **first** `/` is assumed to be an
+ *      intentional directory boundary (e.g. `memory/2026-03-15`).
+ *      Only the portion after the first `/` has its `/` replaced.
+ *      If there is no `/` at all, the string is returned unchanged
+ *      (nothing to sanitize).
+ *
+ * Note: DocIds should avoid `/` characters. Use `__` as a substitute
+ * when `/` appears in names. The `unsanitizeDocId()` function reverses
+ * this transformation when parsing COS URIs from search results.
+ *
+ * Examples:
+ *   "IMAP__SMTP Email Tool"            → "IMAP__SMTP Email Tool"  (pre-sanitized)
+ *   "memory/2026-03-15"                → "memory/2026-03-15"      (dir preserved)
+ *   "memory/IMAP/SMTP Tool"            → "memory/IMAP__SMTP Tool" (dir preserved, name sanitized)
+ */
+function sanitizeDocId(docId: string): string {
+  // Prefixed docIds (e.g. "category:name")
+  // The colon separates a category tag from the human-readable name.
+  // ALL slashes after the colon belong to the name and must be escaped.
+  const colonIdx = docId.indexOf(':');
+  if (colonIdx !== -1) {
+    const prefix = docId.slice(0, colonIdx + 1);
+    const namePart = docId.slice(colonIdx + 1).replace(/\//g, '__');
+    return `${prefix}${namePart}`;
+  }
+
+  // Non-prefixed: preserve the FIRST `/` as a directory boundary,
+  // but replace any further `/` in the filename segment.
+  const firstSlash = docId.indexOf('/');
+  if (firstSlash === -1) {
+    // No slash at all — nothing to sanitize
+    return docId;
+  }
+
+  const dirPart = docId.slice(0, firstSlash);
+  const namePart = docId.slice(firstSlash + 1).replace(/\//g, '__');
+  return `${dirPart}/${namePart}`;
+}
+
+/**
+ * Reverse `sanitizeDocId` — restores the original docId from a COS key
+ * segment. Used when parsing COS URIs returned by CI search.
+ */
+function unsanitizeDocId(sanitized: string): string {
+  return sanitized.replace(/__/g, '/');
+}
+
+// ============================================================================
+// CosOperations — Unified CRUD
+// ============================================================================
+
+export class CosOperations {
+  private readonly cos: COS;
+  private readonly config: ResolvedCosConfig;
+  /** Search template — DocSearch or ImageSearch. Default: DocSearch. */
+  private readonly template: string;
+  /** Default match threshold (0-100). CI recommends 80, we default to 60. */
+  private readonly matchThreshold: number;
+
+  /**
+   * Create a CosOperations instance from a successful bootstrap outcome.
+   *
+   * @throws if the bootstrap outcome indicates failure
+   */
+  constructor(
+    outcome: BootstrapOutcome,
+    opts?: { template?: string; matchThreshold?: number },
+  ) {
+    if (!outcome.success) {
+      throw new Error(`CosOperations: cannot initialize from failed bootstrap: ${outcome.error}`);
+    }
+    this.cos = outcome.cos;
+    this.config = outcome.config;
+    this.template = opts?.template ?? 'DocSearch';
+    this.matchThreshold = opts?.matchThreshold ?? 60;
+  }
+
+  // ==========================================================================
+  // Dataset routing
+  // ==========================================================================
+
+  /**
+   * Resolve the dataset definition for a given category.
+   *
+   * Routing rules:
+   *   1. If a dataset's `cosPrefix` starts with `{category}/`, use it.
+   *      (legacy layout: cosPrefix="memory/" matches category="memory")
+   *   2. If a dataset's `cosPrefix` contains `/{category}/`, use it.
+   *      (multi-agent layout: cosPrefix="openclaw-xxx/workspace/memory/" matches category="memory")
+   *   3. If a dataset's `name` contains the category, use it.
+   *   4. Otherwise, fall back to the first dataset in config.
+   */
+  private resolveDataset(category?: string): ResolvedDataset {
+    if (!category || this.config.datasets.length === 1) {
+      return this.config.datasets[0];
+    }
+
+    const lowerCat = category.toLowerCase();
+
+    // Priority 1: cosPrefix starts with category (legacy: cosPrefix="memory/")
+    const byPrefix = this.config.datasets.find(
+      (ds) => ds.cosPrefix.toLowerCase().startsWith(`${lowerCat}/`),
+    );
+    if (byPrefix) {
+      return byPrefix;
+    }
+
+    // Priority 2: cosPrefix contains category as a path segment
+    // (multi-agent: cosPrefix="openclaw-xxx/workspace/memory/")
+    const byContains = this.config.datasets.find(
+      (ds) => ds.cosPrefix.toLowerCase().includes(`/${lowerCat}/`),
+    );
+    if (byContains) {
+      return byContains;
+    }
+
+    // Priority 3: name contains category (e.g. category="memory" → name="openclaw-memory-xxx")
+    const byName = this.config.datasets.find(
+      (ds) => ds.name.toLowerCase().includes(lowerCat),
+    );
+    if (byName) {
+      return byName;
+    }
+
+    // Fallback: first dataset
+    return this.config.datasets[0];
+  }
+
+  // ==========================================================================
+  // Search — CI hybridsearch API
+  // ==========================================================================
+
+  /**
+   * Semantic / hybrid search against the CI dataset.
+   *
+   * Routing:
+   *   - Image datasets (Official:ImageSearch) → `POST /datasetquery/imagesearch`
+   *     with only `DatasetName` + `Mode: "text"` (simplified temporary API).
+   *   - All other datasets → `POST /datasetquery/hybridsearch` with full params.
+   *
+   * DocSearch: SearchText is truncated to 60 UTF-8 chars (CI API limit).
+   */
+  async search(query: string, opts?: CloudSearchOptions): Promise<CloudSearchResult[]> {
+    const { maxResults = 10, minScore, category } = opts ?? {};
+    const dataset = this.resolveDataset(category);
+
+    const isImageDataset = dataset.templateId.includes('ImageSearch');
+
+    // ── Image dataset → simplified imagesearch endpoint ──
+    if (isImageDataset) {
+      const body: Record<string, unknown> = {
+        DatasetName: dataset.name,
+        Mode: 'text',
+        Text: String(query).slice(0, 55)|| '-',
+        Limit: 10,
+        MatchThreshold: 60,
+      };
+
+      const result = await sendCIRequest(
+        this.cos,
+        this.config.bucket,
+        this.config.region,
+        'POST',
+        'datasetquery/imagesearch',
+        body,
+      );
+
+      const res = result as Record<string, unknown>;
+      const response = res.Response as Record<string, unknown> | undefined;
+      const imageResult = (response?.ImageResult ?? res.ImageResult) as ImageResultItem[] | undefined;
+
+      return this.mapImageResults(imageResult, category);
+    }
+
+    // ── Doc dataset → hybridsearch endpoint (full params) ──
+    // CI API: SearchText max 60 UTF-8 characters
+    const searchText = query.length > 60 ? query.slice(0, 60) : query;
+
+    // Convert 0-1 minScore to 0-100 MatchThreshold, floor to configured minimum
+    const threshold = minScore !== undefined
+      ? Math.max(Math.floor(minScore * 100), this.matchThreshold)
+      : this.matchThreshold;
+
+    const body: Record<string, unknown> = {
+      DatasetName: dataset.name,
+      Mode: 'text',
+      Templates: this.template,
+      SearchText: searchText,
+      Limit: 30,
+      MatchThreshold: threshold,
+      Offset: 0,
+    };
+
+    const result = await sendCIRequest(
+      this.cos,
+      this.config.bucket,
+      this.config.region,
+      'POST',
+      'datasetquery/hybridsearch',
+      body,
+    );
+
+    const res = result as Record<string, unknown>;
+    const response = res.Response as Record<string, unknown> | undefined;
+    const docResult = (response?.DocResult ?? res.DocResult) as DocResultItem[] | undefined;
+
+    return this.mapDocResults(docResult, category);
+  }
+
+  // ==========================================================================
+  // Upload — COS putObject (content stored as Markdown for CI indexing)
+  // ==========================================================================
+
+  /**
+   * Upload content to the COS bucket for CI indexing.
+   *
+   * Content is stored as a Markdown file under `{cosPrefix}{docId}.md`.
+   * CI will pick it up via the dataset binding and index it automatically.
+   * Metadata is stored in COS custom headers (`x-cos-meta-*`).
+   *
+   * The upload path is derived from the dataset's `cosPrefix` — not hardcoded.
+   * Category routing is handled by `resolveDataset()` which selects the
+   * correct dataset (and thus the correct cosPrefix). We do NOT append
+   * `{category}/` again — that would create nested directories like
+   * `memory/memory/`.
+   */
+  async upload(content: string, opts?: CloudUploadOptions): Promise<CloudUploadResult> {
+    const category = opts?.category ?? 'general';
+    const docId = opts?.docId ?? `${category}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const dataset = this.resolveDataset(category);
+
+    // Sanitize docId: replace `/` with `__` so COS doesn't treat it as a
+    // directory boundary.  e.g. "memory:IMAP/SMTP Email Tool"
+    //   → "memory:IMAP__SMTP Email Tool"
+    const safeDocId = sanitizeDocId(docId);
+
+    // Route to the correct COS path via dataset cosPrefix.
+    // cosPrefix already encodes the category boundary (e.g. "memory/"),
+    // so we only append the docId — no extra `{category}/` layer.
+    //
+    // When `customKey` is provided, it overrides the default key construction.
+    // This is used for files that should live outside the dataset's cosPrefix,
+    // e.g. workspace identity files at `openclaw-{agentId}/agents.md`.
+    const key = opts?.customKey ?? `${dataset.cosPrefix}${safeDocId}.md`;
+
+    // Build COS custom headers for metadata (x-cos-meta-* headers).
+    // Values must be strings; non-string values are JSON-serialized.
+    const headers: Record<string, string> = {
+      'x-cos-meta-category': category,
+      'x-cos-meta-created-at': new Date().toISOString(),
+    };
+    const metadata = opts?.metadata ?? {};
+    for (const [k, v] of Object.entries(metadata)) {
+      const headerKey = `x-cos-meta-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+      headers[headerKey] = typeof v === 'string' ? v : JSON.stringify(v);
+    }
+
+    return new Promise((resolve, reject) => {
+      this.cos.putObject(
+        {
+          Bucket: this.config.bucket,
+          Region: this.config.region,
+          Key: key,
+          Body: content,
+          Headers: headers,
+        } as never,
+        (err: unknown) => {
+          if (err) {
+            const detail = err instanceof Error
+              ? err.message
+              : (typeof err === 'object' && err !== null
+                ? JSON.stringify(err, null, 2)
+                : String(err));
+            reject(new Error(`COS upload failed: ${detail}`));
+            return;
+          }
+          resolve({ docId, key, status: 'uploaded' });
+        },
+      );
+    });
+  }
+
+  /**
+   * Batch upload multiple items in parallel (with concurrency limit).
+   *
+   * Individual upload failures are captured per-item (status='error')
+   * instead of aborting the entire batch — this prevents one bad item
+   * from causing all remaining items to be dropped.
+   */
+  async uploadBatch(
+    items: Array<{ content: string; opts?: CloudUploadOptions }>,
+    concurrency = 5,
+  ): Promise<CloudUploadResult[]> {
+    const results: CloudUploadResult[] = [];
+    const queue = [...items];
+
+    const worker = async (): Promise<void> => {
+      while (queue.length > 0) {
+        const item = queue.shift();
+        if (!item) {
+          break;
+        }
+        try {
+          const result = await this.upload(item.content, item.opts);
+          results.push(result);
+        } catch (err) {
+          // Record the failure but continue processing remaining items
+          results.push({
+            docId: item.opts?.docId ?? 'unknown',
+            key: '',
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    };
+
+    const workers = Array.from(
+      { length: Math.min(concurrency, items.length) },
+      () => worker(),
+    );
+    await Promise.all(workers);
+    return results;
+  }
+
+  // ==========================================================================
+  // Upload Binary — COS putObject for images and binary files
+  // ==========================================================================
+
+  /**
+   * Upload a binary file (e.g. image) to the COS bucket.
+   *
+   * Unlike `upload()` which stores text content as Markdown, this method
+   * accepts a Buffer and stores the file with its original content type.
+   * The file is placed under the provided COS key path.
+   *
+   * @param buffer    Raw file content as a Buffer.
+   * @param key       Full COS key (e.g. "openclaw-main/asset/photo.png").
+   * @param contentType  MIME type (e.g. "image/png"). Default: "application/octet-stream".
+   * @param metadata  Optional metadata to attach as COS custom headers.
+   * @returns Upload result with the COS key.
+   */
+  async uploadBinary(
+    buffer: Buffer,
+    key: string,
+    contentType = 'application/octet-stream',
+    metadata?: Record<string, unknown>,
+  ): Promise<CloudUploadResult> {
+    const headers: Record<string, string> = {
+      'Content-Type': contentType,
+      'x-cos-meta-category': 'image',
+      'x-cos-meta-created-at': new Date().toISOString(),
+    };
+
+    if (metadata) {
+      for (const [k, v] of Object.entries(metadata)) {
+        const headerKey = `x-cos-meta-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+        headers[headerKey] = typeof v === 'string' ? v : JSON.stringify(v);
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      this.cos.putObject(
+        {
+          Bucket: this.config.bucket,
+          Region: this.config.region,
+          Key: key,
+          Body: buffer,
+          Headers: headers,
+        } as never,
+        (err: unknown) => {
+          if (err) {
+            const detail = err instanceof Error
+              ? err.message
+              : (typeof err === 'object' && err !== null
+                ? JSON.stringify(err, null, 2)
+                : String(err));
+            reject(new Error(`COS binary upload failed for "${key}": ${detail}`));
+            return;
+          }
+          resolve({ docId: key, key, status: 'uploaded' });
+        },
+      );
+    });
+  }
+
+  /**
+   * Check whether a COS object exists at the given key.
+   *
+   * Uses `headObject` which returns metadata without downloading the body.
+   * Returns true if the object exists, false otherwise.
+   */
+  async objectExists(key: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      this.cos.headObject(
+        {
+          Bucket: this.config.bucket,
+          Region: this.config.region,
+          Key: key,
+        },
+        (err: unknown) => {
+          if (err) {
+            resolve(false);
+            return;
+          }
+          resolve(true);
+        },
+      );
+    });
+  }
+
+  // ==========================================================================
+  // Download — COS getObject
+  // ==========================================================================
+
+  /**
+   * Download a document from the COS bucket by its key.
+   *
+   * @param docKey  Full COS key (e.g. "memory/memory/abc.md") or a short docId.
+   *                If a short docId is provided, it will be resolved via the dataset cosPrefix.
+   */
+  async download(docKey: string, opts?: CloudDownloadOptions): Promise<CloudDownloadResult> {
+    const dataset = this.resolveDataset(opts?.category);
+
+    // Determine if docKey is a full COS key or a short docId.
+    // A full key starts with one of the known dataset cosPrefixes.
+    // Short docIds are resolved via `{cosPrefix}{sanitizedDocId}.md`.
+    // We do NOT use `includes('/')` because docIds can contain `/`
+    // (e.g. "category:IMAP/SMTP Email Tool").
+    const isFullKey = this.config.datasets.some(
+      (ds) => docKey.startsWith(ds.cosPrefix),
+    );
+    const key = isFullKey
+      ? docKey
+      : `${dataset.cosPrefix}${sanitizeDocId(docKey)}.md`;
+
+    return new Promise((resolve, reject) => {
+      this.cos.getObject(
+        {
+          Bucket: this.config.bucket,
+          Region: this.config.region,
+          Key: key,
+        },
+        (err: unknown, data: unknown) => {
+          if (err) {
+            reject(new Error(`COS download failed for "${key}": ${String(err)}`));
+            return;
+          }
+
+          const raw = data as Record<string, unknown>;
+          const body = typeof raw.Body === 'string'
+            ? raw.Body
+            : raw.Body instanceof Buffer
+              ? (raw.Body as Buffer).toString('utf-8')
+              : String(raw.Body ?? '');
+
+          // Extract metadata from COS custom headers (x-cos-meta-*)
+          const headers = (raw.headers ?? {}) as Record<string, string>;
+          const metadata: Record<string, unknown> = {};
+          for (const [hk, hv] of Object.entries(headers)) {
+            if (hk.startsWith('x-cos-meta-')) {
+              const metaKey = hk.slice('x-cos-meta-'.length);
+              metadata[metaKey] = hv;
+            }
+          }
+
+          // Backward compatibility: try to parse as old JSON wrapper format
+          try {
+            const parsed = JSON.parse(body) as Record<string, unknown>;
+            if (typeof parsed.content === 'string') {
+              resolve({
+                content: parsed.content,
+                key,
+                metadata: (parsed.metadata ?? metadata) as Record<string, unknown>,
+              });
+              return;
+            }
+          } catch {
+            // Not JSON — this is the expected path for .md files
+          }
+
+          resolve({ content: body, key, metadata });
+        },
+      );
+    });
+  }
+
+  // ==========================================================================
+  // Delete — COS deleteObject
+  // ==========================================================================
+
+  /**
+   * Delete a document from the COS bucket.
+   *
+   * @param docKey  Full COS key or short docId (resolved via dataset cosPrefix).
+   */
+  async deleteDoc(docKey: string, opts?: CloudDownloadOptions): Promise<{ deleted: boolean; key: string }> {
+    const dataset = this.resolveDataset(opts?.category);
+
+    // Same logic as download: detect full key by cosPrefix, not by `/`.
+    const isFullKey = this.config.datasets.some(
+      (ds) => docKey.startsWith(ds.cosPrefix),
+    );
+    const key = isFullKey
+      ? docKey
+      : `${dataset.cosPrefix}${sanitizeDocId(docKey)}.md`;
+
+    return new Promise((resolve, reject) => {
+      this.cos.deleteObject(
+        {
+          Bucket: this.config.bucket,
+          Region: this.config.region,
+          Key: key,
+        },
+        (err: unknown) => {
+          if (err) {
+            reject(new Error(`COS delete failed for "${key}": ${String(err)}`));
+            return;
+          }
+          resolve({ deleted: true, key });
+        },
+      );
+    });
+  }
+
+  // ==========================================================================
+  // Accessors
+  // ==========================================================================
+
+  /** Get the resolved COS config (useful for diagnostics). */
+  getConfig(): ResolvedCosConfig {
+    return this.config;
+  }
+
+  /** Get all available dataset names. */
+  getDatasetNames(): string[] {
+    return this.config.datasets.map((ds) => ds.name);
+  }
+
+  /**
+   * Get the agent-level COS key prefix (without trailing "/workspace/").
+   *
+   * For multi-agent setups (agentId set), this returns `openclaw-{agentId}/`.
+   * For legacy setups (no agentId), this returns an empty string.
+   *
+   * Useful for placing files alongside the workspace directory rather than
+   * inside it. E.g. workspace files like AGENTS.md should go to
+   * `openclaw-{agentId}/agents.md` (agent root) instead of
+   * `openclaw-{agentId}/workspace/agents.md` (inside workspace).
+   */
+  getAgentPrefix(): string {
+    if (this.config.agentId) {
+      return `openclaw-${this.config.agentId}/`;
+    }
+    return '';
+  }
+
+  // ==========================================================================
+  // Signed URL — generate a temporary access URL for a COS object
+  // ==========================================================================
+
+  /**
+   * Generate a signed (temporary) download URL for a COS object.
+   *
+   * @param cosUri  Full COS URI (e.g. `cos://bucket-123/image/photo.jpg`)
+   *                or a plain COS key (e.g. `image/photo.jpg`).
+   * @param expiresInSeconds  URL validity duration. Default: 3600 (1 hour).
+   * @returns A signed HTTPS URL that can be used to access the object.
+   */
+  getSignedUrl(cosUri: string, expiresInSeconds = 3600): string {
+    // Extract the COS key from a `cos://bucket/key` URI
+    const key = cosUri.startsWith('cos://')
+      ? cosUri.replace(/^cos:\/\/[^/]+\//, '')
+      : cosUri;
+
+    return this.cos.getObjectUrl({
+      Bucket: this.config.bucket,
+      Region: this.config.region,
+      Key: key,
+      Sign: true,
+      Expires: expiresInSeconds,
+    }) as unknown as string;
+  }
+
+  // ==========================================================================
+  // Private: result mapping helpers
+  // ==========================================================================
+
+  /**
+   * Map CI DocSearch results to CloudSearchResult[].
+   */
+  private mapDocResults(
+    items: DocResultItem[] | undefined,
+    category?: string,
+  ): CloudSearchResult[] {
+    if (!items || items.length === 0) {
+      return [];
+    }
+
+    return items.map((item) => ({
+      snippet: item.Text ?? '',
+      score: (item.Score ?? 0) / 100, // Normalize 0-100 → 0-1
+      docId: item.URI ? this.cosUriToDocId(item.URI) : undefined,
+      category: (category as CloudSearchResult['category']) ?? 'document',
+      metadata: {
+        uri: item.URI,
+        textPage: item.TextPage,
+        imageUrls: item.ImageUrls,
+      },
+    }));
+  }
+
+  /**
+   * Map CI ImageSearch results to CloudSearchResult[].
+   * Each result includes a signed URL for direct image access.
+   */
+  private mapImageResults(
+    items: ImageResultItem[] | undefined,
+    category?: string,
+  ): CloudSearchResult[] {
+    if (!items || items.length === 0) {
+      return [];
+    }
+
+    return items.map((item) => {
+      const uri = item.URI ?? '';
+      const signedUrl = uri ? this.getSignedUrl(uri) : undefined;
+
+      return {
+        snippet: `[image] ${uri || 'unknown'}`,
+        score: (item.Score ?? 0) / 100, // Normalize 0-100 → 0-1
+        docId: uri ? this.cosUriToDocId(uri) : undefined,
+        category: (category as CloudSearchResult['category']) ?? 'document',
+        imageUrl: signedUrl,
+        metadata: {
+          uri,
+        },
+      };
+    });
+  }
+
+  /**
+   * Extract a short doc ID from a COS URI.
+   * e.g. `cos://bucket-123/memory/abc.md` → `abc.md`
+   * e.g. `cos://bucket-123/memory/IMAP__SMTP Email Tool.md`
+   *     → `IMAP/SMTP Email Tool.md`
+   *
+   * Note: docIds stored on COS have `/` replaced with `__` (see `sanitizeDocId`).
+   * This method reverses that transformation so callers see the original name.
+   */
+  private cosUriToDocId(uri: string): string {
+    // Remove cos:// scheme and bucket name
+    const withoutScheme = uri.replace(/^cos:\/\/[^/]+\//, '');
+    // Remove known dataset prefixes
+    for (const ds of this.config.datasets) {
+      if (withoutScheme.startsWith(ds.cosPrefix)) {
+        return unsanitizeDocId(withoutScheme.slice(ds.cosPrefix.length));
+      }
+    }
+    return unsanitizeDocId(withoutScheme);
+  }
+}