metainsight-context-engine 0.0.8 → 0.0.9

package/cos-bootstrap.ts

@@ -0,0 +1,864 @@
+/**
+ * COS Bootstrap — Infrastructure Initialization
+ *
+ * Ensures all preconditions for the Cloud Context Engine are met before
+ * the engine starts processing requests:
+ *
+ *   1. COS SDK instance is initialized (SecretId / SecretKey auth)
+ *   2. Target bucket exists (headBucket → putBucket if missing)
+ *   3. For each dataset definition:
+ *      a. Dataset exists (GET /dataset → POST /dataset if missing)
+ *      b. Dataset ↔ Bucket binding exists (GET /datasetbinding → POST /datasetbinding if missing)
+ *
+ * The module supports **multiple datasets** per bucket — each dataset has its
+ * own COS path prefix and CI template. The default setup includes a "memory"
+ * dataset (DocSearch) and an "image" dataset (ImageSearch) for multimodal
+ * retrieval. Users can extend it with "knowledge" or any custom datasets.
+ *
+ * **Multi-agent isolation**: When `agentId` is set, the default cosPrefix
+ * becomes `openclaw-{agentId}/workspace/memory/`. This allows multiple
+ * agents to share the same bucket without data collisions.
+ *
+ * The module also exposes a generic `sendCIRequest()` helper for CI API
+ * calls (used by cos-operations.ts for hybridsearch, upload, etc.).
+ *
+ * Supported regions: ap-beijing, ap-shanghai, ap-chengdu
+ *
+ * @example
+ * ```ts
+ * // Minimal — uses default datasets (memory)
+ * bootstrap({ secretId, secretKey, appId: '1253311026' }, logger);
+ *
+ * // Extended — add a custom knowledge dataset alongside defaults
+ * bootstrap({
+ *   secretId, secretKey,
+ *   appId: '1253311026',
+ *   datasets: [
+ *     { name: 'my-memory',    cosPrefix: 'memory/',    templateId: 'Official:DocSearch' },
+ *     { name: 'my-knowledge', cosPrefix: 'knowledge/', templateId: 'Official:DocSearch' },
+ *   ],
+ * }, logger);
+ * ```
+ */
+
+// cos-nodejs-sdk-v5 uses `export = COS` (CJS style)
+import COS from 'cos-nodejs-sdk-v5';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Definition for a single dataset that should be bootstrapped.
+ *
+ * - `name`        — CI dataset name (unique within the APPID scope)
+ * - `cosPrefix`   — COS key prefix the binding should cover (e.g. "memory/")
+ * - `templateId`  — CI dataset template (default: "Official:DocSearch")
+ * - `description` — Human-readable description used when auto-creating
+ */
+export interface DatasetDefinition {
+  /** CI dataset name (e.g. "openclaw-memory"). */
+  name: string;
+  /**
+   * COS key prefix that the binding covers.
+   * Must end with "/" (e.g. "memory/").
+   */
+  cosPrefix: string;
+  /** CI dataset template (default: "Official:DocSearch"). */
+  templateId?: string;
+  /** Description applied when auto-creating the dataset. */
+  description?: string;
+}
+
+export interface CosBootstrapConfig {
+  secretId: string;
+  secretKey: string;
+  /**
+   * Tencent Cloud APPID (e.g. "1253311026").
+   * Obtain from https://console.cloud.tencent.com/cam/capi
+   */
+  appId: string;
+  /**
+   * Agent ID for multi-agent isolation within a single bucket.
+   *
+   * When set, the default cosPrefix becomes:
+   *   `openclaw-{agentId}/workspace/memory/`
+   *
+   * Typically resolved by the plugin entry point (index.ts) with priority:
+   *   1. User-configured cfg.agentId
+   *   2. Hook ctx.agentId (auto-detected at runtime)
+   *   3. Fallback: 'main'
+   *
+   * When omitted here, the legacy flat prefix `memory/` is used
+   * (only happens if the caller does not resolve agentId beforehand).
+   */
+  agentId?: string;
+  /** COS bucket short name without APPID suffix (e.g. "openclaw-metainsight"). */
+  bucket?: string;
+  /** COS region — only ap-beijing / ap-shanghai / ap-chengdu are supported. */
+  region?: string;
+  /**
+   * Dataset definitions to bootstrap.
+   *
+   * When omitted, three default datasets are created:
+   * ```
+   * [
+   *   { name: "openclaw-memory",   cosPrefix: "memory/",  templateId: "Official:DocSearch" },
+   *   { name: "openclaw-image",    cosPrefix: "asset/",   templateId: "Official:ImageSearch" },
+   *   { name: "openclaw-document", cosPrefix: "asset/",   templateId: "Official:DocSearch" },
+   * ]
+   * ```
+   *
+   * When `agentId` is set and datasets are omitted, the defaults become:
+   * ```
+   * [
+   *   { name: "openclaw-memory-{agentId}",   cosPrefix: "openclaw-{agentId}/workspace/", ... },
+   *   { name: "openclaw-{agentId}-image",     cosPrefix: "openclaw-{agentId}/asset/",     ... },
+   *   { name: "openclaw-{agentId}-document",  cosPrefix: "openclaw-{agentId}/asset/",     ... },
+   * ]
+   * ```
+   *
+   * To add more datasets (e.g. knowledge), supply the full array:
+   * ```
+   * [
+   *   { name: "openclaw-memory",    cosPrefix: "memory/" },
+   *   { name: "openclaw-image",     cosPrefix: "asset/", templateId: "Official:ImageSearch" },
+   *   { name: "openclaw-document",  cosPrefix: "asset/" },
+   *   { name: "openclaw-knowledge", cosPrefix: "knowledge/" },
+   * ]
+   * ```
+   */
+  datasets?: DatasetDefinition[];
+}
+
+export interface ResolvedDataset {
+  /** CI dataset name. */
+  name: string;
+  /** COS key prefix the binding covers (e.g. "memory/"). */
+  cosPrefix: string;
+  /** CI dataset template. */
+  templateId: string;
+  /** Dataset description. */
+  description: string;
+}
+
+export interface ResolvedCosConfig {
+  secretId: string;
+  secretKey: string;
+  appId: string;
+  /** Agent ID for multi-agent isolation (undefined = legacy flat layout). */
+  agentId?: string;
+  /** Full bucket name in COS format: "{shortName}-{APPID}" */
+  bucket: string;
+  region: string;
+  /** All datasets to bootstrap (always ≥ 1). */
+  datasets: ResolvedDataset[];
+}
+
+/** Subset of Dataset info returned by CI API. */
+export interface DatasetInfo {
+  DatasetName?: string;
+  Description?: string;
+  TemplateId?: string;
+  [key: string]: unknown;
+}
+
+/** Subset of Binding info returned by CI API. */
+export interface DatasetBinding {
+  DatasetName?: string;
+  URI?: string;
+  State?: string;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Logger (subset)
+// ============================================================================
+
+interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+}
+
+// ============================================================================
+// Error serialization helper
+// ============================================================================
+
+/**
+ * Convert an unknown error value into a human-readable string.
+ *
+ * COS SDK often throws plain objects like `{statusCode, code, message, resource}`
+ * instead of Error instances. `String(obj)` on these produces `[object Object]`.
+ * This helper extracts the most useful fields for logging/error messages.
+ */
+function serializeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === 'string') {
+    return err;
+  }
+  if (typeof err === 'object' && err !== null) {
+    const obj = err as Record<string, unknown>;
+    const parts: string[] = [];
+    if (obj.code) {
+      parts.push(`code=${String(obj.code)}`);
+    }
+    if (obj.statusCode) {
+      parts.push(`status=${String(obj.statusCode)}`);
+    }
+    if (obj.message) {
+      parts.push(String(obj.message));
+    }
+    if (obj.resource) {
+      parts.push(`resource=${String(obj.resource)}`);
+    }
+    return parts.length > 0 ? parts.join(', ') : JSON.stringify(err);
+  }
+  return String(err);
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const SUPPORTED_REGIONS = ['ap-beijing', 'ap-shanghai', 'ap-chengdu'];
+
+/**
+ * Default datasets (no agentId):
+ *   - "openclaw-memory"   → COS prefix `memory/` (conversation memory documents, DocSearch)
+ *   - "openclaw-image"    → COS prefix `asset/`  (image retrieval dataset, ImageSearch)
+ *   - "openclaw-document" → COS prefix `asset/`  (document retrieval dataset, DocSearch)
+ */
+const DEFAULT_DATASETS: DatasetDefinition[] = [
+  {
+    name: 'openclaw-memory',
+    cosPrefix: 'memory/',
+    templateId: 'Official:DocSearch',
+    description: 'OpenClaw Cloud Context Engine — memory document search dataset',
+  },
+  {
+    name: 'openclaw-image',
+    cosPrefix: 'asset/',
+    templateId: 'Official:ImageSearch',
+    description: 'OpenClaw Cloud Context Engine — image search dataset',
+  },
+  {
+    name: 'openclaw-document',
+    cosPrefix: 'asset/',
+    templateId: 'Official:DocSearch',
+    description: 'OpenClaw Cloud Context Engine — document retrieval dataset',
+  },
+];
+
+const DEFAULTS = {
+  bucket: 'openclaw-metainsight',
+  region: 'ap-beijing',
+} as const;
+
+// ============================================================================
+// Singleton COS instance (per secretId)
+// ============================================================================
+
+let cosInstance: COS | null = null;
+let lastSecretId = '';
+
+/**
+ * Get (or create) the COS SDK singleton.
+ */
+export function getCOSInstance(secretId: string, secretKey: string): COS {
+  if (cosInstance && lastSecretId === secretId) {
+    return cosInstance;
+  }
+  cosInstance = new COS({
+    SecretId: secretId,
+    SecretKey: secretKey,
+  });
+  lastSecretId = secretId;
+  return cosInstance;
+}
+
+// ============================================================================
+// Config resolution
+// ============================================================================
+
+/**
+ * Merge user-provided config with defaults, validate region.
+ *
+ * The bucket name is automatically resolved to COS format: `{shortName}-{APPID}`.
+ * If the user-provided bucket already contains the APPID suffix, it is used as-is.
+ *
+ * When `datasets` is omitted, three default datasets are created (memory, image, document).
+ * Each dataset's `cosPrefix` is normalized to end with "/".
+ */
+export function resolveConfig(input: CosBootstrapConfig): ResolvedCosConfig {
+  const region = input.region ?? DEFAULTS.region;
+
+  if (!SUPPORTED_REGIONS.includes(region)) {
+    throw new Error(
+      `cos-bootstrap: unsupported region "${region}". Supported: ${SUPPORTED_REGIONS.join(', ')}`,
+    );
+  }
+
+  if (!input.appId) {
+    throw new Error(
+      'cos-bootstrap: "appId" is required. '
+      + 'Obtain from https://console.cloud.tencent.com/cam/capi',
+    );
+  }
+
+  const shortBucket = input.bucket ?? DEFAULTS.bucket;
+  // If bucket already ends with `-{appId}`, use as-is; otherwise append
+  const bucket = shortBucket.endsWith(`-${input.appId}`)
+    ? shortBucket
+    : `${shortBucket}-${input.appId}`;
+
+  // Resolve datasets — use defaults when omitted.
+  // When agentId is set and no explicit datasets are provided, the default
+  // cosPrefix becomes `openclaw-{agentId}/workspace/memory/` for multi-agent isolation.
+  const agentId = input.agentId?.trim();
+  let rawDatasets: DatasetDefinition[];
+
+  if (input.datasets && input.datasets.length > 0) {
+    rawDatasets = input.datasets;
+  } else if (agentId) {
+    rawDatasets = [
+      {
+        name: `openclaw-${agentId}-memory`,
+        cosPrefix: `openclaw-${agentId}/workspace/`,
+        templateId: 'Official:DocSearch',
+        description: `OpenClaw Cloud Context Engine — memory dataset for agent "${agentId}"`,
+      },
+      {
+        name: `openclaw-${agentId}-image`,
+        cosPrefix: `openclaw-${agentId}/asset/`,
+        templateId: 'Official:ImageSearch',
+        description: `OpenClaw Cloud Context Engine — image search dataset for agent "${agentId}"`,
+      },
+      {
+        name: `openclaw-${agentId}-document`,
+        cosPrefix: `openclaw-${agentId}/asset/`,
+        templateId: 'Official:DocSearch',
+        description: `OpenClaw Cloud Context Engine — document retrieval dataset for agent "${agentId}"`,
+      },
+    ];
+  } else {
+    rawDatasets = DEFAULT_DATASETS;
+  }
+
+  const datasets: ResolvedDataset[] = rawDatasets.map((ds) => {
+    if (!ds.name) {
+      throw new Error('cos-bootstrap: each dataset must have a non-empty "name"');
+    }
+    // Ensure cosPrefix ends with "/"
+    let cosPrefix = ds.cosPrefix || `${ds.name}/`;
+    if (!cosPrefix.endsWith('/')) {
+      cosPrefix = `${cosPrefix}/`;
+    }
+    return {
+      name: ds.name,
+      cosPrefix,
+      templateId: ds.templateId ?? 'Official:DocSearch',
+      description: ds.description ?? `OpenClaw dataset — ${ds.name}`,
+    };
+  });
+
+  // Validate no duplicate dataset names
+  const names = new Set<string>();
+  for (const ds of datasets) {
+    if (names.has(ds.name)) {
+      throw new Error(`cos-bootstrap: duplicate dataset name "${ds.name}"`);
+    }
+    names.add(ds.name);
+  }
+
+  return {
+    secretId: input.secretId,
+    secretKey: input.secretKey,
+    appId: input.appId,
+    agentId: agentId || undefined,
+    bucket,
+    region,
+    datasets,
+  };
+}
+
+// ============================================================================
+// Generic CI API helper
+// ============================================================================
+
+/**
+ * Construct the CI host for a given bucket and region.
+ * Format: `{bucket}.ci.{region}.myqcloud.com`
+ */
+function getCIHost(bucket: string, region: string): string {
+  return `${bucket}.ci.${region}.myqcloud.com`;
+}
+
+/**
+ * Send a request to the COS CI API with automatic SDK signing.
+ *
+ * @param cos    COS SDK instance
+ * @param bucket Bucket name
+ * @param region COS region
+ * @param method HTTP method (GET / POST / PUT / DELETE)
+ * @param endpoint  CI API endpoint path (e.g. "dataset", "datasetbinding", "datasetquery/hybridsearch")
+ * @param body   Optional JSON request body
+ * @param query  Optional query string parameters
+ * @returns Parsed JSON response
+ */
+export async function sendCIRequest(
+  cos: COS,
+  bucket: string,
+  region: string,
+  method: string,
+  endpoint: string,
+  body?: Record<string, unknown>,
+  query?: Record<string, string>,
+): Promise<unknown> {
+  const host = getCIHost(bucket, region);
+  const url = `https://${host}/${endpoint}`;
+
+  const requestConfig: Record<string, unknown> = {
+    Method: method,
+    Key: endpoint,
+    Url: url,
+    Headers: {
+      'Accept': 'application/json',
+    },
+  };
+
+  if (query && Object.keys(query).length > 0) {
+    requestConfig.Query = query;
+  }
+
+  if (body) {
+    (requestConfig.Headers as Record<string, string>)['Content-Type'] = 'application/json';
+    requestConfig.Body = JSON.stringify(body);
+  }
+
+  return new Promise((resolve, reject) => {
+    cos.request(requestConfig as never, (err: unknown, data: unknown) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+
+      // Attempt to parse JSON body if the response is a string
+      const raw = data as Record<string, unknown> | undefined;
+      if (raw && typeof raw.Body === 'string') {
+        try {
+          resolve(JSON.parse(raw.Body as string));
+          return;
+        } catch {
+          // fallback — return raw
+        }
+      }
+      resolve(raw);
+    });
+  });
+}
+
+// ============================================================================
+// Simple retry helper
+// ============================================================================
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  retries = 2,
+  delayMs = 1000,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries) {
+        await new Promise((r) => setTimeout(r, delayMs * (attempt + 1)));
+      }
+    }
+  }
+  throw lastError;
+}
+
+// ============================================================================
+// Simple cache (TTL-based)
+// ============================================================================
+
+const cache = new Map<string, { data: unknown; expiresAt: number }>();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function getCachedData<T>(key: string): T | null {
+  const entry = cache.get(key);
+  if (entry && entry.expiresAt > Date.now()) {
+    return entry.data as T;
+  }
+  cache.delete(key);
+  return null;
+}
+
+function setCachedData(key: string, data: unknown): void {
+  cache.set(key, { data, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+// ============================================================================
+// Bucket operations
+// ============================================================================
+
+/**
+ * Check whether the target bucket exists.
+ */
+async function doesBucketExist(cos: COS, bucket: string, region: string): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    cos.headBucket(
+      { Bucket: bucket, Region: region },
+      (err: unknown) => {
+        if (!err) {
+          resolve(true);
+          return;
+        }
+        // Distinguish "not found" from transient server errors
+        const error = err as Record<string, unknown>;
+        const statusCode = error.statusCode as number | undefined;
+        if (statusCode === 404 || statusCode === 403) {
+          // 404 = not found; 403 = exists but no permission (treat as not found for creation)
+          resolve(false);
+          return;
+        }
+        // 500 / network errors should bubble up rather than falsely claiming "not found"
+        reject(new Error(`cos-bootstrap: headBucket failed: ${serializeError(err)}`));
+      },
+    );
+  });
+}
+
+/**
+ * Create a new COS bucket.
+ *
+ * `BucketAlreadyOwnedByYou` is treated as success — it means the bucket
+ * already exists and is owned by this account (common race condition when
+ * multiple callers bootstrap concurrently).
+ */
+async function createBucket(cos: COS, bucket: string, region: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    cos.putBucket(
+      { Bucket: bucket, Region: region },
+      (err: unknown) => {
+        if (err) {
+          // BucketAlreadyOwnedByYou means we already own it — treat as success
+          const errStr = serializeError(err);
+          if (errStr.includes('BucketAlreadyOwnedByYou') || errStr.includes('BucketAlreadyExists')) {
+            resolve();
+            return;
+          }
+          reject(new Error(`cos-bootstrap: failed to create bucket "${bucket}": ${errStr}`));
+          return;
+        }
+        resolve();
+      },
+    );
+  });
+}
+
+// ============================================================================
+// Dataset operations
+// ============================================================================
+
+/**
+ * Query dataset info (with cache).
+ */
+async function getDatasetInfo(
+  cos: COS,
+  bucket: string,
+  region: string,
+  datasetName: string,
+): Promise<DatasetInfo | null> {
+  const cacheKey = `dataset-info-${datasetName}`;
+
+  const cached = getCachedData<DatasetInfo>(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  try {
+    const result = await withRetry(async () => {
+      return await sendCIRequest(cos, bucket, region, 'GET', 'dataset', undefined, {
+        datasetname: datasetName,
+        statistics: 'true',
+      });
+    });
+
+    // Handle various response shapes from CI API
+    const res = result as Record<string, unknown>;
+    let datasetInfo: DatasetInfo | null = null;
+
+    const response = res.Response as Record<string, unknown> | undefined;
+    if (response?.Dataset) {
+      datasetInfo = response.Dataset as DatasetInfo;
+    } else if (res.Dataset) {
+      datasetInfo = res.Dataset as DatasetInfo;
+    } else if (res.DatasetName) {
+      datasetInfo = res as unknown as DatasetInfo;
+    }
+
+    if (datasetInfo) {
+      setCachedData(cacheKey, datasetInfo);
+    }
+
+    return datasetInfo;
+  } catch (err) {
+    // 404 / 400 / not found → dataset doesn't exist (400 can occur when bucket is freshly created)
+    const error = err as Record<string, unknown>;
+    const statusCode = error.statusCode as number | undefined;
+    const code = error.code as string | undefined;
+    const msg = typeof error.message === 'string' ? error.message : '';
+    if (
+      msg.includes('404')
+      || statusCode === 404
+      || statusCode === 400
+      || code === 'NoSuchDataset'
+    ) {
+      return null;
+    }
+    throw new Error(`cos-bootstrap: failed to query dataset "${datasetName}": ${serializeError(err)}`);
+  }
+}
+
+/**
+ * Create a new CI dataset.
+ */
+async function createDataset(
+  cos: COS,
+  bucket: string,
+  region: string,
+  datasetName: string,
+  templateId: string,
+  description: string,
+): Promise<DatasetInfo> {
+  // CI API may return 400/500 right after bucket creation; retry with backoff.
+  const result = await withRetry(async () => {
+    return await sendCIRequest(cos, bucket, region, 'POST', 'dataset', {
+      DatasetName: datasetName,
+      Description: description,
+      TemplateId: templateId,
+    });
+  }, 2, 2000);
+
+  const res = result as Record<string, unknown>;
+  const response = res.Response as Record<string, unknown> | undefined;
+
+  return (response?.Dataset ?? res.Dataset ?? res) as DatasetInfo;
+}
+
+// ============================================================================
+// Dataset binding operations
+// ============================================================================
+
+/**
+ * Query dataset ↔ bucket binding (with cache).
+ *
+ * @param cosPrefix  COS key prefix the binding covers (e.g. "memory/")
+ */
+async function getDatasetBinding(
+  cos: COS,
+  bucket: string,
+  region: string,
+  datasetName: string,
+  cosPrefix: string,
+): Promise<DatasetBinding | null> {
+  const uri = `cos://${bucket}/${cosPrefix}`;
+  const cacheKey = `binding-${datasetName}-${bucket}-${cosPrefix}`;
+
+  const cached = getCachedData<DatasetBinding>(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  try {
+    const result = await withRetry(async () => {
+      return await sendCIRequest(cos, bucket, region, 'GET', 'datasetbinding', undefined, {
+        datasetname: datasetName,
+        uri,
+      });
+    });
+
+    const res = result as Record<string, unknown>;
+    let binding: DatasetBinding | null = null;
+
+    const response = res.Response as Record<string, unknown> | undefined;
+    if (response?.Binding) {
+      binding = response.Binding as DatasetBinding;
+    } else if (res.Binding) {
+      binding = res.Binding as DatasetBinding;
+    } else if (res.State) {
+      binding = res as unknown as DatasetBinding;
+    }
+
+    if (binding) {
+      setCachedData(cacheKey, binding);
+    }
+
+    return binding;
+  } catch (err) {
+    const error = err as Record<string, unknown>;
+    const statusCode = error.statusCode as number | undefined;
+    const code = error.code as string | undefined;
+    if (code === 'NoSuchBinding' || statusCode === 404 || statusCode === 400) {
+      return null;
+    }
+    throw new Error(
+      `cos-bootstrap: failed to query dataset binding "${datasetName}": ${serializeError(err)}`,
+    );
+  }
+}
+
+/**
+ * Create dataset ↔ bucket binding.
+ *
+ * @param cosPrefix  COS key prefix the binding covers (e.g. "memory/")
+ */
+async function createDatasetBinding(
+  cos: COS,
+  bucket: string,
+  region: string,
+  datasetName: string,
+  cosPrefix: string,
+): Promise<DatasetBinding> {
+  // CI API may return 400/500 if dataset was just created; retry with backoff.
+  const result = await withRetry(async () => {
+    return await sendCIRequest(cos, bucket, region, 'POST', 'datasetbinding', {
+      DatasetName: datasetName,
+      URI: `cos://${bucket}/${cosPrefix}`,
+      Mode: 1,
+    });
+  }, 2, 2000);
+
+  const res = result as Record<string, unknown>;
+  const response = res.Response as Record<string, unknown> | undefined;
+
+  return (response?.Binding ?? res.Binding ?? res) as DatasetBinding;
+}
+
+// ============================================================================
+// Main bootstrap entry point
+// ============================================================================
+
+/** Per-dataset bootstrap result. */
+export interface DatasetOutcome {
+  name: string;
+  cosPrefix: string;
+  datasetCreated: boolean;
+  bindingCreated: boolean;
+}
+
+export interface BootstrapOutcome {
+  success: boolean;
+  cos: COS;
+  config: ResolvedCosConfig;
+  bucketCreated: boolean;
+  /** Per-dataset results (one entry per dataset in config.datasets). */
+  datasetOutcomes: DatasetOutcome[];
+  error?: string;
+}
+
+/**
+ * Run the full bootstrap sequence:
+ *   1. Initialize COS SDK
+ *   2. Ensure bucket exists
+ *   3. For each dataset in config.datasets:
+ *      a. Ensure dataset exists (GET → POST if missing)
+ *      b. Ensure binding exists (GET → POST if missing), bound to `cos://{bucket}/{cosPrefix}`
+ *
+ * Returns a {@link BootstrapOutcome} with the COS instance and resolved config,
+ * ready for use by `CloudClient`.
+ */
+export async function bootstrap(
+  input: CosBootstrapConfig,
+  logger: Logger,
+): Promise<BootstrapOutcome> {
+  // ---- Step 0: Resolve config & create COS instance ----
+  const config = resolveConfig(input);
+  const cos = getCOSInstance(config.secretId, config.secretKey);
+
+  let bucketCreated = false;
+  const datasetOutcomes: DatasetOutcome[] = [];
+
+  try {
+    // ---- Step 1: Ensure bucket exists ----
+    const bucketExists = await doesBucketExist(cos, config.bucket, config.region);
+
+    if (!bucketExists) {
+      logger.info(`cos-bootstrap: creating bucket "${config.bucket}"...`);
+      await createBucket(cos, config.bucket, config.region);
+      bucketCreated = true;
+
+      // CI (data-processing) API may not be immediately available on a freshly
+      // created bucket. Wait a short period to reduce 400/500 errors downstream.
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+
+    // ---- Step 2: For each dataset — ensure dataset + binding ----
+    for (const ds of config.datasets) {
+      const outcome: DatasetOutcome = {
+        name: ds.name,
+        cosPrefix: ds.cosPrefix,
+        datasetCreated: false,
+        bindingCreated: false,
+      };
+
+      // 2a. Ensure dataset exists
+      const datasetInfo = await getDatasetInfo(cos, config.bucket, config.region, ds.name);
+
+      if (!datasetInfo) {
+        logger.info(`cos-bootstrap: [${ds.name}] creating dataset (template: ${ds.templateId})...`);
+        await createDataset(
+          cos,
+          config.bucket,
+          config.region,
+          ds.name,
+          ds.templateId,
+          ds.description,
+        );
+        outcome.datasetCreated = true;
+      }
+
+      // 2b. Ensure binding exists (bound to cosPrefix)
+      const binding = await getDatasetBinding(
+        cos, config.bucket, config.region, ds.name, ds.cosPrefix,
+      );
+
+      if (!binding) {
+        logger.info(`cos-bootstrap: [${ds.name}] creating binding → ${ds.cosPrefix}...`);
+        await createDatasetBinding(
+          cos, config.bucket, config.region, ds.name, ds.cosPrefix,
+        );
+        outcome.bindingCreated = true;
+      }
+
+      datasetOutcomes.push(outcome);
+    }
+
+    logger.info(`cos-bootstrap: ready ✓ (${config.datasets.length} dataset(s))`);
+
+    return {
+      success: true,
+      cos,
+      config,
+      bucketCreated,
+      datasetOutcomes,
+    };
+  } catch (err) {
+    const message = serializeError(err);
+    logger.warn(`cos-bootstrap: initialization failed: ${message}`);
+
+    return {
+      success: false,
+      cos,
+      config,
+      bucketCreated,
+      datasetOutcomes,
+      error: message,
+    };
+  }
+}