mlclaw 0.1.0

package/src/hf-bucket-client/client.ts

@@ -0,0 +1,217 @@
+/**
+ * Minimal Hugging Face Storage Bucket client.
+ *
+ * Protocol reference: huggingface_hub (Python) `HfApi._batch_bucket_files`.
+ * Buckets are non-versioned object storage; file content travels the Xet
+ * protocol (vendored from huggingface.js), then files are registered with a
+ * single NDJSON `POST /api/buckets/{id}/batch` call. Reads are plain HTTP.
+ */
+import { uploadShards } from "../vendor/hfjs-xet/utils/uploadShards.js";
+
+export const HUB_URL = "https://huggingface.co";
+
+export type BucketClientOptions = {
+  bucket: string;
+  accessToken: string;
+  hubUrl?: string;
+  fetch?: typeof fetch;
+};
+
+export type BucketEntry = {
+  path: string;
+  size: number;
+  type: "file" | "directory";
+};
+
+type BatchOperation =
+  | { type: "addFile"; path: string; xetHash: string; mtime: number; contentType?: string }
+  | { type: "deleteFile"; path: string };
+
+const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** RFC 5988 Link header, GitHub pagination style (per the Python reference). */
+function nextPageUrl(linkHeader: string | null): string | null {
+  if (!linkHeader) {
+    return null;
+  }
+  for (const part of linkHeader.split(",")) {
+    const match = part.match(/<([^>]+)>\s*;\s*rel="next"/);
+    if (match?.[1]) {
+      return match[1];
+    }
+  }
+  return null;
+}
+
+export class BucketHttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly url: string,
+    body: string,
+  ) {
+    super(`bucket request failed: ${status} ${url}: ${body.slice(0, 500)}`);
+    this.name = "BucketHttpError";
+  }
+}
+
+export class BucketClient {
+  private readonly bucket: string;
+  private readonly hubUrl: string;
+  private readonly accessToken: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: BucketClientOptions) {
+    this.bucket = options.bucket;
+    this.hubUrl = options.hubUrl ?? HUB_URL;
+    this.accessToken = options.accessToken;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  private apiUrl(suffix: string): string {
+    return `${this.hubUrl}/api/buckets/${this.bucket}${suffix}`;
+  }
+
+  private authHeaders(): Record<string, string> {
+    return { Authorization: `Bearer ${this.accessToken}` };
+  }
+
+  private async request(url: string, init?: RequestInit): Promise<Response> {
+    const response = await this.fetchWithRetry(url, init);
+    if (!response.ok) {
+      throw new BucketHttpError(response.status, url, await response.text());
+    }
+    return response;
+  }
+
+  private async fetchWithRetry(url: string, init?: RequestInit): Promise<Response> {
+    const attempts = 4;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      let response: Response;
+      try {
+        response = await this.fetchImpl(url, {
+          ...init,
+          signal: init?.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+          headers: { ...this.authHeaders(), ...init?.headers },
+        });
+      } catch (err) {
+        if (
+          attempt < attempts - 1 &&
+          err instanceof Error &&
+          (err.name === "AbortError" || err.name === "TimeoutError")
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+          continue;
+        }
+        throw err;
+      }
+      if (!RETRY_STATUSES.has(response.status) || attempt === attempts - 1) {
+        return response;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+    }
+    throw new Error("unreachable retry state");
+  }
+
+  /** Upload file contents via Xet, then register them in one batch call. */
+  async uploadFiles(files: Array<{ path: string; content: Blob }>): Promise<void> {
+    if (files.length === 0) {
+      return;
+    }
+    const hashes = new Map<string, string>();
+    const source = (async function* () {
+      for (const file of files) {
+        yield { content: file.content, path: file.path };
+      }
+    })();
+    for await (const event of uploadShards(source, {
+      accessToken: this.accessToken,
+      hubUrl: this.hubUrl,
+      // All upload traffic goes to the CAS endpoint from the write token;
+      // repo/rev are unused by the network path for buckets.
+      repo: { type: "model", name: this.bucket },
+      rev: "main",
+      xetParams: {
+        refreshWriteTokenUrl: this.apiUrl("/xet-write-token"),
+      },
+      fetch: this.fetchImpl,
+    })) {
+      if (event.event === "file") {
+        hashes.set(event.path, event.xetHash);
+      }
+    }
+    const missing = files.filter((file) => !hashes.has(file.path));
+    if (missing.length > 0) {
+      throw new Error(`xet upload returned no hash for: ${missing.map((f) => f.path).join(", ")}`);
+    }
+    await this.batch(
+      files.map((file) => ({
+        type: "addFile",
+        path: file.path,
+        xetHash: hashes.get(file.path) as string,
+        // Milliseconds, per the Python reference (`int(time.time() * 1000)`).
+        mtime: Date.now(),
+      })),
+    );
+  }
+
+  async deleteFiles(paths: string[]): Promise<void> {
+    if (paths.length === 0) {
+      return;
+    }
+    await this.batch(paths.map((path) => ({ type: "deleteFile", path })));
+  }
+
+  private async batch(operations: BatchOperation[]): Promise<void> {
+    const body = `${operations.map((op) => JSON.stringify(op)).join("\n")}\n`;
+    await this.request(this.apiUrl("/batch"), {
+      method: "POST",
+      headers: { "Content-Type": "application/x-ndjson" },
+      body,
+    });
+  }
+
+  /**
+   * Download a file. Returns null when the file does not exist; throws on
+   * any other failure (including bucket/auth errors), so a missing object is
+   * never conflated with an unreachable bucket.
+   */
+  async downloadFile(path: string): Promise<Blob | null> {
+    // The reference fully quotes the path, slashes included (`quote(safe="")`).
+    const url = `${this.hubUrl}/buckets/${this.bucket}/resolve/${encodeURIComponent(path)}`;
+    const response = await this.fetchWithRetry(url);
+    if (response.status === 404) {
+      // Distinguish "object missing" from "bucket missing/no access".
+      await this.assertBucketAccessible();
+      return null;
+    }
+    if (!response.ok) {
+      throw new BucketHttpError(response.status, url, await response.text());
+    }
+    return await response.blob();
+  }
+
+  /** List files under a prefix (recursive), following Link-header pagination. */
+  async listFiles(prefix = ""): Promise<BucketEntry[]> {
+    const entries: BucketEntry[] = [];
+    const encodedPrefix = prefix ? `/${encodeURIComponent(prefix)}` : "";
+    let url: string | null = `${this.apiUrl(`/tree${encodedPrefix}`)}?recursive=true`;
+    while (url) {
+      const response: Response = await this.request(url);
+      const page = (await response.json()) as Array<{ type: string; path: string; size?: number }>;
+      for (const item of page) {
+        entries.push({
+          path: item.path,
+          size: item.size ?? 0,
+          type: item.type === "directory" ? "directory" : "file",
+        });
+      }
+      url = nextPageUrl(response.headers.get("link"));
+    }
+    return entries;
+  }
+
+  async assertBucketAccessible(): Promise<void> {
+    await this.request(this.apiUrl(""));
+  }
+}

package/src/hf-state-sync/archive.ts

@@ -0,0 +1,137 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { promisify } from "node:util";
+import { checkIntegrity, vacuumInto } from "./sqlite.js";
+
+const execFileAsync = promisify(execFile);
+
+// Secrets live in HF Space Secrets, never in snapshots; scratch state is
+// rebuildable. These exclusions apply ONLY inside OpenClaw state dirs
+// (`.openclaw`): user workspace content is durable data no matter what it is
+// named, so a `workspace/logs/` directory must survive.
+const STATE_EXCLUDED_NAMES = new Set([".env", "credentials", "tmp", "cache", "logs"]);
+const STATE_EXCLUDED_SUFFIXES = [".log"];
+// WAL/SHM sidecars are never a durable format anywhere; live .sqlite files
+// are replaced by VACUUM INTO copies during staging.
+const SIDECAR_SUFFIXES = [".sqlite-wal", ".sqlite-shm"];
+const STATE_DIR_NAME = ".openclaw";
+
+function isExcluded(name: string, inStateDir: boolean): boolean {
+  if (SIDECAR_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
+    return true;
+  }
+  if (!inStateDir) {
+    return false;
+  }
+  return (
+    STATE_EXCLUDED_NAMES.has(name) ||
+    STATE_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix))
+  );
+}
+
+/**
+ * Walk the live tree once: copy regular files, skip excluded names, and
+ * collect live SQLite DBs for consistent copying. Discovering DBs during the
+ * same filtered walk keeps DBs under excluded dirs (e.g. cache/) out of the
+ * snapshot.
+ */
+async function copyTreeFiltered(params: {
+  sourceDir: string;
+  destDir: string;
+  databases: string[];
+  rootDir: string;
+  inStateDir: boolean;
+  depth: number;
+}): Promise<void> {
+  const { sourceDir, destDir, databases, rootDir, inStateDir, depth } = params;
+  await fs.mkdir(destDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (isExcluded(entry.name, inStateDir)) {
+      continue;
+    }
+    const source = path.join(sourceDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyTreeFiltered({
+        sourceDir: source,
+        destDir: dest,
+        databases,
+        rootDir,
+        // Only the top-level .openclaw dir is OpenClaw state; a workspace
+        // project may legitimately contain its own .openclaw directory.
+        inStateDir: inStateDir || (depth === 0 && entry.name === STATE_DIR_NAME),
+        depth: depth + 1,
+      });
+    } else if (entry.isFile()) {
+      if (entry.name.endsWith(".sqlite")) {
+        databases.push(path.relative(rootDir, source));
+      } else {
+        await fs.copyFile(source, dest);
+      }
+    } else if (entry.isSymbolicLink()) {
+      // Workspaces hold checked-out repos; dropping symlinks would restore
+      // them broken. The link target is copied verbatim, not followed.
+      await fs.symlink(await fs.readlink(source), dest);
+    }
+  }
+}
+
+export type StageResult =
+  | { kind: "staged"; databases: string[] }
+  | { kind: "corrupt-database"; database: string; detail: string };
+
+/**
+ * Stage a snapshot of the live dir: filtered file copy plus a consistent,
+ * integrity-checked VACUUM INTO copy of every live SQLite DB.
+ */
+export async function stageLiveDir(liveDir: string, stagingDir: string): Promise<StageResult> {
+  const databases: string[] = [];
+  await copyTreeFiltered({
+    sourceDir: liveDir,
+    destDir: stagingDir,
+    databases,
+    rootDir: liveDir,
+    inStateDir: false,
+    depth: 0,
+  });
+  for (const relative of databases) {
+    const staged = path.join(stagingDir, relative);
+    await fs.mkdir(path.dirname(staged), { recursive: true });
+    vacuumInto(path.join(liveDir, relative), staged);
+    const integrity = checkIntegrity(staged);
+    if (integrity.kind === "corrupt") {
+      return { kind: "corrupt-database", database: relative, detail: integrity.detail };
+    }
+  }
+  return { kind: "staged", databases };
+}
+
+// Two-step tar + zstd keeps this portable across GNU tar and bsdtar; tar's
+// --use-compress-program extraction semantics differ between them.
+export async function createTarZst(sourceDir: string, outFile: string): Promise<void> {
+  const tarFile = `${outFile}.tar`;
+  await execFileAsync("tar", ["-cf", tarFile, "-C", sourceDir, "."]);
+  await execFileAsync("zstd", ["-q", "-f", "--rm", tarFile, "-o", outFile]);
+}
+
+export async function extractTarZst(archiveFile: string, destDir: string): Promise<void> {
+  const tarFile = `${archiveFile}.extracted.tar`;
+  await execFileAsync("zstd", ["-q", "-f", "-d", archiveFile, "-o", tarFile]);
+  try {
+    await fs.mkdir(destDir, { recursive: true });
+    await execFileAsync("tar", ["-xf", tarFile, "-C", destDir]);
+  } finally {
+    await fs.rm(tarFile, { force: true });
+  }
+}
+
+export async function sha256File(file: string): Promise<string> {
+  const hash = createHash("sha256");
+  await pipeline(createReadStream(file), hash);
+  return hash.digest("hex");
+}

package/src/hf-state-sync/cli.ts

@@ -0,0 +1,92 @@
+import { createHfBucketHub } from "./hub.js";
+import type { BucketHub } from "./hub.js";
+import { log, logError, resolveSyncConfig } from "./paths.js";
+import { runRestore } from "./restore.js";
+import { runSnapshot } from "./snapshot.js";
+import { supervise } from "./supervise.js";
+
+const USAGE = `usage:
+  hf-state-sync restore
+  hf-state-sync snapshot
+  hf-state-sync supervise -- <command> [args...]`;
+
+function makeHub(bucket: string | null): BucketHub | null {
+  return bucket ? createHfBucketHub({ bucket }) : null;
+}
+
+async function main(argv: string[]): Promise<number> {
+  const config = resolveSyncConfig();
+  const hub = makeHub(config.bucket);
+  if (!hub) {
+    logError("OPENCLAW_HF_STATE_BUCKET is not set; state will NOT survive restarts");
+  }
+  const mode = argv[0];
+
+  switch (mode) {
+    case "restore": {
+      if (!hub) {
+        return 0;
+      }
+      const outcome = await runRestore({ config, hub });
+      switch (outcome.kind) {
+        case "restored":
+          return 0;
+        case "fresh-start":
+          log(`fresh start (${outcome.reason})`);
+          return 0;
+        case "invalid-manifest":
+          // Refuse to silently lose a bucket that claims to have state.
+          logError(`manifest exists but is invalid, refusing fresh start: ${outcome.reason}`);
+          return 1;
+        case "all-snapshots-failed":
+          logError(`all snapshots failed verification: ${outcome.tried.join(", ")}`);
+          return 1;
+      }
+      break;
+    }
+    case "snapshot": {
+      if (!hub) {
+        return 1;
+      }
+      const outcome = await runSnapshot({ config, hub, bootTime: new Date().toISOString() });
+      if (outcome.kind === "failed") {
+        logError(outcome.detail);
+        return 1;
+      }
+      log(`snapshot outcome: ${outcome.kind}`);
+      return 0;
+    }
+    case "supervise": {
+      const separator = argv.indexOf("--");
+      const command = separator >= 0 ? argv.slice(separator + 1) : [];
+      if (command.length === 0) {
+        logError(USAGE);
+        return 2;
+      }
+      if (!hub) {
+        // Still run the child: a Space without a bucket should serve, just
+        // without durability.
+        const { spawn } = await import("node:child_process");
+        const child = spawn(command[0] as string, command.slice(1), { stdio: "inherit" });
+        return await new Promise<number>((resolve) => {
+          process.on("SIGTERM", () => child.kill("SIGTERM"));
+          process.on("SIGINT", () => child.kill("SIGINT"));
+          child.on("exit", (code) => resolve(code ?? 1));
+        });
+      }
+      return await supervise({ config, hub, command });
+    }
+    default:
+      logError(USAGE);
+      return 2;
+  }
+  return 2;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    logError(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exit(1);
+  },
+);

package/src/hf-state-sync/hub.ts

@@ -0,0 +1,81 @@
+import fs from "node:fs/promises";
+import { BucketClient, BucketHttpError } from "../hf-bucket-client/client.js";
+
+/**
+ * Transport to the durable bucket. Implementations must be safe to call with
+ * untrusted remote state; callers verify all downloaded content separately.
+ */
+export interface BucketHub {
+  download(remotePath: string, localPath: string): Promise<"downloaded" | "not-found">;
+  upload(localPath: string, remotePath: string): Promise<void>;
+  delete(remotePaths: string[]): Promise<void>;
+}
+
+/**
+ * BucketHub backed by the shared TypeScript Storage Bucket client. Auth comes
+ * from HF_TOKEN in Space Secrets.
+ */
+export function createHfBucketHub(params: { bucket: string; token?: string }): BucketHub {
+  const token = params.token ?? process.env.HF_TOKEN;
+  if (!token) {
+    throw new Error("HF_TOKEN is required when OPENCLAW_HF_STATE_BUCKET is set");
+  }
+  const client = new BucketClient({ bucket: params.bucket, accessToken: token });
+
+  // A mistyped bucket id or a token without access also surfaces as a
+  // not-found error from resolve URLs. Treating that as "object missing" would
+  // make restore fresh-start a Space with NO durability, so a not-found is
+  // only trusted after the bucket itself proves listable.
+  let bucketAccessible = false;
+  const assertBucketAccessible = async (): Promise<void> => {
+    if (bucketAccessible) {
+      return;
+    }
+    try {
+      await client.assertBucketAccessible();
+      bucketAccessible = true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`bucket ${params.bucket} is not accessible: ${message}`);
+    }
+  };
+
+  return {
+    async download(remotePath, localPath) {
+      try {
+        const blob = await client.downloadFile(remotePath);
+        if (!blob) {
+          await assertBucketAccessible();
+          return "not-found";
+        }
+        await fs.writeFile(localPath, Buffer.from(await blob.arrayBuffer()));
+        return "downloaded";
+      } catch (err) {
+        if (err instanceof BucketHttpError && err.status === 404) {
+          await assertBucketAccessible();
+          return "not-found";
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`bucket download failed for ${remotePath}: ${message}`);
+      }
+    },
+    async upload(localPath, remotePath) {
+      try {
+        await client.uploadFiles([{ path: remotePath, content: new Blob([await fs.readFile(localPath)]) }]);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`bucket upload failed for ${remotePath}: ${message}`);
+      }
+    },
+    async delete(remotePaths) {
+      try {
+        await client.deleteFiles(remotePaths);
+      } catch (err) {
+        // Retention pruning is best-effort; a leftover file costs storage,
+        // not correctness. Never fail a snapshot over it.
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[hf-state-sync] prune failed for ${remotePaths.join(", ")}: ${message}`);
+      }
+    },
+  };
+}

package/src/hf-state-sync/manifest.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+const snapshotEntrySchema = z.object({
+  id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/),
+  path: z.string().min(1),
+  createdAt: z.string().datetime(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  sizeBytes: z.number().int().nonnegative(),
+  runId: z.string().min(1),
+  bootTime: z.string().datetime(),
+});
+
+// Buckets are non-versioned: this manifest plus the snapshot files it
+// references are the ONLY rollback path. Never drop an entry whose file
+// has not been deleted, and never delete a file that is still referenced.
+export const manifestSchema = z.object({
+  version: z.literal(1),
+  current: snapshotEntrySchema,
+  previous: z.array(snapshotEntrySchema),
+});
+
+export type SnapshotEntry = z.infer<typeof snapshotEntrySchema>;
+export type Manifest = z.infer<typeof manifestSchema>;
+
+export const MANIFEST_REMOTE_NAME = "manifest.json";
+
+export type ManifestParseResult =
+  | { kind: "ok"; manifest: Manifest }
+  | { kind: "invalid"; reason: string };
+
+export function parseManifest(raw: string): ManifestParseResult {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return { kind: "invalid", reason: `not JSON: ${String(err)}` };
+  }
+  const result = manifestSchema.safeParse(json);
+  return result.success
+    ? { kind: "ok", manifest: result.data }
+    : { kind: "invalid", reason: result.error.message };
+}
+
+export function serializeManifest(manifest: Manifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * Promote a new snapshot: previous gets the old current, truncated so the
+ * total retained count is `keep`. Returns the next manifest and the entries
+ * whose files are no longer referenced and may be deleted from the bucket.
+ */
+export function promoteSnapshot(params: {
+  existing: Manifest | null;
+  entry: SnapshotEntry;
+  keep: number;
+}): { manifest: Manifest; expired: SnapshotEntry[] } {
+  const retainedPrevious = params.existing
+    ? [params.existing.current, ...params.existing.previous]
+    : [];
+  const previous = retainedPrevious.slice(0, Math.max(params.keep - 1, 0));
+  const expired = retainedPrevious.slice(Math.max(params.keep - 1, 0));
+  return {
+    manifest: { version: 1, current: params.entry, previous },
+    expired,
+  };
+}

package/src/hf-state-sync/paths.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+
+/** Resolved runtime configuration for the state sync layer. */
+export type SyncConfig = {
+  /**
+   * Root of all durable runtime data and the snapshot/restore unit. Contains
+   * the OpenClaw state dir AND the agent workspace; snapshotting only the
+   * state dir would silently drop workspace files on every restart.
+   */
+  liveDir: string;
+  /** Bucket repo id (`owner/name`), or null when no bucket is configured. */
+  bucket: string | null;
+  /** Path prefix inside the bucket for all sync objects. */
+  bucketPrefix: string;
+  intervalSeconds: number;
+  handoffPollSeconds: number;
+  keepSnapshots: number;
+  /** Identifies this container run in manifests, for observability. */
+  runId: string;
+  /** Stable logical runtime identity used for leases and handoff. */
+  runtimeId: string;
+  agentName: string;
+  gatewayLocation: "local" | "space" | "unknown";
+  runtimeImage: string;
+};
+
+const DEFAULT_LIVE_DIR = "/tmp/openclaw-live";
+export const DEFAULT_BUCKET_PREFIX = "openclaw-state";
+const DEFAULT_INTERVAL_SECONDS = 60;
+const DEFAULT_HANDOFF_POLL_SECONDS = 5;
+const DEFAULT_KEEP = 5;
+
+function positiveIntFromEnv(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function resolveSyncConfig(env: NodeJS.ProcessEnv = process.env): SyncConfig {
+  const runId = env.MLCLAW_RUN_ID?.trim() || randomUUID();
+  return {
+    liveDir: env.OPENCLAW_LIVE_DIR?.trim() || DEFAULT_LIVE_DIR,
+    bucket: env.OPENCLAW_HF_STATE_BUCKET?.trim() || null,
+    bucketPrefix: normalizeBucketPrefix(env.OPENCLAW_HF_STATE_PREFIX),
+    intervalSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS),
+    handoffPollSeconds: positiveIntFromEnv(env.HF_STATE_SYNC_HANDOFF_POLL_SECONDS, DEFAULT_HANDOFF_POLL_SECONDS),
+    keepSnapshots: positiveIntFromEnv(env.HF_STATE_SYNC_KEEP, DEFAULT_KEEP),
+    runId,
+    runtimeId: env.MLCLAW_RUNTIME_ID?.trim() || runId,
+    agentName: env.OPENCLAW_AGENT_NAME?.trim() || "openclaw",
+    gatewayLocation: env.MLCLAW_GATEWAY_LOCATION === "local" || env.MLCLAW_GATEWAY_LOCATION === "space"
+      ? env.MLCLAW_GATEWAY_LOCATION
+      : "unknown",
+    runtimeImage: env.MLCLAW_RUNTIME_IMAGE?.trim() || "unknown",
+  };
+}
+
+/** Remote object path under the configured bucket prefix. */
+export function remotePath(config: Pick<SyncConfig, "bucketPrefix">, name: string): string {
+  return `${normalizeBucketPrefix(config.bucketPrefix)}/${name.replace(/^\/+/, "")}`;
+}
+
+export function normalizeBucketPrefix(prefix: string | undefined): string {
+  const normalized = (prefix?.trim() || DEFAULT_BUCKET_PREFIX).replace(/^\/+|\/+$/g, "");
+  return normalized || DEFAULT_BUCKET_PREFIX;
+}
+
+export function log(message: string): void {
+  console.log(`[hf-state-sync] ${message}`);
+}
+
+export function logError(message: string): void {
+  console.error(`[hf-state-sync] ${message}`);
+}