mnemospark 0.1.2

package/dist/index.js

@@ -0,0 +1,3217 @@
+// src/proxy.ts
+import { createServer } from "http";
+import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
+
+// src/balance.ts
+import { createPublicClient, http, erc20Abi } from "viem";
+import { base } from "viem/chains";
+
+// src/errors.ts
+var InsufficientFundsError = class extends Error {
+  code = "INSUFFICIENT_FUNDS";
+  currentBalanceUSD;
+  requiredUSD;
+  walletAddress;
+  constructor(opts) {
+    const msg = [
+      `Insufficient balance. Current: ${opts.currentBalanceUSD}, Required: ${opts.requiredUSD}`,
+      `Options:`,
+      `  1. Fund wallet: ${opts.walletAddress}`,
+      `  2. Use free model: /model free`
+    ].join("\n");
+    super(msg);
+    this.name = "InsufficientFundsError";
+    this.currentBalanceUSD = opts.currentBalanceUSD;
+    this.requiredUSD = opts.requiredUSD;
+    this.walletAddress = opts.walletAddress;
+  }
+};
+var EmptyWalletError = class extends Error {
+  code = "EMPTY_WALLET";
+  walletAddress;
+  constructor(walletAddress) {
+    const msg = [
+      `No USDC balance.`,
+      `Options:`,
+      `  1. Fund wallet: ${walletAddress}`,
+      `  2. Use free model: /model free`,
+      `  3. Uninstall: bash ~/.openclaw/extensions/mnemospark/scripts/uninstall.sh`
+    ].join("\n");
+    super(msg);
+    this.name = "EmptyWalletError";
+    this.walletAddress = walletAddress;
+  }
+};
+function isInsufficientFundsError(error) {
+  return error instanceof Error && error.code === "INSUFFICIENT_FUNDS";
+}
+function isEmptyWalletError(error) {
+  return error instanceof Error && error.code === "EMPTY_WALLET";
+}
+function isBalanceError(error) {
+  return isInsufficientFundsError(error) || isEmptyWalletError(error);
+}
+var RpcError = class extends Error {
+  code = "RPC_ERROR";
+  originalError;
+  constructor(message, originalError) {
+    super(`RPC error: ${message}. Check network connectivity.`);
+    this.name = "RpcError";
+    this.originalError = originalError;
+  }
+};
+function isRpcError(error) {
+  return error instanceof Error && error.code === "RPC_ERROR";
+}
+
+// src/balance.ts
+var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var CACHE_TTL_MS = 3e4;
+var BALANCE_THRESHOLDS = {
+  /** Low balance warning threshold: $1.00 */
+  LOW_BALANCE_MICROS: 1000000n,
+  /** Effectively zero threshold: $0.0001 (covers dust/rounding) */
+  ZERO_THRESHOLD: 100n
+};
+var BalanceMonitor = class {
+  client;
+  walletAddress;
+  /** Cached balance (null = not yet fetched) */
+  cachedBalance = null;
+  /** Timestamp when cache was last updated */
+  cachedAt = 0;
+  constructor(walletAddress) {
+    this.walletAddress = walletAddress;
+    this.client = createPublicClient({
+      chain: base,
+      transport: http(void 0, {
+        timeout: 1e4
+        // 10 second timeout to prevent hanging on slow RPC
+      })
+    });
+  }
+  /**
+   * Check current USDC balance.
+   * Uses cache if valid, otherwise fetches from RPC.
+   */
+  async checkBalance() {
+    const now = Date.now();
+    if (this.cachedBalance !== null && now - this.cachedAt < CACHE_TTL_MS) {
+      return this.buildInfo(this.cachedBalance);
+    }
+    const balance = await this.fetchBalance();
+    this.cachedBalance = balance;
+    this.cachedAt = now;
+    return this.buildInfo(balance);
+  }
+  /**
+   * Check if balance is sufficient for an estimated cost.
+   *
+   * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+   */
+  async checkSufficient(estimatedCostMicros) {
+    const info = await this.checkBalance();
+    if (info.balance >= estimatedCostMicros) {
+      return { sufficient: true, info };
+    }
+    const shortfall = estimatedCostMicros - info.balance;
+    return {
+      sufficient: false,
+      info,
+      shortfall: this.formatUSDC(shortfall)
+    };
+  }
+  /**
+   * Optimistically deduct estimated cost from cached balance.
+   * Call this after a successful payment to keep cache accurate.
+   *
+   * @param amountMicros - Amount to deduct in USDC smallest unit
+   */
+  deductEstimated(amountMicros) {
+    if (this.cachedBalance !== null && this.cachedBalance >= amountMicros) {
+      this.cachedBalance -= amountMicros;
+    }
+  }
+  /**
+   * Invalidate cache, forcing next checkBalance() to fetch from RPC.
+   * Call this after a payment failure to get accurate balance.
+   */
+  invalidate() {
+    this.cachedBalance = null;
+    this.cachedAt = 0;
+  }
+  /**
+   * Force refresh balance from RPC (ignores cache).
+   */
+  async refresh() {
+    this.invalidate();
+    return this.checkBalance();
+  }
+  /**
+   * Format USDC amount (in micros) as "$X.XX".
+   */
+  formatUSDC(amountMicros) {
+    const dollars = Number(amountMicros) / 1e6;
+    return `$${dollars.toFixed(2)}`;
+  }
+  /**
+   * Get the wallet address being monitored.
+   */
+  getWalletAddress() {
+    return this.walletAddress;
+  }
+  /** Fetch balance from RPC */
+  async fetchBalance() {
+    try {
+      const balance = await this.client.readContract({
+        address: USDC_BASE,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [this.walletAddress]
+      });
+      return balance;
+    } catch (error) {
+      throw new RpcError(error instanceof Error ? error.message : "Unknown error", error);
+    }
+  }
+  /** Build BalanceInfo from raw balance */
+  buildInfo(balance) {
+    return {
+      balance,
+      balanceUSD: this.formatUSDC(balance),
+      isLow: balance < BALANCE_THRESHOLDS.LOW_BALANCE_MICROS,
+      isEmpty: balance < BALANCE_THRESHOLDS.ZERO_THRESHOLD,
+      walletAddress: this.walletAddress
+    };
+  }
+};
+
+// src/config.ts
+var DEFAULT_PORT = 7120;
+var PROXY_PORT = (() => {
+  const envPort = process.env.MNEMOSPARK_PROXY_PORT;
+  if (envPort) {
+    const parsed = parseInt(envPort, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
+      return parsed;
+    }
+  }
+  return DEFAULT_PORT;
+})();
+var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL ?? "").trim();
+
+// src/mnemospark-request-sign.ts
+import { getAddress } from "viem";
+import { privateKeyToAccount, signTypedData } from "viem/accounts";
+
+// src/nonce.ts
+function createNonce() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+// src/mnemospark-request-sign.ts
+var MNEMOSPARK_DOMAIN_NAME = "Mnemospark";
+var MNEMOSPARK_DOMAIN_VERSION = "1";
+var MNEMOSPARK_VERIFYING_CONTRACT = "0x0000000000000000000000000000000000000001";
+var BASE_MAINNET_CHAIN_ID = 8453;
+var BASE_SEPOLIA_CHAIN_ID = 84532;
+var MNEMOSPARK_REQUEST_TYPES = {
+  MnemosparkRequest: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    { name: "walletAddress", type: "string" },
+    { name: "nonce", type: "string" },
+    { name: "timestamp", type: "string" }
+  ]
+};
+function encodeBase64Json(value) {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+function normalizeMethod(method) {
+  const normalized = method.trim().toUpperCase();
+  if (!normalized) {
+    throw new Error("Request signing requires a non-empty HTTP method.");
+  }
+  return normalized;
+}
+function normalizePath(path) {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error("Request signing requires a non-empty path.");
+  }
+  let parsedPath;
+  if (/^https?:\/\//i.test(trimmed)) {
+    parsedPath = new URL(trimmed).pathname;
+  } else {
+    parsedPath = trimmed.split("?")[0]?.split("#")[0] ?? "";
+  }
+  if (!parsedPath) {
+    throw new Error("Request signing requires a valid request path.");
+  }
+  const prefixed = parsedPath.startsWith("/") ? parsedPath : `/${parsedPath}`;
+  const deduplicated = prefixed.replace(/\/{2,}/g, "/");
+  return deduplicated.length > 1 && deduplicated.endsWith("/") ? deduplicated.slice(0, -1) : deduplicated;
+}
+function normalizeTimestamp(value) {
+  const timestamp = value ?? Math.floor(Date.now() / 1e3).toString();
+  if (!/^\d+$/.test(timestamp)) {
+    throw new Error("Request signing timestamp must be a Unix timestamp in seconds.");
+  }
+  return timestamp;
+}
+function normalizeNonce(value) {
+  const nonce = value ?? createNonce();
+  if (!/^0x[0-9a-fA-F]{64}$/.test(nonce)) {
+    throw new Error("Request signing nonce must be a 32-byte hex value.");
+  }
+  return nonce;
+}
+function normalizeChainId(chainId) {
+  const selected = chainId ?? BASE_MAINNET_CHAIN_ID;
+  if (selected !== BASE_MAINNET_CHAIN_ID && selected !== BASE_SEPOLIA_CHAIN_ID) {
+    throw new Error(`Unsupported chainId for request signing: ${selected}`);
+  }
+  return selected;
+}
+function createMnemosparkRequestDomain(chainId) {
+  return {
+    name: MNEMOSPARK_DOMAIN_NAME,
+    version: MNEMOSPARK_DOMAIN_VERSION,
+    chainId: normalizeChainId(chainId),
+    verifyingContract: MNEMOSPARK_VERIFYING_CONTRACT
+  };
+}
+function createMnemosparkRequestPayload(method, path, walletAddress, options) {
+  return {
+    method: normalizeMethod(method),
+    path: normalizePath(path),
+    walletAddress: getAddress(walletAddress),
+    nonce: normalizeNonce(options?.nonce),
+    timestamp: normalizeTimestamp(options?.timestamp)
+  };
+}
+async function createWalletSignatureHeaderValue(method, path, walletAddress, walletPrivateKey, options) {
+  const payload = createMnemosparkRequestPayload(method, path, walletAddress, {
+    nonce: options?.nonce,
+    timestamp: options?.timestamp
+  });
+  const signer = privateKeyToAccount(walletPrivateKey);
+  if (signer.address.toLowerCase() !== payload.walletAddress.toLowerCase()) {
+    throw new Error(
+      `Wallet address ${payload.walletAddress} does not match signer address ${signer.address}.`
+    );
+  }
+  const signature = await signTypedData({
+    privateKey: walletPrivateKey,
+    domain: createMnemosparkRequestDomain(options?.chainId),
+    types: MNEMOSPARK_REQUEST_TYPES,
+    primaryType: "MnemosparkRequest",
+    message: payload
+  });
+  const headerEnvelope = {
+    payloadB64: encodeBase64Json(payload),
+    signature,
+    address: signer.address
+  };
+  return encodeBase64Json(headerEnvelope);
+}
+
+// src/cloud-utils.ts
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number.parseFloat(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function asNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function normalizePaymentRequired(headers) {
+  return headers.get("PAYMENT-REQUIRED") ?? headers.get("x-payment-required") ?? void 0;
+}
+function normalizePaymentResponse(headers) {
+  return headers.get("PAYMENT-RESPONSE") ?? headers.get("x-payment-response") ?? void 0;
+}
+
+// src/wallet-signature.ts
+function normalizeWalletSignature(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+
+// src/cloud-price-storage.ts
+var PRICE_STORAGE_PROXY_PATH = "/mnemospark/price-storage";
+var UPLOAD_PROXY_PATH = "/mnemospark/upload";
+function asStringRecord(value) {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  const output = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry !== "string") {
+      return null;
+    }
+    output[key] = entry;
+  }
+  return output;
+}
+function parsePriceStorageQuoteRequest(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  const objectId = asNonEmptyString(record.object_id);
+  const objectIdHash = asNonEmptyString(record.object_id_hash);
+  const gb = asNumber(record.gb);
+  const provider = asNonEmptyString(record.provider);
+  const region = asNonEmptyString(record.region);
+  if (!walletAddress || !objectId || !objectIdHash || gb === null || !provider || !region) {
+    return null;
+  }
+  return {
+    wallet_address: walletAddress,
+    object_id: objectId,
+    object_id_hash: objectIdHash,
+    gb,
+    provider,
+    region
+  };
+}
+function parsePriceStorageQuoteResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid price-storage response payload");
+  }
+  const timestamp = asNonEmptyString(record.timestamp);
+  const quoteId = asNonEmptyString(record.quote_id);
+  const storagePrice = asNumber(record.storage_price);
+  const addr = asNonEmptyString(record.addr);
+  const objectId = asNonEmptyString(record.object_id);
+  const objectIdHash = asNonEmptyString(record.object_id_hash);
+  const objectSizeGb = asNumber(record.object_size_gb);
+  const provider = asNonEmptyString(record.provider);
+  const location = asNonEmptyString(record.location);
+  if (!timestamp || !quoteId || storagePrice === null || !addr || !objectId || !objectIdHash || objectSizeGb === null || !provider || !location) {
+    throw new Error("Price-storage response is missing required fields");
+  }
+  return {
+    timestamp,
+    quote_id: quoteId,
+    storage_price: storagePrice,
+    addr,
+    object_id: objectId,
+    object_id_hash: objectIdHash,
+    object_size_gb: objectSizeGb,
+    provider,
+    location
+  };
+}
+function parseStorageUploadRequest(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const quoteId = asNonEmptyString(record.quote_id);
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  const objectId = asNonEmptyString(record.object_id);
+  const objectIdHash = asNonEmptyString(record.object_id_hash);
+  const quotedStoragePrice = asNumber(record.quoted_storage_price);
+  const payloadRecord = asRecord(record.payload);
+  if (!payloadRecord) {
+    return null;
+  }
+  const modeRaw = asNonEmptyString(payloadRecord.mode);
+  const mode = modeRaw === "inline" || modeRaw === "presigned" ? modeRaw : null;
+  const contentBase64 = payloadRecord.content_base64 === void 0 ? void 0 : asNonEmptyString(payloadRecord.content_base64);
+  const contentSha256 = asNonEmptyString(payloadRecord.content_sha256);
+  const contentLengthBytes = asNumber(payloadRecord.content_length_bytes);
+  const wrappedDek = asNonEmptyString(payloadRecord.wrapped_dek);
+  const encryptionAlgorithm = asNonEmptyString(payloadRecord.encryption_algorithm);
+  const bucketNameHint = asNonEmptyString(payloadRecord.bucket_name_hint);
+  const keyStorePathHint = asNonEmptyString(payloadRecord.key_store_path_hint);
+  if (!quoteId || !walletAddress || !objectId || !objectIdHash || quotedStoragePrice === null || !mode || !contentSha256 || contentLengthBytes === null || !wrappedDek || encryptionAlgorithm !== "AES-256-GCM" || !bucketNameHint || !keyStorePathHint) {
+    return null;
+  }
+  if (mode === "inline" && !contentBase64) {
+    return null;
+  }
+  return {
+    quote_id: quoteId,
+    wallet_address: walletAddress,
+    object_id: objectId,
+    object_id_hash: objectIdHash,
+    quoted_storage_price: quotedStoragePrice,
+    payload: {
+      mode,
+      content_base64: contentBase64 ?? void 0,
+      content_sha256: contentSha256,
+      content_length_bytes: contentLengthBytes,
+      wrapped_dek: wrappedDek,
+      encryption_algorithm: "AES-256-GCM",
+      bucket_name_hint: bucketNameHint,
+      key_store_path_hint: keyStorePathHint
+    }
+  };
+}
+function parseStorageUploadResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid upload response payload");
+  }
+  const quoteId = asNonEmptyString(record.quote_id);
+  const addr = asNonEmptyString(record.addr);
+  const addrHash = asNonEmptyString(record.addr_hash);
+  const transId = asNonEmptyString(record.trans_id);
+  const storagePrice = asNumber(record.storage_price);
+  const objectId = asNonEmptyString(record.object_id);
+  const objectKey = asNonEmptyString(record.object_key);
+  const provider = asNonEmptyString(record.provider);
+  const bucketName = asNonEmptyString(record.bucket_name);
+  const location = asNonEmptyString(record.location);
+  const uploadUrl = asNonEmptyString(record.upload_url);
+  const uploadHeaders = record.upload_headers === void 0 ? void 0 : asStringRecord(record.upload_headers);
+  if (!quoteId || !addr || !objectId || !objectKey || !provider || !bucketName || !location) {
+    throw new Error("Upload response is missing required fields");
+  }
+  if (record.upload_headers !== void 0 && !uploadHeaders) {
+    throw new Error("Upload response has invalid upload_headers");
+  }
+  return {
+    quote_id: quoteId,
+    addr,
+    addr_hash: addrHash ?? void 0,
+    trans_id: transId ?? void 0,
+    storage_price: storagePrice ?? void 0,
+    object_id: objectId,
+    object_key: objectKey,
+    provider,
+    bucket_name: bucketName,
+    location,
+    upload_url: uploadUrl ?? void 0,
+    upload_headers: uploadHeaders ?? void 0
+  };
+}
+async function requestPriceStorageViaProxy(request, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = normalizeBaseUrl(
+    options.proxyBaseUrl ?? `http://127.0.0.1:${PROXY_PORT.toString()}`
+  );
+  const response = await fetchImpl(`${baseUrl}${PRICE_STORAGE_PROXY_PATH}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(request)
+  });
+  const responseBody = await response.text();
+  if (!response.ok) {
+    throw new Error(responseBody || `Price-storage proxy failed with status ${response.status}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(responseBody);
+  } catch {
+    throw new Error("Price-storage proxy returned invalid JSON");
+  }
+  return parsePriceStorageQuoteResponse(payload);
+}
+async function requestStorageUploadViaProxy(request, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = normalizeBaseUrl(
+    options.proxyBaseUrl ?? `http://127.0.0.1:${PROXY_PORT.toString()}`
+  );
+  const requestHeaders = {
+    "Content-Type": "application/json"
+  };
+  if (options.idempotencyKey && options.idempotencyKey.trim().length > 0) {
+    requestHeaders["Idempotency-Key"] = options.idempotencyKey.trim();
+  }
+  const response = await fetchImpl(`${baseUrl}${UPLOAD_PROXY_PATH}`, {
+    method: "POST",
+    headers: requestHeaders,
+    body: JSON.stringify(request)
+  });
+  const responseBody = await response.text();
+  if (!response.ok) {
+    throw new Error(responseBody || `Upload proxy failed with status ${response.status}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(responseBody);
+  } catch {
+    throw new Error("Upload proxy returned invalid JSON");
+  }
+  return parseStorageUploadResponse(payload);
+}
+async function forwardPriceStorageToBackend(request, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const backendBaseUrl = (options.backendBaseUrl ?? "").trim();
+  const walletSignature = normalizeWalletSignature(options.walletSignature);
+  if (!backendBaseUrl) {
+    throw new Error("MNEMOSPARK_BACKEND_API_BASE_URL is not configured");
+  }
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (walletSignature) {
+    headers["X-Wallet-Signature"] = walletSignature;
+  }
+  const targetUrl = `${normalizeBaseUrl(backendBaseUrl)}/price-storage`;
+  const response = await fetchImpl(targetUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(request)
+  });
+  return {
+    status: response.status,
+    bodyText: await response.text(),
+    contentType: response.headers.get("content-type") ?? "application/json",
+    paymentRequired: normalizePaymentRequired(response.headers),
+    paymentResponse: normalizePaymentResponse(response.headers)
+  };
+}
+async function forwardStorageUploadToBackend(request, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const backendBaseUrl = (options.backendBaseUrl ?? "").trim();
+  const walletSignature = normalizeWalletSignature(options.walletSignature);
+  if (!backendBaseUrl) {
+    throw new Error("MNEMOSPARK_BACKEND_API_BASE_URL is not configured");
+  }
+  if (!walletSignature) {
+    throw new Error(
+      "Wallet required for storage endpoints: wallet key must be present to sign requests."
+    );
+  }
+  const requestHeaders = {
+    "Content-Type": "application/json",
+    "X-Wallet-Signature": walletSignature
+  };
+  if (options.idempotencyKey && options.idempotencyKey.trim().length > 0) {
+    requestHeaders["Idempotency-Key"] = options.idempotencyKey.trim();
+  }
+  const paymentSignature = options.paymentSignature?.trim();
+  const legacyPayment = options.legacyPayment?.trim();
+  if (paymentSignature) {
+    requestHeaders["PAYMENT-SIGNATURE"] = paymentSignature;
+    requestHeaders["x-payment"] = paymentSignature;
+  }
+  if (legacyPayment) {
+    requestHeaders["x-payment"] = legacyPayment;
+    requestHeaders["PAYMENT-SIGNATURE"] = requestHeaders["PAYMENT-SIGNATURE"] ?? legacyPayment;
+  }
+  const targetUrl = `${normalizeBaseUrl(backendBaseUrl)}/storage/upload`;
+  const response = await fetchImpl(targetUrl, {
+    method: "POST",
+    headers: requestHeaders,
+    body: JSON.stringify(request)
+  });
+  return {
+    status: response.status,
+    bodyText: await response.text(),
+    contentType: response.headers.get("content-type") ?? "application/json",
+    paymentRequired: normalizePaymentRequired(response.headers),
+    paymentResponse: normalizePaymentResponse(response.headers)
+  };
+}
+
+// src/cloud-storage.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join, resolve, sep } from "path";
+var STORAGE_LS_PROXY_PATH = "/mnemospark/storage/ls";
+var STORAGE_DOWNLOAD_PROXY_PATH = "/mnemospark/storage/download";
+var STORAGE_DELETE_PROXY_PATH = "/mnemospark/storage/delete";
+function asBooleanOrDefault(value, defaultValue) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return defaultValue;
+}
+function parseJsonText(text, errorMessage) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(errorMessage);
+  }
+  const record = asRecord(parsed);
+  if (!record) {
+    throw new Error(errorMessage);
+  }
+  return record;
+}
+function sanitizeObjectKeyToRelativePath(objectKey) {
+  const normalized = objectKey.replace(/\\/g, "/").trim().replace(/^\/+/, "");
+  const segments = normalized.split("/").filter((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+  if (segments.length === 0) {
+    return "downloaded-object";
+  }
+  return join(...segments);
+}
+function resolveDownloadPath(outputDir, objectKey) {
+  const resolvedOutputDir = resolve(outputDir);
+  const relativeObjectPath = sanitizeObjectKeyToRelativePath(objectKey);
+  const resolvedTargetPath = resolve(resolvedOutputDir, relativeObjectPath);
+  if (resolvedTargetPath !== resolvedOutputDir && !resolvedTargetPath.startsWith(`${resolvedOutputDir}${sep}`)) {
+    throw new Error("Resolved download target escapes output directory");
+  }
+  return resolvedTargetPath;
+}
+function parseFilenameFromContentDisposition(contentDisposition) {
+  if (!contentDisposition) {
+    return void 0;
+  }
+  const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i);
+  if (utf8Match?.[1]) {
+    try {
+      return decodeURIComponent(utf8Match[1]);
+    } catch {
+      return utf8Match[1];
+    }
+  }
+  const quotedMatch = contentDisposition.match(/filename="([^"]+)"/i);
+  if (quotedMatch?.[1]) {
+    return quotedMatch[1];
+  }
+  const plainMatch = contentDisposition.match(/filename=([^;]+)/i);
+  if (plainMatch?.[1]) {
+    return plainMatch[1].trim();
+  }
+  return void 0;
+}
+async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = normalizeBaseUrl(
+    options.proxyBaseUrl ?? `http://127.0.0.1:${PROXY_PORT.toString()}`
+  );
+  const response = await fetchImpl(`${baseUrl}${proxyPath}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(request)
+  });
+  const bodyText = await response.text();
+  if (!response.ok) {
+    throw new Error(bodyText || `Cloud storage proxy failed with status ${response.status}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(bodyText);
+  } catch {
+    throw new Error("Cloud storage proxy returned invalid JSON");
+  }
+  return parser(payload);
+}
+async function forwardStorageToBackend(path, method, request, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const backendBaseUrl = (options.backendBaseUrl ?? "").trim();
+  const walletSignature = normalizeWalletSignature(options.walletSignature);
+  if (!backendBaseUrl) {
+    throw new Error("MNEMOSPARK_BACKEND_API_BASE_URL is not configured");
+  }
+  if (!walletSignature) {
+    throw new Error(
+      "Wallet required for storage endpoints: wallet key must be present to sign requests."
+    );
+  }
+  const targetUrl = `${normalizeBaseUrl(backendBaseUrl)}${path}`;
+  const response = await fetchImpl(targetUrl, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "X-Wallet-Signature": walletSignature
+    },
+    body: JSON.stringify(request)
+  });
+  const bodyBuffer = Buffer.from(await response.arrayBuffer());
+  return {
+    status: response.status,
+    bodyText: bodyBuffer.toString("utf-8"),
+    bodyBuffer,
+    contentType: response.headers.get("content-type") ?? "application/octet-stream",
+    contentDisposition: response.headers.get("content-disposition") ?? void 0,
+    paymentRequired: normalizePaymentRequired(response.headers),
+    paymentResponse: normalizePaymentResponse(response.headers)
+  };
+}
+function parseStorageObjectRequest(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  const objectKey = asNonEmptyString(record.object_key);
+  const location = asNonEmptyString(record.location) ?? void 0;
+  if (!walletAddress || !objectKey) {
+    return null;
+  }
+  return {
+    wallet_address: walletAddress,
+    object_key: objectKey,
+    location
+  };
+}
+function parseStorageLsResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid ls response payload");
+  }
+  const key = asNonEmptyString(record.key) ?? asNonEmptyString(record.object_key);
+  const sizeBytes = asNumber(record.size_bytes);
+  const bucket = asNonEmptyString(record.bucket) ?? asNonEmptyString(record.bucket_name);
+  const objectId = asNonEmptyString(record.object_id) ?? void 0;
+  if (!key || sizeBytes === null || !bucket) {
+    throw new Error("ls response is missing required fields");
+  }
+  return {
+    success: asBooleanOrDefault(record.success, true),
+    key,
+    size_bytes: sizeBytes,
+    bucket,
+    object_id: objectId
+  };
+}
+function parseStorageDeleteResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid delete response payload");
+  }
+  const key = asNonEmptyString(record.key) ?? asNonEmptyString(record.object_key);
+  const bucket = asNonEmptyString(record.bucket) ?? asNonEmptyString(record.bucket_name);
+  const bucketDeleted = asBooleanOrDefault(record.bucket_deleted, false);
+  if (!key || !bucket) {
+    throw new Error("delete response is missing required fields");
+  }
+  return {
+    success: asBooleanOrDefault(record.success, true),
+    key,
+    bucket,
+    bucket_deleted: bucketDeleted
+  };
+}
+function parseStorageDownloadProxyResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid download response payload");
+  }
+  const key = asNonEmptyString(record.key) ?? asNonEmptyString(record.object_key);
+  const filePath = asNonEmptyString(record.file_path);
+  if (!key || !filePath) {
+    throw new Error("download response is missing required fields");
+  }
+  return {
+    success: asBooleanOrDefault(record.success, true),
+    key,
+    file_path: filePath
+  };
+}
+async function requestStorageLsViaProxy(request, options = {}) {
+  return requestJsonViaProxy(STORAGE_LS_PROXY_PATH, request, parseStorageLsResponse, options);
+}
+async function requestStorageDownloadViaProxy(request, options = {}) {
+  return requestJsonViaProxy(
+    STORAGE_DOWNLOAD_PROXY_PATH,
+    request,
+    parseStorageDownloadProxyResponse,
+    options
+  );
+}
+async function requestStorageDeleteViaProxy(request, options = {}) {
+  return requestJsonViaProxy(
+    STORAGE_DELETE_PROXY_PATH,
+    request,
+    parseStorageDeleteResponse,
+    options
+  );
+}
+async function forwardStorageLsToBackend(request, options = {}) {
+  return forwardStorageToBackend("/storage/ls", "POST", request, options);
+}
+async function forwardStorageDownloadToBackend(request, options = {}) {
+  return forwardStorageToBackend("/storage/download", "POST", request, options);
+}
+async function forwardStorageDeleteToBackend(request, options = {}) {
+  return forwardStorageToBackend("/storage/delete", "POST", request, options);
+}
+async function downloadStorageToDisk(request, backendResponse, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const outputDir = options.outputDir ?? process.cwd();
+  let objectKey = request.object_key;
+  let bytes = backendResponse.bodyBuffer;
+  const contentType = backendResponse.contentType.toLowerCase();
+  if (contentType.includes("application/json")) {
+    const payload = parseJsonText(
+      backendResponse.bodyText,
+      "Download response was JSON but not parseable"
+    );
+    const payloadObjectKey = asNonEmptyString(payload.object_key) ?? asNonEmptyString(payload.key) ?? asNonEmptyString(payload.object_id);
+    const downloadUrl = asNonEmptyString(payload.download_url);
+    const inlineContent = asNonEmptyString(payload.content) ?? asNonEmptyString(payload.body_base64) ?? asNonEmptyString(payload.data);
+    if (payloadObjectKey) {
+      objectKey = payloadObjectKey;
+    }
+    if (downloadUrl) {
+      const fileResponse = await fetchImpl(downloadUrl, { method: "GET" });
+      if (!fileResponse.ok) {
+        throw new Error(`Presigned download failed with status ${fileResponse.status}`);
+      }
+      bytes = Buffer.from(await fileResponse.arrayBuffer());
+    } else if (inlineContent) {
+      bytes = Buffer.from(inlineContent, "base64");
+    } else {
+      throw new Error("Download response did not include download_url or inline content");
+    }
+  } else {
+    const filenameFromHeader = parseFilenameFromContentDisposition(
+      backendResponse.contentDisposition
+    );
+    if (filenameFromHeader) {
+      objectKey = filenameFromHeader;
+    }
+  }
+  const filePath = resolveDownloadPath(outputDir, objectKey);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, bytes);
+  return {
+    key: objectKey,
+    filePath,
+    bytesWritten: bytes.length
+  };
+}
+
+// src/proxy.ts
+var HEALTH_CHECK_TIMEOUT_MS = 2e3;
+var PORT_RETRY_ATTEMPTS = 5;
+var PORT_RETRY_DELAY_MS = 1e3;
+function matchesProxyPath(url, path) {
+  return url === path || url?.startsWith(`${path}?`) === true;
+}
+function readHeaderValue(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (Array.isArray(value)) {
+    for (const candidate of value) {
+      const trimmed = candidate.trim();
+      if (trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  }
+  return void 0;
+}
+async function readProxyJsonBody(req) {
+  const bodyChunks = [];
+  for await (const chunk of req) {
+    bodyChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const bodyText = Buffer.concat(bodyChunks).toString("utf-8").trim();
+  if (bodyText.length === 0) {
+    return {};
+  }
+  return JSON.parse(bodyText);
+}
+function sendJson(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+function createBackendForwardHeaders(response) {
+  const responseHeaders = {
+    "Content-Type": response.contentType
+  };
+  if (response.paymentRequired) {
+    responseHeaders["PAYMENT-REQUIRED"] = response.paymentRequired;
+    responseHeaders["x-payment-required"] = response.paymentRequired;
+  }
+  if (response.paymentResponse) {
+    responseHeaders["PAYMENT-RESPONSE"] = response.paymentResponse;
+    responseHeaders["x-payment-response"] = response.paymentResponse;
+  }
+  return responseHeaders;
+}
+function isLikelyWalletProofFailure(bodyText) {
+  return /(wallet|signature|proof|nonce|timestamp|expired|authoriz)/i.test(bodyText);
+}
+function normalizeBackendAuthFailure(status, bodyText) {
+  if (status !== 401 && status !== 403) {
+    return void 0;
+  }
+  const message = isLikelyWalletProofFailure(bodyText) ? "wallet proof invalid" : "unauthorized";
+  return {
+    status,
+    contentType: "application/json",
+    bodyText: createAuthErrorBody(message)
+  };
+}
+function createAuthErrorBody(message) {
+  return JSON.stringify({
+    error: message.replace(/\s+/g, "_"),
+    message
+  });
+}
+function createWalletRequiredBody() {
+  return JSON.stringify({
+    error: "wallet_required",
+    message: "wallet required for storage endpoints"
+  });
+}
+function getProxyPort() {
+  return PROXY_PORT;
+}
+async function checkExistingProxy(port) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), HEALTH_CHECK_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (response.ok) {
+      const data = await response.json();
+      if (data.status === "ok" && data.wallet) {
+        return data.wallet;
+      }
+    }
+    return void 0;
+  } catch {
+    clearTimeout(timeoutId);
+    return void 0;
+  }
+}
+async function startProxy(options) {
+  const listenPort = options.port ?? getProxyPort();
+  const existingWallet = await checkExistingProxy(listenPort);
+  if (existingWallet) {
+    const account2 = privateKeyToAccount2(options.walletKey);
+    const balanceMonitor2 = new BalanceMonitor(account2.address);
+    const baseUrl2 = `http://127.0.0.1:${listenPort}`;
+    if (existingWallet !== account2.address) {
+      console.warn(
+        `[mnemospark] Existing proxy on port ${listenPort} uses wallet ${existingWallet}, but current config uses ${account2.address}. Reusing existing proxy.`
+      );
+    }
+    options.onReady?.(listenPort);
+    return {
+      port: listenPort,
+      baseUrl: baseUrl2,
+      walletAddress: existingWallet,
+      balanceMonitor: balanceMonitor2,
+      close: async () => {
+      }
+    };
+  }
+  const walletPrivateKey = options.walletKey.trim();
+  const account = privateKeyToAccount2(walletPrivateKey);
+  const balanceMonitor = new BalanceMonitor(account.address);
+  const proxyWalletAddressLower = account.address.toLowerCase();
+  const connections = /* @__PURE__ */ new Set();
+  const createBackendWalletSignature = async (method, path, walletAddress) => {
+    if (walletAddress.toLowerCase() !== proxyWalletAddressLower) {
+      return void 0;
+    }
+    try {
+      return await createWalletSignatureHeaderValue(method, path, walletAddress, walletPrivateKey);
+    } catch (err) {
+      console.warn(
+        `[mnemospark] Failed to create wallet proof for ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return void 0;
+    }
+  };
+  const server = createServer(async (req, res) => {
+    req.on("error", (err) => {
+      console.error(`[mnemospark] Request stream error: ${err.message}`);
+    });
+    res.on("error", (err) => {
+      console.error(`[mnemospark] Response stream error: ${err.message}`);
+    });
+    if (req.method === "POST" && matchesProxyPath(req.url, PRICE_STORAGE_PROXY_PATH)) {
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /cloud price-storage"
+          });
+          return;
+        }
+        const requestPayload = parsePriceStorageQuoteRequest(payload);
+        if (!requestPayload) {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: wallet_address, object_id, object_id_hash, gb, provider, region"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/price-storage",
+          requestPayload.wallet_address
+        );
+        const backendResponse = await forwardPriceStorageToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          const responseHeaders2 = createBackendForwardHeaders({
+            contentType: authFailure.contentType,
+            paymentRequired: backendResponse.paymentRequired,
+            paymentResponse: backendResponse.paymentResponse
+          });
+          res.writeHead(authFailure.status, responseHeaders2);
+          res.end(authFailure.bodyText);
+          return;
+        }
+        const responseHeaders = createBackendForwardHeaders(backendResponse);
+        res.writeHead(backendResponse.status, responseHeaders);
+        res.end(backendResponse.bodyText);
+      } catch (err) {
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /cloud price-storage: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_PROXY_PATH)) {
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /cloud upload"
+          });
+          return;
+        }
+        const requestPayload = parseStorageUploadRequest(payload);
+        if (!requestPayload) {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: quote_id, wallet_address, object_id, object_id_hash, quoted_storage_price, payload"
+          });
+          return;
+        }
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/upload",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(createWalletRequiredBody());
+          return;
+        }
+        const requiredMicros = BigInt(
+          Math.max(1, Math.ceil(requestPayload.quoted_storage_price * 1e6))
+        );
+        const uploadBalanceMonitor = requestPayload.wallet_address.toLowerCase() === account.address.toLowerCase() ? balanceMonitor : new BalanceMonitor(requestPayload.wallet_address);
+        const sufficiency = await uploadBalanceMonitor.checkSufficient(requiredMicros);
+        const requiredUSD = uploadBalanceMonitor.formatUSDC(requiredMicros);
+        if (!sufficiency.sufficient) {
+          options.onInsufficientFunds?.({
+            balanceUSD: sufficiency.info.balanceUSD,
+            requiredUSD,
+            walletAddress: requestPayload.wallet_address
+          });
+          sendJson(res, 400, {
+            error: "insufficient_balance",
+            message: `Insufficient USDC balance. Current: ${sufficiency.info.balanceUSD}, Required: ${requiredUSD}`,
+            wallet: requestPayload.wallet_address,
+            help: `Fund wallet ${requestPayload.wallet_address} on Base before running /cloud upload`
+          });
+          return;
+        }
+        if (sufficiency.info.isLow) {
+          options.onLowBalance?.({
+            balanceUSD: sufficiency.info.balanceUSD,
+            walletAddress: requestPayload.wallet_address
+          });
+        }
+        const backendResponse = await forwardStorageUploadToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature,
+          paymentSignature: readHeaderValue(req.headers["payment-signature"]),
+          legacyPayment: readHeaderValue(req.headers["x-payment"]),
+          idempotencyKey: readHeaderValue(req.headers["idempotency-key"])
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          const responseHeaders2 = createBackendForwardHeaders({
+            contentType: authFailure.contentType,
+            paymentRequired: backendResponse.paymentRequired,
+            paymentResponse: backendResponse.paymentResponse
+          });
+          res.writeHead(authFailure.status, responseHeaders2);
+          res.end(authFailure.bodyText);
+          return;
+        }
+        const responseHeaders = createBackendForwardHeaders(backendResponse);
+        res.writeHead(backendResponse.status, responseHeaders);
+        res.end(backendResponse.bodyText);
+      } catch (err) {
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /cloud upload: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_LS_PROXY_PATH)) {
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /cloud ls"
+          });
+          return;
+        }
+        const requestPayload = parseStorageObjectRequest(payload);
+        if (!requestPayload) {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: wallet_address, object_key"
+          });
+          return;
+        }
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/ls",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(createWalletRequiredBody());
+          return;
+        }
+        const backendResponse = await forwardStorageLsToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          const responseHeaders2 = createBackendForwardHeaders({
+            contentType: authFailure.contentType,
+            paymentRequired: backendResponse.paymentRequired,
+            paymentResponse: backendResponse.paymentResponse
+          });
+          res.writeHead(authFailure.status, responseHeaders2);
+          res.end(authFailure.bodyText);
+          return;
+        }
+        const responseHeaders = createBackendForwardHeaders(backendResponse);
+        res.writeHead(backendResponse.status, responseHeaders);
+        res.end(backendResponse.bodyText);
+      } catch (err) {
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /cloud ls: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DOWNLOAD_PROXY_PATH)) {
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /cloud download"
+          });
+          return;
+        }
+        const requestPayload = parseStorageObjectRequest(payload);
+        if (!requestPayload) {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: wallet_address, object_key"
+          });
+          return;
+        }
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/download",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(createWalletRequiredBody());
+          return;
+        }
+        const backendResponse = await forwardStorageDownloadToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          const responseHeaders = createBackendForwardHeaders({
+            contentType: authFailure.contentType,
+            paymentRequired: backendResponse.paymentRequired,
+            paymentResponse: backendResponse.paymentResponse
+          });
+          res.writeHead(authFailure.status, responseHeaders);
+          res.end(authFailure.bodyText);
+          return;
+        }
+        if (backendResponse.status < 200 || backendResponse.status >= 300) {
+          const responseHeaders = createBackendForwardHeaders(backendResponse);
+          res.writeHead(backendResponse.status, responseHeaders);
+          res.end(backendResponse.bodyText);
+          return;
+        }
+        const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse);
+        sendJson(res, 200, {
+          success: true,
+          key: downloadResult.key,
+          file_path: downloadResult.filePath,
+          bytes_written: downloadResult.bytesWritten
+        });
+      } catch (err) {
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /cloud download: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DELETE_PROXY_PATH)) {
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /cloud delete"
+          });
+          return;
+        }
+        const requestPayload = parseStorageObjectRequest(payload);
+        if (!requestPayload) {
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: wallet_address, object_key"
+          });
+          return;
+        }
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/delete",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(createWalletRequiredBody());
+          return;
+        }
+        const backendResponse = await forwardStorageDeleteToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          const responseHeaders2 = createBackendForwardHeaders({
+            contentType: authFailure.contentType,
+            paymentRequired: backendResponse.paymentRequired,
+            paymentResponse: backendResponse.paymentResponse
+          });
+          res.writeHead(authFailure.status, responseHeaders2);
+          res.end(authFailure.bodyText);
+          return;
+        }
+        const responseHeaders = createBackendForwardHeaders(backendResponse);
+        res.writeHead(backendResponse.status, responseHeaders);
+        res.end(backendResponse.bodyText);
+      } catch (err) {
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /cloud delete: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.url === "/health" || req.url?.startsWith("/health?")) {
+      const url = new URL(req.url, "http://localhost");
+      const full = url.searchParams.get("full") === "true";
+      const response = {
+        status: "ok",
+        wallet: account.address
+      };
+      if (full) {
+        try {
+          const balanceInfo = await balanceMonitor.checkBalance();
+          response.balance = balanceInfo.balanceUSD;
+          response.isLow = balanceInfo.isLow;
+          response.isEmpty = balanceInfo.isEmpty;
+        } catch {
+          response.balanceError = "Could not fetch balance";
+        }
+      }
+      sendJson(res, 200, response);
+      return;
+    }
+    sendJson(res, 404, {
+      error: "Not found",
+      message: "Supported paths: /health and /mnemospark/* storage endpoints"
+    });
+  });
+  const tryListen = (attempt) => {
+    return new Promise((resolveAttempt, rejectAttempt) => {
+      const onError = async (err) => {
+        server.removeListener("error", onError);
+        if (err.code === "EADDRINUSE") {
+          const existingWallet2 = await checkExistingProxy(listenPort);
+          if (existingWallet2) {
+            console.log(`[mnemospark] Existing proxy detected on port ${listenPort}, reusing`);
+            rejectAttempt({ code: "REUSE_EXISTING", wallet: existingWallet2 });
+            return;
+          }
+          if (attempt < PORT_RETRY_ATTEMPTS) {
+            console.log(
+              `[mnemospark] Port ${listenPort} in TIME_WAIT, retrying in ${PORT_RETRY_DELAY_MS}ms (attempt ${attempt}/${PORT_RETRY_ATTEMPTS})`
+            );
+            rejectAttempt({ code: "RETRY", attempt });
+            return;
+          }
+          console.error(
+            `[mnemospark] Port ${listenPort} still in use after ${PORT_RETRY_ATTEMPTS} attempts`
+          );
+          rejectAttempt(err);
+          return;
+        }
+        rejectAttempt(err);
+      };
+      server.once("error", onError);
+      server.listen(listenPort, "127.0.0.1", () => {
+        server.removeListener("error", onError);
+        resolveAttempt();
+      });
+    });
+  };
+  let lastError;
+  for (let attempt = 1; attempt <= PORT_RETRY_ATTEMPTS; attempt++) {
+    try {
+      await tryListen(attempt);
+      break;
+    } catch (err) {
+      const error = err;
+      if (error.code === "REUSE_EXISTING" && error.wallet) {
+        const baseUrl2 = `http://127.0.0.1:${listenPort}`;
+        options.onReady?.(listenPort);
+        return {
+          port: listenPort,
+          baseUrl: baseUrl2,
+          walletAddress: error.wallet,
+          balanceMonitor,
+          close: async () => {
+          }
+        };
+      }
+      if (error.code === "RETRY") {
+        await new Promise((r) => setTimeout(r, PORT_RETRY_DELAY_MS));
+        continue;
+      }
+      lastError = err;
+      break;
+    }
+  }
+  if (lastError) {
+    throw lastError;
+  }
+  const addr = server.address();
+  const port = addr.port;
+  const baseUrl = `http://127.0.0.1:${port}`;
+  options.onReady?.(port);
+  server.on("error", (err) => {
+    console.error(`[mnemospark] Server runtime error: ${err.message}`);
+    options.onError?.(err);
+  });
+  server.on("clientError", (err, socket) => {
+    console.error(`[mnemospark] Client error: ${err.message}`);
+    if (socket.writable && !socket.destroyed) {
+      socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+    }
+  });
+  server.on("connection", (socket) => {
+    connections.add(socket);
+    socket.setTimeout(3e5);
+    socket.on("timeout", () => {
+      console.error(`[mnemospark] Socket timeout, destroying connection`);
+      socket.destroy();
+    });
+    socket.on("error", (err) => {
+      console.error(`[mnemospark] Socket error: ${err.message}`);
+    });
+    socket.on("close", () => {
+      connections.delete(socket);
+    });
+  });
+  return {
+    port,
+    baseUrl,
+    walletAddress: account.address,
+    balanceMonitor,
+    close: () => new Promise((res, rej) => {
+      const timeout = setTimeout(() => {
+        rej(new Error("[mnemospark] Close timeout after 4s"));
+      }, 4e3);
+      for (const socket of connections) {
+        socket.destroy();
+      }
+      connections.clear();
+      server.close((err) => {
+        clearTimeout(timeout);
+        if (err) {
+          rej(err);
+        } else {
+          res();
+        }
+      });
+    })
+  };
+}
+
+// src/auth.ts
+import { writeFile as writeFile2, readFile, mkdir as mkdir2 } from "fs/promises";
+import { join as join2 } from "path";
+import { homedir } from "os";
+import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
+var LEGACY_WALLET_DIR = join2(homedir(), ".openclaw", "blockrun");
+var LEGACY_WALLET_FILE = join2(LEGACY_WALLET_DIR, "wallet.key");
+var WALLET_DIR = join2(homedir(), ".openclaw", "mnemospark", "wallet");
+var WALLET_FILE = join2(WALLET_DIR, "wallet.key");
+async function loadSavedWallet() {
+  for (const path of [WALLET_FILE, LEGACY_WALLET_FILE]) {
+    try {
+      const key = (await readFile(path, "utf-8")).trim();
+      if (key.startsWith("0x") && key.length === 66) {
+        console.log(`[mnemospark] \u2713 Loaded existing wallet from ${path}`);
+        return key;
+      }
+      console.warn(`[mnemospark] \u26A0 Wallet file exists but is invalid (wrong format): ${path}`);
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.error(
+          `[mnemospark] \u2717 Failed to read wallet file ${path}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  return void 0;
+}
+async function generateAndSaveWallet() {
+  const key = generatePrivateKey();
+  const account = privateKeyToAccount3(key);
+  await mkdir2(WALLET_DIR, { recursive: true });
+  await writeFile2(WALLET_FILE, key + "\n", { mode: 384 });
+  try {
+    const verification = (await readFile(WALLET_FILE, "utf-8")).trim();
+    if (verification !== key) {
+      throw new Error("Wallet file verification failed - content mismatch");
+    }
+    console.log(`[mnemospark] \u2713 Wallet saved and verified at ${WALLET_FILE}`);
+  } catch (err) {
+    throw new Error(
+      `Failed to verify wallet file after creation: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return { key, address: account.address };
+}
+async function resolveOrGenerateWalletKey() {
+  const saved = await loadSavedWallet();
+  if (saved) {
+    const account = privateKeyToAccount3(saved);
+    return { key: saved, address: account.address, source: "saved" };
+  }
+  const envKey = process.env.BLOCKRUN_WALLET_KEY;
+  if (typeof envKey === "string" && envKey.startsWith("0x") && envKey.length === 66) {
+    const account = privateKeyToAccount3(envKey);
+    return { key: envKey, address: account.address, source: "env" };
+  }
+  const { key, address } = await generateAndSaveWallet();
+  return { key, address, source: "generated" };
+}
+
+// src/index.ts
+import { existsSync, readFileSync } from "fs";
+
+// src/version.ts
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join as join3 } from "path";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var require2 = createRequire(import.meta.url);
+var pkg = require2(join3(__dirname, "..", "package.json"));
+var VERSION = pkg.version;
+var USER_AGENT = `mnemospark/${VERSION}`;
+
+// src/index.ts
+import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
+
+// src/cloud-command.ts
+import { spawn } from "child_process";
+import {
+  createCipheriv,
+  createHash,
+  randomBytes as randomBytesNode,
+  randomUUID
+} from "crypto";
+import { createReadStream, statfsSync } from "fs";
+import { appendFile, lstat, mkdir as mkdir3, readFile as readFile2, readdir, rm, stat, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { basename, dirname as dirname3, join as join4, resolve as resolve2 } from "path";
+import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
+
+// src/x402.ts
+import { signTypedData as signTypedData2, privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
+
+// src/payment-cache.ts
+var DEFAULT_TTL_MS = 36e5;
+var PaymentCache = class {
+  cache = /* @__PURE__ */ new Map();
+  ttlMs;
+  constructor(ttlMs = DEFAULT_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+  /** Get cached payment params for an endpoint path. */
+  get(endpointPath) {
+    const entry = this.cache.get(endpointPath);
+    if (!entry) return void 0;
+    if (Date.now() - entry.cachedAt > this.ttlMs) {
+      this.cache.delete(endpointPath);
+      return void 0;
+    }
+    return entry;
+  }
+  /** Cache payment params from a 402 response. */
+  set(endpointPath, params) {
+    this.cache.set(endpointPath, { ...params, cachedAt: Date.now() });
+  }
+  /** Invalidate cache for an endpoint (e.g., if payTo changed). */
+  invalidate(endpointPath) {
+    this.cache.delete(endpointPath);
+  }
+};
+
+// src/x402.ts
+var BASE_CHAIN_ID = 8453;
+var BASE_SEPOLIA_CHAIN_ID2 = 84532;
+var DEFAULT_TOKEN_NAME = "USD Coin";
+var DEFAULT_TOKEN_VERSION = "2";
+var DEFAULT_NETWORK = "eip155:8453";
+var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+var TRANSFER_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function decodeBase64Json(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = (4 - normalized.length % 4) % 4;
+  const padded = normalized + "=".repeat(padding);
+  const decoded = Buffer.from(padded, "base64").toString("utf8");
+  return JSON.parse(decoded);
+}
+function encodeBase64Json2(value) {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+function parsePaymentRequired(headerValue) {
+  return decodeBase64Json(headerValue);
+}
+function normalizeNetwork(network) {
+  if (!network || network.trim().length === 0) {
+    return DEFAULT_NETWORK;
+  }
+  return network.trim().toLowerCase();
+}
+function resolveChainId(network) {
+  const eip155Match = network.match(/^eip155:(\d+)$/i);
+  if (eip155Match) {
+    const parsed = Number.parseInt(eip155Match[1], 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  if (network === "base") return BASE_CHAIN_ID;
+  if (network === "base-sepolia") return BASE_SEPOLIA_CHAIN_ID2;
+  return BASE_CHAIN_ID;
+}
+function parseHexAddress(value) {
+  if (!value) return void 0;
+  const direct = value.match(/^0x[a-fA-F0-9]{40}$/);
+  if (direct) {
+    return direct[0];
+  }
+  const caipSuffix = value.match(/0x[a-fA-F0-9]{40}$/);
+  if (caipSuffix) {
+    return caipSuffix[0];
+  }
+  return void 0;
+}
+function requireHexAddress(value, field) {
+  const parsed = parseHexAddress(value);
+  if (!parsed) {
+    throw new Error(`Invalid ${field} in payment requirements: ${String(value)}`);
+  }
+  return parsed;
+}
+function setPaymentHeaders(headers, payload) {
+  headers.set("payment-signature", payload);
+  headers.set("x-payment", payload);
+}
+async function createPaymentPayload(privateKey, fromAddress, option, amount, requestUrl, resource) {
+  const network = normalizeNetwork(option.network);
+  const chainId = resolveChainId(network);
+  const recipient = requireHexAddress(option.payTo, "payTo");
+  const verifyingContract = requireHexAddress(option.asset, "asset");
+  const maxTimeoutSeconds = typeof option.maxTimeoutSeconds === "number" && option.maxTimeoutSeconds > 0 ? Math.floor(option.maxTimeoutSeconds) : DEFAULT_MAX_TIMEOUT_SECONDS;
+  const now = Math.floor(Date.now() / 1e3);
+  const validAfter = now - 600;
+  const validBefore = now + maxTimeoutSeconds;
+  const nonce = createNonce();
+  const signature = await signTypedData2({
+    privateKey,
+    domain: {
+      name: option.extra?.name || DEFAULT_TOKEN_NAME,
+      version: option.extra?.version || DEFAULT_TOKEN_VERSION,
+      chainId,
+      verifyingContract
+    },
+    types: TRANSFER_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: fromAddress,
+      to: recipient,
+      value: BigInt(amount),
+      validAfter: BigInt(validAfter),
+      validBefore: BigInt(validBefore),
+      nonce
+    }
+  });
+  const paymentData = {
+    x402Version: 2,
+    resource: {
+      url: resource?.url || requestUrl,
+      description: resource?.description || "BlockRun AI API call",
+      mimeType: "application/json"
+    },
+    accepted: {
+      scheme: option.scheme,
+      network,
+      amount,
+      asset: option.asset,
+      payTo: option.payTo,
+      maxTimeoutSeconds: option.maxTimeoutSeconds,
+      extra: option.extra
+    },
+    payload: {
+      signature,
+      authorization: {
+        from: fromAddress,
+        to: recipient,
+        value: amount,
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce
+      }
+    },
+    extensions: {}
+  };
+  return encodeBase64Json2(paymentData);
+}
+function createPaymentFetch(privateKey) {
+  const account = privateKeyToAccount4(privateKey);
+  const walletAddress = account.address;
+  const paymentCache = new PaymentCache();
+  const payFetch = async (input, init, preAuth) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const endpointPath = new URL(url).pathname;
+    const cached = paymentCache.get(endpointPath);
+    if (cached && preAuth?.estimatedAmount) {
+      const paymentPayload = await createPaymentPayload(
+        privateKey,
+        walletAddress,
+        {
+          scheme: cached.scheme,
+          network: cached.network,
+          asset: cached.asset,
+          payTo: cached.payTo,
+          maxTimeoutSeconds: cached.maxTimeoutSeconds,
+          extra: cached.extra
+        },
+        preAuth.estimatedAmount,
+        url,
+        {
+          url: cached.resourceUrl,
+          description: cached.resourceDescription
+        }
+      );
+      const preAuthHeaders = new Headers(init?.headers);
+      setPaymentHeaders(preAuthHeaders, paymentPayload);
+      const response2 = await fetch(input, { ...init, headers: preAuthHeaders });
+      if (response2.status !== 402) {
+        return response2;
+      }
+      const paymentHeader2 = response2.headers.get("payment-required") ?? response2.headers.get("x-payment-required");
+      if (paymentHeader2) {
+        return handle402(input, init, url, endpointPath, paymentHeader2);
+      }
+      paymentCache.invalidate(endpointPath);
+      const cleanResponse = await fetch(input, init);
+      if (cleanResponse.status !== 402) {
+        return cleanResponse;
+      }
+      const cleanHeader = cleanResponse.headers.get("payment-required") ?? cleanResponse.headers.get("x-payment-required");
+      if (!cleanHeader) {
+        throw new Error("402 response missing PAYMENT-REQUIRED or x-payment-required header");
+      }
+      return handle402(input, init, url, endpointPath, cleanHeader);
+    }
+    const response = await fetch(input, init);
+    if (response.status !== 402) {
+      return response;
+    }
+    const paymentHeader = response.headers.get("payment-required") ?? response.headers.get("x-payment-required");
+    if (!paymentHeader) {
+      throw new Error("402 response missing PAYMENT-REQUIRED or x-payment-required header");
+    }
+    return handle402(input, init, url, endpointPath, paymentHeader);
+  };
+  async function handle402(input, init, url, endpointPath, paymentHeader) {
+    const paymentRequired = parsePaymentRequired(paymentHeader);
+    const option = paymentRequired.accepts?.[0];
+    if (!option) {
+      throw new Error("No payment options in 402 response");
+    }
+    const amount = option.amount || option.maxAmountRequired;
+    if (!amount) {
+      throw new Error("No amount in payment requirements");
+    }
+    paymentCache.set(endpointPath, {
+      payTo: option.payTo,
+      asset: option.asset,
+      scheme: option.scheme,
+      network: option.network,
+      extra: option.extra,
+      maxTimeoutSeconds: option.maxTimeoutSeconds,
+      resourceUrl: paymentRequired.resource?.url,
+      resourceDescription: paymentRequired.resource?.description
+    });
+    const paymentPayload = await createPaymentPayload(
+      privateKey,
+      walletAddress,
+      option,
+      amount,
+      url,
+      paymentRequired.resource
+    );
+    const retryHeaders = new Headers(init?.headers);
+    setPaymentHeaders(retryHeaders, paymentPayload);
+    return fetch(input, {
+      ...init,
+      headers: retryHeaders
+    });
+  }
+  return { fetch: payFetch, cache: paymentCache };
+}
+
+// src/cloud-command.ts
+var SUPPORTED_BACKUP_PLATFORMS = /* @__PURE__ */ new Set(["darwin", "linux"]);
+var BACKUP_DIR_SUBPATH = join4(".openclaw", "mnemospark", "backup");
+var DEFAULT_BACKUP_DIR = join4(homedir2(), BACKUP_DIR_SUBPATH);
+var OBJECT_LOG_SUBPATH = join4(".openclaw", "mnemospark", "object.log");
+var CRON_TABLE_SUBPATH = join4(".openclaw", "mnemospark", "crontab.txt");
+var BLOCKRUN_WALLET_KEY_SUBPATH = join4(".openclaw", "blockrun", "wallet.key");
+var MNEMOSPARK_WALLET_KEY_SUBPATH = join4(".openclaw", "mnemospark", "wallet", "wallet.key");
+var KEY_STORE_SUBPATH = join4(".openclaw", "mnemospark", "keys");
+var INLINE_UPLOAD_MAX_BYTES = 45e5;
+var AES_GCM_NONCE_BYTES = 12;
+var PAYMENT_REMINDER_INTERVAL_DAYS = 30;
+var PAYMENT_DELETE_DEADLINE_DAYS = 32;
+var PAYMENT_CRON_SCHEDULE = "0 0 1 * *";
+var CRON_LOG_ROW_PREFIX = "cron";
+var TAR_OVERHEAD_BYTES = 10 * 1024 * 1024;
+var REQUIRED_PRICE_STORAGE = "--wallet-address, --object-id, --object-id-hash, --gb, --provider, --region";
+var REQUIRED_UPLOAD = "--quote-id, --wallet-address, --object-id, --object-id-hash";
+var REQUIRED_STORAGE_OBJECT = "--wallet-address, --object-key";
+var CLOUD_HELP_TEXT = [
+  "\u2601\uFE0F **mnemospark Cloud Commands**",
+  "",
+  "\u2022 `/cloud` or `/cloud help` \u2014 show this message",
+  "",
+  "\u2022 `/cloud backup <file>` or `/cloud backup <directory>`",
+  "  Required: <file> or <directory> (path to back up)",
+  "",
+  "\u2022 `/cloud price-storage --wallet-address <addr> --object-id <id> --object-id-hash <hash> --gb <gb> --provider <provider> --region <region>`",
+  "  Required: " + REQUIRED_PRICE_STORAGE,
+  "",
+  "\u2022 `/cloud upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash>`",
+  "  Required: " + REQUIRED_UPLOAD,
+  "",
+  "\u2022 `/cloud ls --wallet-address <addr> --object-key <object-key>`",
+  "  Required: " + REQUIRED_STORAGE_OBJECT,
+  "",
+  "\u2022 `/cloud download --wallet-address <addr> --object-key <object-key>`",
+  "  Required: " + REQUIRED_STORAGE_OBJECT,
+  "",
+  "\u2022 `/cloud delete --wallet-address <addr> --object-key <object-key>`",
+  "  Required: " + REQUIRED_STORAGE_OBJECT,
+  "",
+  "Backup creates a tar+gzip object in ~/.openclaw/mnemospark/backup and appends object metadata to ~/.openclaw/mnemospark/object.log. Upload appends storage rows and cron-tracking rows to object.log, and keeps job entries in ~/.openclaw/mnemospark/crontab.txt. All storage commands (price-storage, upload, ls, download, delete) require --wallet-address."
+].join("\n");
+var UnsupportedBackupPlatformError = class extends Error {
+  constructor(platform) {
+    super(`Unsupported platform for backup: ${platform}`);
+    this.name = "UnsupportedBackupPlatformError";
+  }
+};
+function toGbString(bytes) {
+  const gb = bytes / 1e9;
+  const fixed = gb.toFixed(9).replace(/\.?0+$/, "");
+  if (!fixed) return "0";
+  return fixed.includes(".") ? fixed : `${fixed}.0`;
+}
+function stripWrappingQuotes(input) {
+  const trimmed = input.trim();
+  if (trimmed.length < 2) return trimmed;
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function tokenizeArgs(input) {
+  const tokens = input.match(/"[^"]*"|'[^']*'|\S+/g);
+  if (!tokens) {
+    return [];
+  }
+  return tokens.map((token) => stripWrappingQuotes(token));
+}
+function parseNamedFlags(input) {
+  const tokens = tokenizeArgs(input);
+  if (tokens.length === 0) {
+    return null;
+  }
+  const parsed = {};
+  for (let i = 0; i < tokens.length; i += 1) {
+    const keyToken = tokens[i];
+    if (!keyToken.startsWith("--")) {
+      return null;
+    }
+    const key = keyToken.slice(2).toLowerCase();
+    const value = tokens[i + 1];
+    if (!value || value.startsWith("--")) {
+      return null;
+    }
+    parsed[key] = value;
+    i += 1;
+  }
+  return parsed;
+}
+function parseCloudArgs(args) {
+  const trimmed = args?.trim() ?? "";
+  if (!trimmed) {
+    return { mode: "help" };
+  }
+  const spaceIdx = trimmed.indexOf(" ");
+  const subcommand = (spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx)).toLowerCase();
+  const rest = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1);
+  if (subcommand === "help") {
+    return { mode: "help" };
+  }
+  if (subcommand === "backup") {
+    const backupTarget = stripWrappingQuotes(rest);
+    if (!backupTarget) {
+      return { mode: "unknown" };
+    }
+    return { mode: "backup", backupTarget };
+  }
+  if (subcommand === "price-storage") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "price-storage-invalid" };
+    }
+    const gb = Number.parseFloat(flags.gb ?? "");
+    const request = parsePriceStorageQuoteRequest({
+      wallet_address: flags["wallet-address"],
+      object_id: flags["object-id"],
+      object_id_hash: flags["object-id-hash"],
+      gb,
+      provider: flags.provider,
+      region: flags.region
+    });
+    if (!request) {
+      return { mode: "price-storage-invalid" };
+    }
+    return { mode: "price-storage", priceStorageRequest: request };
+  }
+  if (subcommand === "upload") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "upload-invalid" };
+    }
+    const quoteId = flags["quote-id"]?.trim();
+    const walletAddress = flags["wallet-address"]?.trim();
+    const objectId = flags["object-id"]?.trim();
+    const objectIdHash = flags["object-id-hash"]?.trim();
+    if (!quoteId || !walletAddress || !objectId || !objectIdHash) {
+      return { mode: "upload-invalid" };
+    }
+    return {
+      mode: "upload",
+      uploadRequest: {
+        quote_id: quoteId,
+        wallet_address: walletAddress,
+        object_id: objectId,
+        object_id_hash: objectIdHash
+      }
+    };
+  }
+  if (subcommand === "ls") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "ls-invalid" };
+    }
+    const request = parseStorageObjectRequest({
+      wallet_address: flags["wallet-address"],
+      object_key: flags["object-key"],
+      location: flags.location ?? flags.region
+    });
+    if (!request) {
+      return { mode: "ls-invalid" };
+    }
+    return { mode: "ls", storageObjectRequest: request };
+  }
+  if (subcommand === "download") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "download-invalid" };
+    }
+    const request = parseStorageObjectRequest({
+      wallet_address: flags["wallet-address"],
+      object_key: flags["object-key"],
+      location: flags.location ?? flags.region
+    });
+    if (!request) {
+      return { mode: "download-invalid" };
+    }
+    return { mode: "download", storageObjectRequest: request };
+  }
+  if (subcommand === "delete") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "delete-invalid" };
+    }
+    const request = parseStorageObjectRequest({
+      wallet_address: flags["wallet-address"],
+      object_key: flags["object-key"],
+      location: flags.location ?? flags.region
+    });
+    if (!request) {
+      return { mode: "delete-invalid" };
+    }
+    return { mode: "delete", storageObjectRequest: request };
+  }
+  return { mode: "unknown" };
+}
+function resolveObjectLogPath(homeDir) {
+  return join4(homeDir ?? homedir2(), OBJECT_LOG_SUBPATH);
+}
+function resolveCronTablePath(homeDir) {
+  return join4(homeDir ?? homedir2(), CRON_TABLE_SUBPATH);
+}
+async function appendObjectLogLine(line, homeDir) {
+  const objectLogPath = resolveObjectLogPath(homeDir);
+  await mkdir3(dirname3(objectLogPath), { recursive: true });
+  await appendFile(objectLogPath, `${line}
+`, "utf-8");
+  return objectLogPath;
+}
+async function calculateInputSizeBytes(targetPath) {
+  const targetStats = await lstat(targetPath);
+  if (targetStats.isFile() || targetStats.isSymbolicLink()) {
+    return targetStats.size;
+  }
+  if (!targetStats.isDirectory()) {
+    throw new Error("Backup target must be a file or directory");
+  }
+  let total = 0;
+  const entries = await readdir(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    total += await calculateInputSizeBytes(join4(targetPath, entry.name));
+  }
+  return total;
+}
+function getAvailableDiskBytes(tmpDir, options) {
+  if (typeof options.availableDiskBytes === "number") {
+    return options.availableDiskBytes;
+  }
+  const stats = statfsSync(tmpDir);
+  return stats.bavail * stats.bsize;
+}
+async function runTarGzip(archivePath, sourcePath) {
+  const sourceDir = dirname3(sourcePath);
+  const sourceName = basename(sourcePath);
+  await new Promise((resolvePromise, rejectPromise) => {
+    let stderr = "";
+    const child = spawn("tar", ["-czf", archivePath, "-C", sourceDir, sourceName], {
+      stdio: ["ignore", "ignore", "pipe"]
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", rejectPromise);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      rejectPromise(new Error(stderr.trim() || `tar exited with code ${code ?? "unknown"}`));
+    });
+  });
+}
+async function sha256File(filePath) {
+  const hash = createHash("sha256");
+  await new Promise((resolvePromise, rejectPromise) => {
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", rejectPromise);
+    stream.on("end", () => resolvePromise());
+  });
+  return hash.digest("hex");
+}
+function createObjectId(options) {
+  const nowFn = options.now ?? Date.now;
+  const randomFn = options.randomBytes ?? randomBytesNode;
+  return `${nowFn()}-${randomFn(8).toString("hex")}`;
+}
+async function buildBackupObject(targetPathArg, options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (!SUPPORTED_BACKUP_PLATFORMS.has(platform)) {
+    throw new UnsupportedBackupPlatformError(platform);
+  }
+  const targetPath = resolve2(targetPathArg);
+  const targetStats = await lstat(targetPath);
+  if (!targetStats.isFile() && !targetStats.isDirectory()) {
+    throw new Error("Backup target must be a file or directory");
+  }
+  const tmpDir = options.tmpDir ?? DEFAULT_BACKUP_DIR;
+  let tmpStats;
+  try {
+    tmpStats = await stat(tmpDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await mkdir3(tmpDir, { recursive: true });
+      tmpStats = await stat(tmpDir);
+    } else {
+      throw error;
+    }
+  }
+  if (!tmpStats.isDirectory()) {
+    throw new Error("Backup path is not a directory");
+  }
+  const inputSizeBytes = await calculateInputSizeBytes(targetPath);
+  const availableDiskBytes = getAvailableDiskBytes(tmpDir, options);
+  const requiredDiskBytes = inputSizeBytes + TAR_OVERHEAD_BYTES;
+  if (availableDiskBytes < requiredDiskBytes) {
+    throw new Error("Insufficient disk space for backup object");
+  }
+  const objectId = createObjectId(options);
+  const archivePath = join4(tmpDir, objectId);
+  try {
+    await runTarGzip(archivePath, targetPath);
+    const archiveStats = await stat(archivePath);
+    const objectIdHash = await sha256File(archivePath);
+    const objectSizeGb = toGbString(archiveStats.size);
+    const objectLogPath = await appendObjectLogLine(
+      `${objectId},${objectIdHash},${objectSizeGb}`,
+      options.homeDir
+    );
+    return {
+      objectId,
+      objectIdHash,
+      objectSizeGb,
+      archivePath,
+      objectLogPath
+    };
+  } catch (error) {
+    await rm(archivePath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+async function appendPriceStorageQuoteLog(quote, homeDir) {
+  return appendObjectLogLine(
+    [
+      quote.timestamp,
+      quote.quote_id,
+      quote.storage_price.toString(),
+      quote.addr,
+      quote.object_id,
+      quote.object_id_hash,
+      quote.object_size_gb.toString(),
+      quote.provider,
+      quote.location
+    ].join(","),
+    homeDir
+  );
+}
+function formatTimestamp(date) {
+  const pad = (value) => value.toString().padStart(2, "0");
+  return [
+    date.getFullYear().toString(),
+    "-",
+    pad(date.getMonth() + 1),
+    "-",
+    pad(date.getDate()),
+    " ",
+    pad(date.getHours()),
+    ":",
+    pad(date.getMinutes()),
+    ":",
+    pad(date.getSeconds())
+  ].join("");
+}
+function parseLoggedPriceStorageQuote(line) {
+  const parts = line.split(",");
+  if (parts.length < 9) {
+    return null;
+  }
+  const quoteId = parts[1]?.trim() ?? "";
+  const storagePriceRaw = parts[2]?.trim() ?? "";
+  const walletAddress = parts[3]?.trim() ?? "";
+  const objectId = parts[4]?.trim() ?? "";
+  const objectIdHash = parts[5]?.trim() ?? "";
+  const provider = parts[7]?.trim() ?? "";
+  const location = parts[8]?.trim() ?? "";
+  const storagePrice = Number.parseFloat(storagePriceRaw);
+  if (!quoteId || !walletAddress || !objectId || !objectIdHash || !provider || !location) {
+    return null;
+  }
+  if (!Number.isFinite(storagePrice) || storagePrice <= 0) {
+    return null;
+  }
+  return {
+    quoteId,
+    storagePrice,
+    walletAddress,
+    objectId,
+    objectIdHash,
+    provider,
+    location
+  };
+}
+function parseLoggedStoragePaymentCron(line) {
+  const parts = line.split(",");
+  if (parts.length < 5) {
+    return null;
+  }
+  if ((parts[0]?.trim() ?? "").toLowerCase() !== CRON_LOG_ROW_PREFIX) {
+    return null;
+  }
+  const cronId = parts[2]?.trim() ?? "";
+  const objectId = parts[3]?.trim() ?? "";
+  const objectKey = parts[4]?.trim() ?? "";
+  if (!cronId || !objectId || !objectKey) {
+    return null;
+  }
+  return {
+    cronId,
+    objectId,
+    objectKey
+  };
+}
+function parseStoragePaymentCronJobLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+  const record = payload;
+  const cronId = typeof record.cronId === "string" ? record.cronId.trim() : "";
+  const createdAt = typeof record.createdAt === "string" ? record.createdAt.trim() : "";
+  const schedule = typeof record.schedule === "string" ? record.schedule.trim() : "";
+  const command = typeof record.command === "string" ? record.command.trim() : "";
+  const quoteId = typeof record.quoteId === "string" ? record.quoteId.trim() : "";
+  const storagePrice = typeof record.storagePrice === "number" ? record.storagePrice : Number.NaN;
+  const walletAddress = typeof record.walletAddress === "string" ? record.walletAddress.trim() : "";
+  const objectId = typeof record.objectId === "string" ? record.objectId.trim() : "";
+  const objectKey = typeof record.objectKey === "string" ? record.objectKey.trim() : "";
+  const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+  const bucketName = typeof record.bucketName === "string" ? record.bucketName.trim() : "";
+  const location = typeof record.location === "string" ? record.location.trim() : "";
+  if (!cronId || !createdAt || !schedule || !command || !quoteId || !Number.isFinite(storagePrice) || storagePrice <= 0 || !walletAddress || !objectId || !objectKey || !provider || !bucketName || !location) {
+    return null;
+  }
+  return {
+    cronId,
+    createdAt,
+    schedule,
+    command,
+    quoteId,
+    storagePrice,
+    walletAddress,
+    objectId,
+    objectKey,
+    provider,
+    bucketName,
+    location
+  };
+}
+async function findLoggedPriceStorageQuote(quoteId, homeDir) {
+  const objectLogPath = resolveObjectLogPath(homeDir);
+  let content;
+  try {
+    content = await readFile2(objectLogPath, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  const lines = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  for (let idx = lines.length - 1; idx >= 0; idx -= 1) {
+    const parsed = parseLoggedPriceStorageQuote(lines[idx]);
+    if (parsed && parsed.quoteId === quoteId) {
+      return parsed;
+    }
+  }
+  return null;
+}
+async function findLoggedStoragePaymentCronByObjectKey(objectKey, homeDir) {
+  const objectLogPath = resolveObjectLogPath(homeDir);
+  let content;
+  try {
+    content = await readFile2(objectLogPath, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  const lines = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  for (let idx = lines.length - 1; idx >= 0; idx -= 1) {
+    const parsed = parseLoggedStoragePaymentCron(lines[idx]);
+    if (parsed && parsed.objectKey === objectKey) {
+      return parsed;
+    }
+  }
+  return null;
+}
+function quoteCronArgument(value) {
+  return JSON.stringify(String(value));
+}
+function buildStoragePaymentCronCommand(job) {
+  return [
+    "mnemospark-pay-storage",
+    "--quote-id",
+    quoteCronArgument(job.quoteId),
+    "--wallet-address",
+    quoteCronArgument(job.walletAddress),
+    "--object-id",
+    quoteCronArgument(job.objectId),
+    "--object-key",
+    quoteCronArgument(job.objectKey),
+    "--storage-price",
+    quoteCronArgument(job.storagePrice)
+  ].join(" ");
+}
+async function appendStoragePaymentCronLog(cronJob, homeDir) {
+  return appendObjectLogLine(
+    [
+      CRON_LOG_ROW_PREFIX,
+      cronJob.createdAt,
+      cronJob.cronId,
+      cronJob.objectId,
+      cronJob.objectKey,
+      cronJob.quoteId,
+      cronJob.storagePrice.toString()
+    ].join(","),
+    homeDir
+  );
+}
+async function appendStoragePaymentCronJob(cronJob, homeDir) {
+  const cronTablePath = resolveCronTablePath(homeDir);
+  await mkdir3(dirname3(cronTablePath), { recursive: true });
+  await appendFile(cronTablePath, `${JSON.stringify(cronJob)}
+`, "utf-8");
+  return cronTablePath;
+}
+async function removeStoragePaymentCronJob(cronId, homeDir) {
+  const cronTablePath = resolveCronTablePath(homeDir);
+  let content;
+  try {
+    content = await readFile2(cronTablePath, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  const lines = content.split(/\r?\n/);
+  let removed = false;
+  const keptLines = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const parsed = parseStoragePaymentCronJobLine(trimmed);
+    if (parsed && parsed.cronId === cronId) {
+      removed = true;
+      continue;
+    }
+    keptLines.push(trimmed);
+  }
+  if (!removed) {
+    return false;
+  }
+  await mkdir3(dirname3(cronTablePath), { recursive: true });
+  const nextContent = keptLines.length > 0 ? `${keptLines.join("\n")}
+` : "";
+  await writeFile3(cronTablePath, nextContent, "utf-8");
+  return true;
+}
+async function createStoragePaymentCronJob(upload, storagePrice, homeDir, nowDateFn = () => /* @__PURE__ */ new Date()) {
+  const cronId = randomUUID();
+  const createdAt = formatTimestamp(nowDateFn());
+  const cronJob = {
+    cronId,
+    createdAt,
+    schedule: PAYMENT_CRON_SCHEDULE,
+    command: buildStoragePaymentCronCommand({
+      quoteId: upload.quote_id,
+      walletAddress: upload.addr,
+      objectId: upload.object_id,
+      objectKey: upload.object_key,
+      storagePrice
+    }),
+    quoteId: upload.quote_id,
+    storagePrice,
+    walletAddress: upload.addr,
+    objectId: upload.object_id,
+    objectKey: upload.object_key,
+    provider: upload.provider,
+    bucketName: upload.bucket_name,
+    location: upload.location
+  };
+  await appendStoragePaymentCronJob(cronJob, homeDir);
+  await appendStoragePaymentCronLog(cronJob, homeDir);
+  return cronJob;
+}
+function isValidWalletPrivateKey(value) {
+  return typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value.trim());
+}
+async function readWalletKeyIfPresent(walletPath) {
+  try {
+    const key = (await readFile2(walletPath, "utf-8")).trim();
+    return isValidWalletPrivateKey(key) ? key : null;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+async function resolveWalletPrivateKey(homeDir) {
+  const envKey = process.env.BLOCKRUN_WALLET_KEY?.trim();
+  if (isValidWalletPrivateKey(envKey)) {
+    return envKey;
+  }
+  const baseHome = homeDir ?? homedir2();
+  const primaryWalletPath = join4(baseHome, BLOCKRUN_WALLET_KEY_SUBPATH);
+  const fallbackWalletPath = join4(baseHome, MNEMOSPARK_WALLET_KEY_SUBPATH);
+  const fromPrimary = await readWalletKeyIfPresent(primaryWalletPath);
+  if (fromPrimary) {
+    return fromPrimary;
+  }
+  const fromFallback = await readWalletKeyIfPresent(fallbackWalletPath);
+  if (fromFallback) {
+    return fromFallback;
+  }
+  throw new Error("Wallet key not found. Configure BLOCKRUN_WALLET_KEY or run /wallet first.");
+}
+function sha256Buffer(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function walletShortHash(walletAddress) {
+  return sha256Buffer(Buffer.from(walletAddress.trim().toLowerCase(), "utf-8")).slice(0, 16);
+}
+function bucketNameForWallet(walletAddress) {
+  return `mnemospark-${walletShortHash(walletAddress)}`;
+}
+function encryptAesGcm(plaintext, key, randomFn = randomBytesNode) {
+  if (key.length !== 32) {
+    throw new Error("Expected 32-byte AES key");
+  }
+  const nonce = randomFn(AES_GCM_NONCE_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([nonce, ciphertext, tag]);
+}
+async function loadOrCreateKek(walletAddress, homeDir) {
+  const keyPath = join4(
+    homeDir ?? homedir2(),
+    KEY_STORE_SUBPATH,
+    `${walletShortHash(walletAddress)}.key`
+  );
+  await mkdir3(dirname3(keyPath), { recursive: true });
+  try {
+    const existing = await readFile2(keyPath);
+    if (existing.length === 32) {
+      return { kek: existing, keyPath };
+    }
+    const decoded = Buffer.from(existing.toString("utf-8").trim(), "base64");
+    if (decoded.length === 32) {
+      return { kek: decoded, keyPath };
+    }
+    throw new Error("Invalid key file format");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const generated = randomBytesNode(32);
+  await writeFile3(keyPath, generated, { mode: 384 });
+  return { kek: generated, keyPath };
+}
+async function prepareUploadPayload(archivePath, walletAddress, homeDir) {
+  const plaintext = await readFile2(archivePath);
+  const { kek, keyPath } = await loadOrCreateKek(walletAddress, homeDir);
+  const dek = randomBytesNode(32);
+  const encryptedContent = encryptAesGcm(plaintext, dek);
+  const wrappedDek = encryptAesGcm(dek, kek);
+  const payloadHash = sha256Buffer(encryptedContent);
+  const payload = {
+    mode: encryptedContent.length <= INLINE_UPLOAD_MAX_BYTES ? "inline" : "presigned",
+    content_base64: encryptedContent.length <= INLINE_UPLOAD_MAX_BYTES ? encryptedContent.toString("base64") : void 0,
+    content_sha256: payloadHash,
+    content_length_bytes: encryptedContent.length,
+    wrapped_dek: wrappedDek.toString("base64"),
+    encryption_algorithm: "AES-256-GCM",
+    bucket_name_hint: bucketNameForWallet(walletAddress),
+    key_store_path_hint: keyPath
+  };
+  return {
+    payload,
+    encryptedContent
+  };
+}
+async function uploadPresignedObjectIfNeeded(uploadResponse, uploadMode, encryptedContent, fetchImpl = fetch) {
+  if (!uploadResponse.upload_url) {
+    if (uploadMode === "presigned") {
+      throw new Error("Cannot upload storage object: missing presigned upload URL.");
+    }
+    return;
+  }
+  const headers = new Headers(uploadResponse.upload_headers ?? {});
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/octet-stream");
+  }
+  const response = await fetchImpl(uploadResponse.upload_url, {
+    method: "PUT",
+    headers,
+    body: new Uint8Array(encryptedContent)
+  });
+  if (!response.ok) {
+    const details = (await response.text()).trim();
+    throw new Error(
+      `Presigned upload failed with status ${response.status}${details ? `: ${details}` : ""}`
+    );
+  }
+}
+async function appendStorageUploadLog(upload, homeDir, nowDateFn = () => /* @__PURE__ */ new Date()) {
+  return appendObjectLogLine(
+    [
+      formatTimestamp(nowDateFn()),
+      upload.quote_id,
+      upload.addr,
+      upload.addr_hash ?? "",
+      upload.trans_id ?? "",
+      upload.storage_price?.toString() ?? "",
+      upload.object_id,
+      upload.object_key,
+      upload.provider,
+      upload.bucket_name,
+      upload.location
+    ].join(","),
+    homeDir
+  );
+}
+async function maybeCleanupLocalBackupArchive(archivePath) {
+  const flag = process.env.MNEMOSPARK_DELETE_BACKUP_AFTER_UPLOAD;
+  if (!flag) {
+    return;
+  }
+  const normalized = flag.trim().toLowerCase();
+  if (normalized !== "1" && normalized !== "true" && normalized !== "yes" && normalized !== "y") {
+    return;
+  }
+  try {
+    await rm(archivePath, { force: true });
+  } catch {
+  }
+}
+function formatStorageUploadUserMessage(upload, cronJobId) {
+  return [
+    `Your file \`${upload.object_id}\` with key \`${upload.object_key}\` has been stored using \`${upload.provider}\` in \`${upload.bucket_name}\` \`${upload.location}\``,
+    `A cron job \`${cronJobId}\` has been configured to send payment monthly (on the 1st) for storage services. If payment is not sent, your \`${upload.object_id}\` will be deleted after the **${PAYMENT_DELETE_DEADLINE_DAYS}-day deadline** (${PAYMENT_REMINDER_INTERVAL_DAYS}-day billing interval + 2-day grace period).`,
+    "Thank you for using mnemospark!"
+  ].join("\n");
+}
+function formatStorageDeleteUserMessage(objectKey, cronId, cronDeleted) {
+  const statusLine = cronId ? cronDeleted ? `File \`${objectKey}\` has been deleted from the cloud and the cron job \`${cronId}\` has been deleted from your system.` : `File \`${objectKey}\` has been deleted from the cloud and the cron job \`${cronId}\` was not found in your system.` : `File \`${objectKey}\` has been deleted from the cloud and no matching cron job was found in your system.`;
+  return [statusLine, "Thank you for using mnemospark!"].join("\n");
+}
+function extractUploadErrorMessage(error) {
+  if (!(error instanceof Error)) {
+    return null;
+  }
+  const message = error.message.trim();
+  if (!message) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(message);
+    if (typeof payload.message === "string" && payload.message.trim().length > 0) {
+      return payload.message.trim();
+    }
+    if (typeof payload.error === "string" && payload.error.trim().length > 0) {
+      return payload.error.trim();
+    }
+    if (payload.error && typeof payload.error === "object" && typeof payload.error.message === "string" && payload.error.message.trim().length > 0) {
+      return payload.error.message.trim();
+    }
+  } catch {
+  }
+  return message;
+}
+function formatPriceStorageUserMessage(quote) {
+  return [
+    `Your storage quote \`${quote.quote_id}\` is valid for 1 hour, the storage price is \`${quote.storage_price}\` for \`${quote.object_id}\` with file size of \`${quote.object_size_gb}\` in \`${quote.provider}\` \`${quote.location}\``,
+    `If you accept this quote run the command /cloud upload --quote-id \`${quote.quote_id}\` --wallet-address \`${quote.addr}\` --object-id \`${quote.object_id}\` --object-id-hash \`${quote.object_id_hash}\``
+  ].join("\n");
+}
+function formatStorageLsUserMessage(result, requestedObjectKey) {
+  const objectId = result.object_id ?? result.key;
+  return `${objectId} with ${requestedObjectKey} is ${result.size_bytes} in ${result.bucket}`;
+}
+function createCloudCommand(options = {}) {
+  const backupBuilder = options.buildBackupObjectFn ?? buildBackupObject;
+  const requestPriceStorageQuote = options.requestPriceStorageQuoteFn ?? requestPriceStorageViaProxy;
+  const requestStorageUpload = options.requestStorageUploadFn ?? requestStorageUploadViaProxy;
+  const resolveWalletKey = options.resolveWalletPrivateKeyFn ?? resolveWalletPrivateKey;
+  const createPayment = options.createPaymentFetchFn ?? createPaymentFetch;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const nowDateFn = options.nowDateFn ?? (() => /* @__PURE__ */ new Date());
+  const idempotencyKeyFn = options.idempotencyKeyFn ?? randomUUID;
+  const requestStorageLs = options.requestStorageLsFn ?? requestStorageLsViaProxy;
+  const requestStorageDownload = options.requestStorageDownloadFn ?? requestStorageDownloadViaProxy;
+  const requestStorageDelete = options.requestStorageDeleteFn ?? requestStorageDeleteViaProxy;
+  const objectLogHomeDir = options.objectLogHomeDir ?? options.backupOptions?.homeDir;
+  return {
+    name: "cloud",
+    description: "Manage mnemospark cloud storage workflow commands",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx) => {
+      const parsed = parseCloudArgs(ctx.args);
+      if (parsed.mode === "help" || parsed.mode === "unknown") {
+        return {
+          text: CLOUD_HELP_TEXT,
+          isError: parsed.mode === "unknown"
+        };
+      }
+      if (parsed.mode === "price-storage-invalid") {
+        return {
+          text: `Cannot price storage: required arguments are ${REQUIRED_PRICE_STORAGE}.`,
+          isError: true
+        };
+      }
+      if (parsed.mode === "upload-invalid") {
+        return {
+          text: `Cannot upload storage object: required arguments are ${REQUIRED_UPLOAD}.`,
+          isError: true
+        };
+      }
+      if (parsed.mode === "ls-invalid") {
+        return {
+          text: `Cannot list storage object: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
+          isError: true
+        };
+      }
+      if (parsed.mode === "download-invalid") {
+        return {
+          text: `Cannot download file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
+          isError: true
+        };
+      }
+      if (parsed.mode === "delete-invalid") {
+        return {
+          text: `Cannot delete file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
+          isError: true
+        };
+      }
+      if (parsed.mode === "backup") {
+        try {
+          const result = await backupBuilder(parsed.backupTarget, options.backupOptions);
+          return {
+            text: `Your object-id is ${result.objectId} your object-id-hash is ${result.objectIdHash} and your object-size is ${result.objectSizeGb}`
+          };
+        } catch (err) {
+          if (err instanceof UnsupportedBackupPlatformError) {
+            return {
+              text: "Cloud backup is only supported on macOS and Linux.",
+              isError: true
+            };
+          }
+          return {
+            text: "Cannot build storage object",
+            isError: true
+          };
+        }
+      }
+      if (parsed.mode === "price-storage") {
+        try {
+          const quote = await requestPriceStorageQuote(
+            parsed.priceStorageRequest,
+            options.proxyQuoteOptions
+          );
+          await appendPriceStorageQuoteLog(quote, objectLogHomeDir);
+          return {
+            text: formatPriceStorageUserMessage(quote)
+          };
+        } catch {
+          return {
+            text: "Cannot price storage",
+            isError: true
+          };
+        }
+      }
+      if (parsed.mode === "upload") {
+        try {
+          const loggedQuote = await findLoggedPriceStorageQuote(
+            parsed.uploadRequest.quote_id,
+            objectLogHomeDir
+          );
+          if (!loggedQuote) {
+            return {
+              text: "Cannot upload storage object: quote-id not found in object.log. Run /cloud price-storage first.",
+              isError: true
+            };
+          }
+          if (loggedQuote.walletAddress.toLowerCase() !== parsed.uploadRequest.wallet_address.toLowerCase() || loggedQuote.objectId !== parsed.uploadRequest.object_id || loggedQuote.objectIdHash.toLowerCase() !== parsed.uploadRequest.object_id_hash.toLowerCase()) {
+            return {
+              text: "Cannot upload storage object: quote details do not match wallet/object arguments.",
+              isError: true
+            };
+          }
+          const archivePath = join4(
+            options.backupOptions?.tmpDir ?? DEFAULT_BACKUP_DIR,
+            parsed.uploadRequest.object_id
+          );
+          let archiveStats;
+          try {
+            archiveStats = await stat(archivePath);
+          } catch {
+            return {
+              text: `Cannot upload storage object: local archive not found at ${archivePath}. Run /cloud backup first.`,
+              isError: true
+            };
+          }
+          if (!archiveStats.isFile()) {
+            return {
+              text: `Cannot upload storage object: local archive path is not a file (${archivePath}).`,
+              isError: true
+            };
+          }
+          const archiveHash = await sha256File(archivePath);
+          if (archiveHash.toLowerCase() !== parsed.uploadRequest.object_id_hash.toLowerCase()) {
+            return {
+              text: "Cannot upload storage object: object-id-hash does not match local archive.",
+              isError: true
+            };
+          }
+          const walletKey = await resolveWalletKey(objectLogHomeDir);
+          const walletAccount = privateKeyToAccount5(walletKey);
+          if (walletAccount.address.toLowerCase() !== parsed.uploadRequest.wallet_address.toLowerCase()) {
+            return {
+              text: `Cannot upload storage object: wallet key address ${walletAccount.address} does not match --wallet-address ${parsed.uploadRequest.wallet_address}.`,
+              isError: true
+            };
+          }
+          const preparedPayload = await prepareUploadPayload(
+            archivePath,
+            parsed.uploadRequest.wallet_address,
+            objectLogHomeDir
+          );
+          const paymentFetch = createPayment(walletKey).fetch;
+          const idempotencyKey = idempotencyKeyFn();
+          const uploadResponse = await requestStorageUpload(
+            {
+              quote_id: parsed.uploadRequest.quote_id,
+              wallet_address: parsed.uploadRequest.wallet_address,
+              object_id: parsed.uploadRequest.object_id,
+              object_id_hash: parsed.uploadRequest.object_id_hash,
+              quoted_storage_price: loggedQuote.storagePrice,
+              payload: preparedPayload.payload
+            },
+            {
+              ...options.proxyUploadOptions,
+              idempotencyKey,
+              fetchImpl: (input, init) => paymentFetch(input, init)
+            }
+          );
+          await uploadPresignedObjectIfNeeded(
+            uploadResponse,
+            preparedPayload.payload.mode,
+            preparedPayload.encryptedContent,
+            fetchImpl
+          );
+          await appendStorageUploadLog(uploadResponse, objectLogHomeDir, nowDateFn);
+          const cronStoragePriceCandidate = uploadResponse.storage_price ?? loggedQuote.storagePrice;
+          const cronStoragePrice = Number.isFinite(cronStoragePriceCandidate) && cronStoragePriceCandidate > 0 ? cronStoragePriceCandidate : loggedQuote.storagePrice;
+          const cronJob = await createStoragePaymentCronJob(
+            uploadResponse,
+            cronStoragePrice,
+            objectLogHomeDir,
+            nowDateFn
+          );
+          await maybeCleanupLocalBackupArchive(archivePath);
+          return {
+            text: formatStorageUploadUserMessage(uploadResponse, cronJob.cronId)
+          };
+        } catch (error) {
+          return {
+            text: extractUploadErrorMessage(error) ?? "Cannot upload storage object",
+            isError: true
+          };
+        }
+      }
+      if (parsed.mode === "ls") {
+        try {
+          const lsResult = await requestStorageLs(
+            parsed.storageObjectRequest,
+            options.proxyStorageOptions
+          );
+          if (!lsResult.success) {
+            throw new Error("ls failed");
+          }
+          return {
+            text: formatStorageLsUserMessage(lsResult, parsed.storageObjectRequest.object_key)
+          };
+        } catch {
+          return {
+            text: "Cannot list storage object",
+            isError: true
+          };
+        }
+      }
+      if (parsed.mode === "download") {
+        try {
+          const downloadResult = await requestStorageDownload(
+            parsed.storageObjectRequest,
+            options.proxyStorageOptions
+          );
+          if (!downloadResult.success) {
+            throw new Error("download failed");
+          }
+          return {
+            text: `File ${parsed.storageObjectRequest.object_key} downloaded`
+          };
+        } catch {
+          return {
+            text: "Cannot download file",
+            isError: true
+          };
+        }
+      }
+      if (parsed.mode === "delete") {
+        try {
+          const deleteResult = await requestStorageDelete(
+            parsed.storageObjectRequest,
+            options.proxyStorageOptions
+          );
+          if (!deleteResult.success) {
+            throw new Error("delete failed");
+          }
+        } catch {
+          return {
+            text: "Cannot delete file",
+            isError: true
+          };
+        }
+        let cronEntry = null;
+        let cronDeleted = false;
+        try {
+          cronEntry = await findLoggedStoragePaymentCronByObjectKey(
+            parsed.storageObjectRequest.object_key,
+            objectLogHomeDir
+          );
+          cronDeleted = cronEntry ? await removeStoragePaymentCronJob(cronEntry.cronId, objectLogHomeDir) : false;
+        } catch {
+        }
+        return {
+          text: formatStorageDeleteUserMessage(
+            parsed.storageObjectRequest.object_key,
+            cronEntry?.cronId ?? null,
+            cronDeleted
+          )
+        };
+      }
+      return {
+        text: CLOUD_HELP_TEXT,
+        isError: true
+      };
+    }
+  };
+}
+
+// src/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 2,
+  baseDelayMs: 500,
+  retryableCodes: [429, 502, 503, 504]
+};
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+async function fetchWithRetry(fetchFn, url, init, config) {
+  const cfg = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config
+  };
+  let lastError;
+  let lastResponse;
+  for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
+    try {
+      const response = await fetchFn(url, init);
+      if (!cfg.retryableCodes.includes(response.status)) {
+        return response;
+      }
+      lastResponse = response;
+      const retryAfter = response.headers.get("retry-after");
+      let delay;
+      if (retryAfter) {
+        const seconds = parseInt(retryAfter, 10);
+        delay = isNaN(seconds) ? cfg.baseDelayMs * Math.pow(2, attempt) : seconds * 1e3;
+      } else {
+        delay = cfg.baseDelayMs * Math.pow(2, attempt);
+      }
+      if (attempt < cfg.maxRetries) {
+        await sleep(delay);
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < cfg.maxRetries) {
+        const delay = cfg.baseDelayMs * Math.pow(2, attempt);
+        await sleep(delay);
+      }
+    }
+  }
+  if (lastResponse) {
+    return lastResponse;
+  }
+  throw lastError ?? new Error("Max retries exceeded");
+}
+function isRetryable(errorOrResponse, config) {
+  const retryableCodes = config?.retryableCodes ?? DEFAULT_RETRY_CONFIG.retryableCodes;
+  if (errorOrResponse instanceof Response) {
+    return retryableCodes.includes(errorOrResponse.status);
+  }
+  const message = errorOrResponse.message.toLowerCase();
+  return message.includes("network") || message.includes("timeout") || message.includes("econnreset") || message.includes("econnrefused") || message.includes("socket hang up");
+}
+
+// src/index.ts
+function isCompletionMode() {
+  const args = process.argv;
+  return args.some((arg, i) => arg === "completion" && i >= 1 && i <= 3);
+}
+function isGatewayMode() {
+  const args = process.argv;
+  return args.includes("gateway");
+}
+var activeProxyHandle = null;
+async function startProxyInBackground(api) {
+  const { key: walletKey, address, source } = await resolveOrGenerateWalletKey();
+  if (source === "generated") {
+    api.logger.info(`Generated new wallet: ${address}`);
+  } else if (source === "saved") {
+    api.logger.info(`Using saved wallet: ${address}`);
+  } else {
+    api.logger.info(`Using wallet from BLOCKRUN_WALLET_KEY: ${address}`);
+  }
+  const proxy = await startProxy({
+    walletKey,
+    onReady: (port) => {
+      api.logger.info(`mnemospark proxy listening on port ${port}`);
+    },
+    onError: (error) => {
+      api.logger.error(`mnemospark proxy error: ${error.message}`);
+    },
+    onLowBalance: (info) => {
+      api.logger.warn(`[!] Low balance: ${info.balanceUSD}. Fund wallet: ${info.walletAddress}`);
+    },
+    onInsufficientFunds: (info) => {
+      api.logger.error(
+        `[!] Insufficient funds. Balance: ${info.balanceUSD}, Needed: ${info.requiredUSD}. Fund wallet: ${info.walletAddress}`
+      );
+    }
+  });
+  activeProxyHandle = proxy;
+  api.logger.info("mnemospark ready");
+  const startupMonitor = new BalanceMonitor(address);
+  startupMonitor.checkBalance().then((balance) => {
+    if (balance.isEmpty) {
+      api.logger.info(`Wallet: ${address} | Balance: $0.00`);
+    } else if (balance.isLow) {
+      api.logger.info(`Wallet: ${address} | Balance: ${balance.balanceUSD} (low)`);
+    } else {
+      api.logger.info(`Wallet: ${address} | Balance: ${balance.balanceUSD}`);
+    }
+  }).catch(() => {
+    api.logger.info(`Wallet: ${address} | Balance: (checking...)`);
+  });
+}
+async function createWalletCommand() {
+  return {
+    name: "wallet",
+    description: "Show mnemospark wallet info or export private key for backup",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx) => {
+      const subcommand = ctx.args?.trim().toLowerCase() || "status";
+      let walletKey;
+      let address;
+      try {
+        if (existsSync(WALLET_FILE)) {
+          walletKey = readFileSync(WALLET_FILE, "utf-8").trim();
+          if (walletKey.startsWith("0x") && walletKey.length === 66) {
+            const account = privateKeyToAccount6(walletKey);
+            address = account.address;
+          }
+        }
+      } catch {
+      }
+      if (!walletKey || !address) {
+        return {
+          text: "No mnemospark wallet found.\n\nRun `openclaw plugins install mnemospark` to generate a wallet.",
+          isError: true
+        };
+      }
+      if (subcommand === "export") {
+        return {
+          text: [
+            "\u{1F510} **mnemospark Wallet Export**",
+            "",
+            "\u26A0\uFE0F **SECURITY WARNING**: Your private key controls your wallet funds.",
+            "Never share this key. Anyone with this key can spend your USDC.",
+            "",
+            `**Address:** \`${address}\``,
+            "",
+            "**Private Key:**",
+            `\`${walletKey}\``,
+            "",
+            "**To restore on a new machine:**",
+            "1. Set the environment variable before running OpenClaw:",
+            `   \`export BLOCKRUN_WALLET_KEY=${walletKey}\``,
+            "2. Or save to file:",
+            `   \`mkdir -p ~/.openclaw/blockrun && echo "${walletKey}" > ~/.openclaw/blockrun/wallet.key && chmod 600 ~/.openclaw/blockrun/wallet.key\``
+          ].join("\n")
+        };
+      }
+      let balanceText = "Balance: (checking...)";
+      try {
+        const monitor = new BalanceMonitor(address);
+        const balance = await monitor.checkBalance();
+        balanceText = `Balance: ${balance.balanceUSD}`;
+      } catch {
+        balanceText = "Balance: (could not check)";
+      }
+      return {
+        text: [
+          "\u{1F99E} **mnemospark Wallet**",
+          "",
+          `**Address:** \`${address}\``,
+          `**${balanceText}**`,
+          `**Key File:** \`${WALLET_FILE}\``,
+          "",
+          "**Commands:**",
+          "\u2022 `/wallet` - Show this status",
+          "\u2022 `/wallet export` - Export private key for backup",
+          "",
+          `**Fund with USDC on Base:** https://basescan.org/address/${address}`
+        ].join("\n")
+      };
+    }
+  };
+}
+var plugin = {
+  id: "mnemospark",
+  name: "mnemospark",
+  description: "mnemospark storage and wallet plugin",
+  version: VERSION,
+  async register(api) {
+    const isDisabled = process.env.MNEMOSPARK_DISABLED === "true" || process.env.MNEMOSPARK_DISABLED === "1";
+    if (isDisabled) {
+      api.logger.info("mnemospark disabled (MNEMOSPARK_DISABLED=true).");
+      return;
+    }
+    if (isCompletionMode()) {
+      return;
+    }
+    createWalletCommand().then((walletCommand) => {
+      api.registerCommand(walletCommand);
+    }).catch((err) => {
+      api.logger.warn(
+        `Failed to register /wallet command: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+    try {
+      api.registerCommand(createCloudCommand());
+    } catch (err) {
+      api.logger.warn(
+        `Failed to register /cloud command: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    api.registerService({
+      id: "mnemospark-proxy",
+      start: () => {
+      },
+      stop: async () => {
+        if (activeProxyHandle) {
+          try {
+            await activeProxyHandle.close();
+            api.logger.info("mnemospark proxy closed");
+          } catch (err) {
+            api.logger.warn(
+              `Error closing proxy: ${err instanceof Error ? err.message : String(err)}`
+            );
+          } finally {
+            activeProxyHandle = null;
+          }
+        }
+      }
+    });
+    if (!isGatewayMode()) {
+      return;
+    }
+    startProxyInBackground(api).catch((err) => {
+      api.logger.error(
+        `Failed to start mnemospark proxy: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  }
+};
+var index_default = plugin;
+export {
+  BALANCE_THRESHOLDS,
+  BalanceMonitor,
+  DEFAULT_RETRY_CONFIG,
+  EmptyWalletError,
+  InsufficientFundsError,
+  PaymentCache,
+  RpcError,
+  createCloudCommand,
+  createPaymentFetch,
+  index_default as default,
+  fetchWithRetry,
+  getProxyPort,
+  isBalanceError,
+  isEmptyWalletError,
+  isInsufficientFundsError,
+  isRetryable,
+  isRpcError,
+  startProxy
+};
+//# sourceMappingURL=index.js.map