mnemospark 0.1.15 → 0.1.17

package/dist/cli.js

@@ -2,6 +2,8 @@
 
 // src/proxy.ts
 import { createServer } from "http";
+import { homedir } from "os";
+import { join as join2 } from "path";
 import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
 
 // src/balance.ts
@@ -324,6 +326,7 @@ function normalizeWalletSignature(value) {
 // src/cloud-price-storage.ts
 var PRICE_STORAGE_PROXY_PATH = "/mnemospark/price-storage";
 var UPLOAD_PROXY_PATH = "/mnemospark/upload";
+var UPLOAD_CONFIRM_PROXY_PATH = "/mnemospark/upload/confirm";
 function asStringRecord(value) {
   const record = asRecord(value);
   if (!record) {
@@ -437,6 +440,25 @@ function parseStorageUploadRequest(payload) {
     }
   };
 }
+function parseStorageUploadConfirmRequest(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const quoteId = asNonEmptyString(record.quote_id);
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  const objectKey = asNonEmptyString(record.object_key);
+  const idempotencyKey = asNonEmptyString(record.idempotency_key);
+  if (!quoteId || !walletAddress || !objectKey || !idempotencyKey) {
+    return null;
+  }
+  return {
+    quote_id: quoteId,
+    wallet_address: walletAddress,
+    object_key: objectKey,
+    idempotency_key: idempotencyKey
+  };
+}
 function parseStorageUploadResponse(payload) {
   const record = asRecord(payload);
   if (!record) {
@@ -454,12 +476,16 @@ function parseStorageUploadResponse(payload) {
   const location = asNonEmptyString(record.location);
   const uploadUrl = asNonEmptyString(record.upload_url);
   const uploadHeaders = record.upload_headers === void 0 ? void 0 : asStringRecord(record.upload_headers);
+  const confirmationRequired = typeof record.confirmation_required === "boolean" ? record.confirmation_required : void 0;
   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");
   }
+  if (record.confirmation_required !== void 0 && confirmationRequired === void 0) {
+    throw new Error("Upload response has invalid confirmation_required");
+  }
   return {
     quote_id: quoteId,
     addr,
@@ -472,7 +498,8 @@ function parseStorageUploadResponse(payload) {
     bucket_name: bucketName,
     location,
     upload_url: uploadUrl ?? void 0,
-    upload_headers: uploadHeaders ?? void 0
+    upload_headers: uploadHeaders ?? void 0,
+    confirmation_required: confirmationRequired
   };
 }
 async function requestPriceStorageViaProxy(request, options = {}) {
@@ -501,29 +528,109 @@ async function requestPriceStorageViaProxy(request, options = {}) {
 }
 async function requestStorageUploadViaProxy(request, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
+  const maxRetries = typeof options.maxRetries === "number" && Number.isFinite(options.maxRetries) && options.maxRetries >= 0 ? Math.floor(options.maxRetries) : 2;
   const baseUrl = normalizeBaseUrl(
     options.proxyBaseUrl ?? `http://127.0.0.1:${PROXY_PORT.toString()}`
   );
+  const targetUrl = `${baseUrl}${UPLOAD_PROXY_PATH}`;
   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}`, {
+  const requestBody = JSON.stringify(request);
+  const sendUploadRequest = async () => {
+    const response2 = await fetchImpl(targetUrl, {
+      method: "POST",
+      headers: requestHeaders,
+      body: requestBody
+    });
+    return { response: response2, bodyText: await response2.text() };
+  };
+  let { response, bodyText: responseBody } = await sendUploadRequest();
+  if (response.status === 207) {
+    let parsed207;
+    try {
+      parsed207 = JSON.parse(responseBody);
+    } catch {
+      parsed207 = null;
+    }
+    const retryablePayload = asRecord(parsed207);
+    if (retryablePayload?.upload_failed === true) {
+      let transId = asNonEmptyString(retryablePayload.trans_id) ?? "unknown";
+      let exhaustedRetryableFailures = true;
+      for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        await new Promise((resolve3) => setTimeout(resolve3, 1e3));
+        try {
+          ({ response, bodyText: responseBody } = await sendUploadRequest());
+        } catch {
+          continue;
+        }
+        if (response.ok && response.status !== 207) {
+          let retryPayload;
+          try {
+            retryPayload = JSON.parse(responseBody);
+          } catch {
+            throw new Error("Upload proxy returned invalid JSON");
+          }
+          return parseStorageUploadResponse(retryPayload);
+        }
+        if (response.status === 207) {
+          let retryParsed207;
+          try {
+            retryParsed207 = JSON.parse(responseBody);
+          } catch {
+            retryParsed207 = null;
+          }
+          const retryableRetryPayload = asRecord(retryParsed207);
+          if (retryableRetryPayload?.upload_failed === true) {
+            transId = asNonEmptyString(retryableRetryPayload.trans_id) ?? transId;
+            continue;
+          }
+          exhaustedRetryableFailures = false;
+          break;
+        }
+      }
+      if (exhaustedRetryableFailures) {
+        throw new Error(
+          `Payment confirmed (trans_id: ${transId}) but file storage failed after ${maxRetries} ${maxRetries === 1 ? "retry" : "retries"}. Contact support with your trans_id.`
+        );
+      }
+    }
+  }
+  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 requestStorageUploadConfirmViaProxy(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}${UPLOAD_CONFIRM_PROXY_PATH}`, {
     method: "POST",
-    headers: requestHeaders,
+    headers: {
+      "Content-Type": "application/json"
+    },
     body: JSON.stringify(request)
   });
   const responseBody = await response.text();
   if (!response.ok) {
-    throw new Error(responseBody || `Upload proxy failed with status ${response.status}`);
+    throw new Error(responseBody || `Upload confirm proxy failed with status ${response.status}`);
   }
   let payload;
   try {
     payload = JSON.parse(responseBody);
   } catch {
-    throw new Error("Upload proxy returned invalid JSON");
+    throw new Error("Upload confirm proxy returned invalid JSON");
   }
   return parseStorageUploadResponse(payload);
 }
@@ -623,6 +730,35 @@ async function forwardStorageUploadToBackend(request, options = {}) {
     paymentResponse: normalizePaymentResponse(response.headers)
   };
 }
+async function forwardStorageUploadConfirmToBackend(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)}/storage/upload/confirm`;
+  const response = await fetchImpl(targetUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Wallet-Signature": walletSignature
+    },
+    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";
@@ -893,6 +1029,14 @@ async function downloadStorageToDisk(request, backendResponse, options = {}) {
 var HEALTH_CHECK_TIMEOUT_MS = 2e3;
 var PORT_RETRY_ATTEMPTS = 5;
 var PORT_RETRY_DELAY_MS = 1e3;
+var DEFAULT_DOWNLOAD_OUTPUT_DIR = join2(homedir(), ".openclaw", "mnemospark", "downloads");
+function resolveDownloadOutputDir() {
+  const configuredOutputDir = process.env.MNEMOSPARK_DOWNLOAD_DIR?.trim();
+  if (configuredOutputDir && configuredOutputDir.length > 0) {
+    return configuredOutputDir;
+  }
+  return DEFAULT_DOWNLOAD_OUTPUT_DIR;
+}
 function matchesProxyPath(url, path) {
   return url === path || url?.startsWith(`${path}?`) === true;
 }
@@ -926,6 +1070,19 @@ function sendJson(res, status, body) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(body));
 }
+function logProxyEvent(level, event, fields = {}) {
+  const payload = JSON.stringify({ event, ...fields });
+  const message = `[mnemospark] ${payload}`;
+  if (level === "error") {
+    console.error(message);
+    return;
+  }
+  if (level === "warn") {
+    console.warn(message);
+    return;
+  }
+  console.info(message);
+}
 function createBackendForwardHeaders(response) {
   const responseHeaders = {
     "Content-Type": response.contentType
@@ -1037,19 +1194,22 @@ async function startProxy(options) {
       console.error(`[mnemospark] Response stream error: ${err.message}`);
     });
     if (req.method === "POST" && matchesProxyPath(req.url, PRICE_STORAGE_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_price_storage_received");
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
+          logProxyEvent("warn", "proxy_price_storage_invalid_json");
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark cloud price-storage"
+            message: "Invalid JSON body for /mnemospark-cloud price-storage"
           });
           return;
         }
         const requestPayload = parsePriceStorageQuoteRequest(payload);
         if (!requestPayload) {
+          logProxyEvent("warn", "proxy_price_storage_missing_fields");
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_id, object_id_hash, gb, provider, region"
@@ -1065,11 +1225,17 @@ async function startProxy(options) {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
         });
+        logProxyEvent("info", "proxy_price_storage_backend_response", {
+          status: backendResponse.status
+        });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
         );
         if (authFailure) {
+          logProxyEvent("warn", "proxy_price_storage_auth_failure", {
+            status: authFailure.status
+          });
           const responseHeaders2 = createBackendForwardHeaders({
             contentType: authFailure.contentType,
             paymentRequired: backendResponse.paymentRequired,
@@ -1083,27 +1249,33 @@ async function startProxy(options) {
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
       } catch (err) {
+        logProxyEvent("error", "proxy_price_storage_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark cloud price-storage: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark-cloud price-storage: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_upload_received");
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
+          logProxyEvent("warn", "proxy_upload_invalid_json");
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark cloud upload"
+            message: "Invalid JSON body for /mnemospark-cloud upload"
           });
           return;
         }
         const requestPayload = parseStorageUploadRequest(payload);
         if (!requestPayload) {
+          logProxyEvent("warn", "proxy_upload_missing_fields");
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: quote_id, wallet_address, object_id, object_id_hash, quoted_storage_price, payload"
@@ -1111,6 +1283,10 @@ async function startProxy(options) {
           return;
         }
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_upload_wallet_mismatch", {
+            request_wallet: requestPayload.wallet_address,
+            proxy_wallet: account.address
+          });
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1123,6 +1299,7 @@ async function startProxy(options) {
           requestPayload.wallet_address
         );
         if (!walletSignature) {
+          logProxyEvent("warn", "proxy_upload_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
           return;
@@ -1134,6 +1311,11 @@ async function startProxy(options) {
         const sufficiency = await uploadBalanceMonitor.checkSufficient(requiredMicros);
         const requiredUSD = uploadBalanceMonitor.formatUSDC(requiredMicros);
         if (!sufficiency.sufficient) {
+          logProxyEvent("warn", "proxy_upload_insufficient_balance", {
+            wallet_address: requestPayload.wallet_address,
+            balance_usd: sufficiency.info.balanceUSD,
+            required_usd: requiredUSD
+          });
           options.onInsufficientFunds?.({
             balanceUSD: sufficiency.info.balanceUSD,
             requiredUSD,
@@ -1143,11 +1325,15 @@ async function startProxy(options) {
             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 /mnemospark cloud upload`
+            help: `Fund wallet ${requestPayload.wallet_address} on Base before running /mnemospark-cloud upload`
           });
           return;
         }
         if (sufficiency.info.isLow) {
+          logProxyEvent("warn", "proxy_upload_low_balance", {
+            wallet_address: requestPayload.wallet_address,
+            balance_usd: sufficiency.info.balanceUSD
+          });
           options.onLowBalance?.({
             balanceUSD: sufficiency.info.balanceUSD,
             walletAddress: requestPayload.wallet_address
@@ -1160,11 +1346,100 @@ async function startProxy(options) {
           legacyPayment: readHeaderValue(req.headers["x-payment"]),
           idempotencyKey: readHeaderValue(req.headers["idempotency-key"])
         });
+        logProxyEvent("info", "proxy_upload_backend_response", {
+          status: backendResponse.status
+        });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          logProxyEvent("warn", "proxy_upload_auth_failure", {
+            status: authFailure.status
+          });
+          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) {
+        logProxyEvent("error", "proxy_upload_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /mnemospark-cloud upload: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
+    if (req.method === "POST" && matchesProxyPath(req.url, UPLOAD_CONFIRM_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_upload_confirm_received");
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          logProxyEvent("warn", "proxy_upload_confirm_invalid_json");
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /mnemospark-cloud upload/confirm"
+          });
+          return;
+        }
+        const requestPayload = parseStorageUploadConfirmRequest(payload);
+        if (!requestPayload) {
+          logProxyEvent("warn", "proxy_upload_confirm_missing_fields");
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required fields: quote_id, wallet_address, object_key, idempotency_key"
+          });
+          return;
+        }
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_upload_confirm_wallet_mismatch", {
+            request_wallet: requestPayload.wallet_address,
+            proxy_wallet: account.address
+          });
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/upload/confirm",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          logProxyEvent("warn", "proxy_upload_confirm_wallet_signature_missing");
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(createWalletRequiredBody());
+          return;
+        }
+        const backendResponse = await forwardStorageUploadConfirmToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        logProxyEvent("info", "proxy_upload_confirm_backend_response", {
+          status: backendResponse.status
+        });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
         );
         if (authFailure) {
+          logProxyEvent("warn", "proxy_upload_confirm_auth_failure", {
+            status: authFailure.status
+          });
           const responseHeaders2 = createBackendForwardHeaders({
             contentType: authFailure.contentType,
             paymentRequired: backendResponse.paymentRequired,
@@ -1178,27 +1453,33 @@ async function startProxy(options) {
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
       } catch (err) {
+        logProxyEvent("error", "proxy_upload_confirm_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark cloud upload: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark-cloud upload/confirm: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_LS_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_ls_received");
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
+          logProxyEvent("warn", "proxy_ls_invalid_json");
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark cloud ls"
+            message: "Invalid JSON body for /mnemospark-cloud ls"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
+          logProxyEvent("warn", "proxy_ls_missing_fields");
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -1206,6 +1487,7 @@ async function startProxy(options) {
           return;
         }
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_ls_wallet_mismatch");
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1218,6 +1500,7 @@ async function startProxy(options) {
           requestPayload.wallet_address
         );
         if (!walletSignature) {
+          logProxyEvent("warn", "proxy_ls_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
           return;
@@ -1226,11 +1509,13 @@ async function startProxy(options) {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
         });
+        logProxyEvent("info", "proxy_ls_backend_response", { status: backendResponse.status });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
         );
         if (authFailure) {
+          logProxyEvent("warn", "proxy_ls_auth_failure", { status: authFailure.status });
           const responseHeaders2 = createBackendForwardHeaders({
             contentType: authFailure.contentType,
             paymentRequired: backendResponse.paymentRequired,
@@ -1244,27 +1529,33 @@ async function startProxy(options) {
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
       } catch (err) {
+        logProxyEvent("error", "proxy_ls_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark cloud ls: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark-cloud ls: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DOWNLOAD_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_download_received");
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
+          logProxyEvent("warn", "proxy_download_invalid_json");
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark cloud download"
+            message: "Invalid JSON body for /mnemospark-cloud download"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
+          logProxyEvent("warn", "proxy_download_missing_fields");
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -1272,6 +1563,7 @@ async function startProxy(options) {
           return;
         }
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_download_wallet_mismatch");
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1284,6 +1576,7 @@ async function startProxy(options) {
           requestPayload.wallet_address
         );
         if (!walletSignature) {
+          logProxyEvent("warn", "proxy_download_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
           return;
@@ -1292,11 +1585,17 @@ async function startProxy(options) {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
         });
+        logProxyEvent("info", "proxy_download_backend_response", {
+          status: backendResponse.status
+        });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
         );
         if (authFailure) {
+          logProxyEvent("warn", "proxy_download_auth_failure", {
+            status: authFailure.status
+          });
           const responseHeaders = createBackendForwardHeaders({
             contentType: authFailure.contentType,
             paymentRequired: backendResponse.paymentRequired,
@@ -1307,12 +1606,22 @@ async function startProxy(options) {
           return;
         }
         if (backendResponse.status < 200 || backendResponse.status >= 300) {
+          logProxyEvent("warn", "proxy_download_backend_non_success", {
+            status: backendResponse.status
+          });
           const responseHeaders = createBackendForwardHeaders(backendResponse);
           res.writeHead(backendResponse.status, responseHeaders);
           res.end(backendResponse.bodyText);
           return;
         }
-        const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse);
+        const downloadResult = await downloadStorageToDisk(requestPayload, backendResponse, {
+          outputDir: resolveDownloadOutputDir()
+        });
+        logProxyEvent("info", "proxy_download_written_to_disk", {
+          key: downloadResult.key,
+          file_path: downloadResult.filePath,
+          bytes_written: downloadResult.bytesWritten
+        });
         sendJson(res, 200, {
           success: true,
           key: downloadResult.key,
@@ -1320,27 +1629,33 @@ async function startProxy(options) {
           bytes_written: downloadResult.bytesWritten
         });
       } catch (err) {
+        logProxyEvent("error", "proxy_download_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark cloud download: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark-cloud download: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
     }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DELETE_PROXY_PATH)) {
+      logProxyEvent("info", "proxy_delete_received");
       try {
         let payload;
         try {
           payload = await readProxyJsonBody(req);
         } catch {
+          logProxyEvent("warn", "proxy_delete_invalid_json");
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Invalid JSON body for /mnemospark cloud delete"
+            message: "Invalid JSON body for /mnemospark-cloud delete"
           });
           return;
         }
         const requestPayload = parseStorageObjectRequest(payload);
         if (!requestPayload) {
+          logProxyEvent("warn", "proxy_delete_missing_fields");
           sendJson(res, 400, {
             error: "Bad request",
             message: "Missing required fields: wallet_address, object_key"
@@ -1348,6 +1663,7 @@ async function startProxy(options) {
           return;
         }
         if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_delete_wallet_mismatch");
           sendJson(res, 403, {
             error: "wallet_proof_invalid",
             message: "wallet proof invalid"
@@ -1360,6 +1676,7 @@ async function startProxy(options) {
           requestPayload.wallet_address
         );
         if (!walletSignature) {
+          logProxyEvent("warn", "proxy_delete_wallet_signature_missing");
           res.writeHead(400, { "Content-Type": "application/json" });
           res.end(createWalletRequiredBody());
           return;
@@ -1368,11 +1685,17 @@ async function startProxy(options) {
           backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
           walletSignature
         });
+        logProxyEvent("info", "proxy_delete_backend_response", {
+          status: backendResponse.status
+        });
         const authFailure = normalizeBackendAuthFailure(
           backendResponse.status,
           backendResponse.bodyText
         );
         if (authFailure) {
+          logProxyEvent("warn", "proxy_delete_auth_failure", {
+            status: authFailure.status
+          });
           const responseHeaders2 = createBackendForwardHeaders({
             contentType: authFailure.contentType,
             paymentRequired: backendResponse.paymentRequired,
@@ -1386,9 +1709,12 @@ async function startProxy(options) {
         res.writeHead(backendResponse.status, responseHeaders);
         res.end(backendResponse.bodyText);
       } catch (err) {
+        logProxyEvent("error", "proxy_delete_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         sendJson(res, 502, {
           error: "proxy_error",
-          message: `Failed to forward /mnemospark cloud delete: ${err instanceof Error ? err.message : String(err)}`
+          message: `Failed to forward /mnemospark-cloud delete: ${err instanceof Error ? err.message : String(err)}`
         });
       }
       return;
@@ -1537,8 +1863,8 @@ async function startProxy(options) {
 
 // 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 { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
 
 // src/wallet-key.ts
@@ -1547,10 +1873,10 @@ function isValidWalletPrivateKey(value) {
 }
 
 // src/auth.ts
-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");
+var LEGACY_WALLET_DIR = join3(homedir2(), ".openclaw", "blockrun");
+var LEGACY_WALLET_FILE = join3(LEGACY_WALLET_DIR, "wallet.key");
+var WALLET_DIR = join3(homedir2(), ".openclaw", "mnemospark", "wallet");
+var WALLET_FILE = join3(WALLET_DIR, "wallet.key");
 async function loadSavedWallet() {
   for (const path of [WALLET_FILE, LEGACY_WALLET_FILE]) {
     try {
@@ -1606,11 +1932,11 @@ async function resolveOrGenerateWalletKey() {
 // src/version.ts
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname2, join as join4 } 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 pkg = require2(join4(__dirname, "..", "package.json"));
 var VERSION = pkg.version;
 var USER_AGENT = `mnemospark/${VERSION}`;
 
@@ -1624,8 +1950,8 @@ import {
 } 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 { homedir as homedir3 } from "os";
+import { basename, dirname as dirname3, join as join5, resolve as resolve2 } from "path";
 import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
 
 // src/x402.ts
@@ -1888,13 +2214,13 @@ function createPaymentFetch(privateKey) {
 
 // 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 BACKUP_DIR_SUBPATH = join5(".openclaw", "mnemospark", "backup");
+var DEFAULT_BACKUP_DIR = join5(homedir3(), BACKUP_DIR_SUBPATH);
+var OBJECT_LOG_SUBPATH = join5(".openclaw", "mnemospark", "object.log");
+var CRON_TABLE_SUBPATH = join5(".openclaw", "mnemospark", "crontab.txt");
+var BLOCKRUN_WALLET_KEY_SUBPATH = join5(".openclaw", "blockrun", "wallet.key");
+var MNEMOSPARK_WALLET_KEY_SUBPATH = join5(".openclaw", "mnemospark", "wallet", "wallet.key");
+var KEY_STORE_SUBPATH = join5(".openclaw", "mnemospark", "keys");
 var INLINE_UPLOAD_MAX_BYTES = 45e5;
 var AES_GCM_NONCE_BYTES = 12;
 var PAYMENT_REMINDER_INTERVAL_DAYS = 30;
@@ -1908,10 +2234,10 @@ var REQUIRED_STORAGE_OBJECT = "--wallet-address, --object-key";
 function expandTilde(path) {
   const trimmed = path.trim();
   if (trimmed === "~") {
-    return homedir2();
+    return homedir3();
   }
   if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
-    return join4(homedir2(), trimmed.slice(2));
+    return join5(homedir3(), trimmed.slice(2));
   }
   return path;
 }
@@ -2095,10 +2421,10 @@ function parseCloudArgs(args) {
   return { mode: "unknown" };
 }
 function resolveObjectLogPath(homeDir) {
-  return join4(homeDir ?? homedir2(), OBJECT_LOG_SUBPATH);
+  return join5(homeDir ?? homedir3(), OBJECT_LOG_SUBPATH);
 }
 function resolveCronTablePath(homeDir) {
-  return join4(homeDir ?? homedir2(), CRON_TABLE_SUBPATH);
+  return join5(homeDir ?? homedir3(), CRON_TABLE_SUBPATH);
 }
 async function appendObjectLogLine(line, homeDir) {
   const objectLogPath = resolveObjectLogPath(homeDir);
@@ -2118,7 +2444,7 @@ async function calculateInputSizeBytes(targetPath) {
   let total = 0;
   const entries = await readdir(targetPath, { withFileTypes: true });
   for (const entry of entries) {
-    total += await calculateInputSizeBytes(join4(targetPath, entry.name));
+    total += await calculateInputSizeBytes(join5(targetPath, entry.name));
   }
   return total;
 }
@@ -2197,7 +2523,7 @@ async function buildBackupObject(targetPathArg, options = {}) {
     throw new Error("Insufficient disk space for backup object");
   }
   const objectId = createObjectId(options);
-  const archivePath = join4(tmpDir, objectId);
+  const archivePath = join5(tmpDir, objectId);
   try {
     await runTarGzip(archivePath, targetPath);
     const archiveStats = await stat(archivePath);
@@ -2502,9 +2828,9 @@ async function resolveWalletPrivateKey(homeDir) {
   if (isValidWalletPrivateKey(envKey)) {
     return envKey;
   }
-  const baseHome = homeDir ?? homedir2();
-  const primaryWalletPath = join4(baseHome, MNEMOSPARK_WALLET_KEY_SUBPATH);
-  const fallbackWalletPath = join4(baseHome, BLOCKRUN_WALLET_KEY_SUBPATH);
+  const baseHome = homeDir ?? homedir3();
+  const primaryWalletPath = join5(baseHome, MNEMOSPARK_WALLET_KEY_SUBPATH);
+  const fallbackWalletPath = join5(baseHome, BLOCKRUN_WALLET_KEY_SUBPATH);
   const fromPrimary = await readWalletKeyIfPresent(primaryWalletPath);
   if (fromPrimary) {
     return fromPrimary;
@@ -2537,8 +2863,8 @@ function encryptAesGcm(plaintext, key, randomFn = randomBytesNode) {
   return Buffer.concat([nonce, ciphertext, tag]);
 }
 async function loadOrCreateKek(walletAddress, homeDir) {
-  const keyPath = join4(
-    homeDir ?? homedir2(),
+  const keyPath = join5(
+    homeDir ?? homedir3(),
     KEY_STORE_SUBPATH,
     `${walletShortHash(walletAddress)}.key`
   );
@@ -2647,7 +2973,7 @@ function formatStorageUploadUserMessage(upload, cronJobId) {
   ].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.`;
+  const statusLine = cronId ? cronDeleted ? `File \`${objectKey}\` has been deleted from the cloud and the cron job \`${cronId}\` has been removed from local mnemospark cron tracking.` : `File \`${objectKey}\` has been deleted from the cloud and the cron job \`${cronId}\` was not found in local mnemospark cron tracking.` : `File \`${objectKey}\` has been deleted from the cloud and no matching cron job was found in local mnemospark cron tracking.`;
   return [statusLine, "Thank you for using mnemospark!"].join("\n");
 }
 function extractUploadErrorMessage(error) {
@@ -2687,6 +3013,7 @@ function createCloudCommand(options = {}) {
   const backupBuilder = options.buildBackupObjectFn ?? buildBackupObject;
   const requestPriceStorageQuote = options.requestPriceStorageQuoteFn ?? requestPriceStorageViaProxy;
   const requestStorageUpload = options.requestStorageUploadFn ?? requestStorageUploadViaProxy;
+  const requestStorageUploadConfirm = options.requestStorageUploadConfirmFn ?? requestStorageUploadConfirmViaProxy;
   const resolveWalletKey = options.resolveWalletPrivateKeyFn ?? resolveWalletPrivateKey;
   const createPayment = options.createPaymentFetchFn ?? createPaymentFetch;
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -2788,7 +3115,7 @@ function createCloudCommand(options = {}) {
           );
           if (!loggedQuote) {
             return {
-              text: "Cannot upload storage object: quote-id not found in object.log. Run /mnemospark cloud price-storage first.",
+              text: "Cannot upload storage object: quote-id not found in object.log. Run /mnemospark-cloud price-storage first.",
               isError: true
             };
           }
@@ -2798,7 +3125,7 @@ function createCloudCommand(options = {}) {
               isError: true
             };
           }
-          const archivePath = join4(
+          const archivePath = join5(
             options.backupOptions?.tmpDir ?? DEFAULT_BACKUP_DIR,
             parsed.uploadRequest.object_id
           );
@@ -2807,7 +3134,7 @@ function createCloudCommand(options = {}) {
             archiveStats = await stat(archivePath);
           } catch {
             return {
-              text: `Cannot upload storage object: local archive not found at ${archivePath}. Run /mnemospark cloud backup first.`,
+              text: `Cannot upload storage object: local archive not found at ${archivePath}. Run /mnemospark-cloud backup first.`,
               isError: true
             };
           }
@@ -2860,22 +3187,43 @@ function createCloudCommand(options = {}) {
             preparedPayload.encryptedContent,
             fetchImpl
           );
-          await appendStorageUploadLog(uploadResponse, objectLogHomeDir, nowDateFn);
-          const cronStoragePriceCandidate = uploadResponse.storage_price ?? loggedQuote.storagePrice;
+          let finalizedUploadResponse = uploadResponse;
+          if (preparedPayload.payload.mode === "presigned" && uploadResponse.confirmation_required === true) {
+            try {
+              finalizedUploadResponse = await requestStorageUploadConfirm(
+                {
+                  quote_id: uploadResponse.quote_id,
+                  wallet_address: parsed.uploadRequest.wallet_address,
+                  object_key: uploadResponse.object_key,
+                  idempotency_key: idempotencyKey
+                },
+                options.proxyUploadConfirmOptions
+              );
+            } catch (confirmError) {
+              const transId = uploadResponse.trans_id ?? "unknown";
+              const confirmMessage = extractUploadErrorMessage(confirmError) ?? "Upload confirmation request failed";
+              throw new Error(
+                `Upload to S3 succeeded, but backend confirmation failed (trans_id: ${transId}, idempotency_key: ${idempotencyKey}). ${confirmMessage}`
+              );
+            }
+          }
+          await appendStorageUploadLog(finalizedUploadResponse, objectLogHomeDir, nowDateFn);
+          const cronStoragePriceCandidate = finalizedUploadResponse.storage_price ?? loggedQuote.storagePrice;
           const cronStoragePrice = Number.isFinite(cronStoragePriceCandidate) && cronStoragePriceCandidate > 0 ? cronStoragePriceCandidate : loggedQuote.storagePrice;
           const cronJob = await createStoragePaymentCronJob(
-            uploadResponse,
+            finalizedUploadResponse,
             cronStoragePrice,
             objectLogHomeDir,
             nowDateFn
           );
           await maybeCleanupLocalBackupArchive(archivePath);
           return {
-            text: formatStorageUploadUserMessage(uploadResponse, cronJob.cronId)
+            text: formatStorageUploadUserMessage(finalizedUploadResponse, cronJob.cronId)
           };
         } catch (error) {
+          const uploadErrorMessage = extractUploadErrorMessage(error);
           return {
-            text: extractUploadErrorMessage(error) ?? "Cannot upload storage object",
+            text: uploadErrorMessage ?? "Cannot upload storage object",
             isError: true
           };
         }
@@ -2909,7 +3257,7 @@ function createCloudCommand(options = {}) {
             throw new Error("download failed");
           }
           return {
-            text: `File ${parsed.storageObjectRequest.object_key} downloaded`
+            text: `File ${parsed.storageObjectRequest.object_key} downloaded to ${downloadResult.file_path}`
           };
         } catch {
           return {
@@ -2961,11 +3309,11 @@ function createCloudCommand(options = {}) {
 
 // src/cli.ts
 import { spawn as spawn2 } from "child_process";
-import { dirname as dirname4, join as join5 } from "path";
+import { dirname as dirname4, join as join6 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
 import { existsSync } from "fs";
-import { homedir as homedir3 } from "os";
+import { homedir as homedir4 } from "os";
 function isHexPrivateKey(value) {
   return typeof value === "string" && /^0x[0-9a-fA-F]{64}$/.test(value.trim());
 }
@@ -3076,14 +3424,14 @@ async function ensureDir(path) {
   await mkdir4(path, { recursive: true });
 }
 async function deployExtensionFiles() {
-  const scriptsSource = join5(PACKAGE_ROOT, "scripts");
+  const scriptsSource = join6(PACKAGE_ROOT, "scripts");
   if (!existsSync(scriptsSource)) return;
-  const mnemoScriptsDir = join5(homedir3(), ".openclaw", "mnemospark", "scripts");
+  const mnemoScriptsDir = join6(homedir4(), ".openclaw", "mnemospark", "scripts");
   await ensureDir(mnemoScriptsDir);
-  const uninstallSrc = join5(scriptsSource, "uninstall.sh");
+  const uninstallSrc = join6(scriptsSource, "uninstall.sh");
   if (existsSync(uninstallSrc)) {
     const content = await readFile3(uninstallSrc);
-    await writeFile4(join5(mnemoScriptsDir, "uninstall.sh"), content, { mode: 493 });
+    await writeFile4(join6(mnemoScriptsDir, "uninstall.sh"), content, { mode: 493 });
   }
 }
 function isOpenClawAvailable() {
@@ -3097,8 +3445,8 @@ function isOpenClawAvailable() {
   });
 }
 function getOpenClawConfigPath() {
-  const stateDir = process.env.OPENCLAW_STATE_DIR ?? join5(homedir3(), ".openclaw");
-  return join5(stateDir, "openclaw.json");
+  const stateDir = process.env.OPENCLAW_STATE_DIR ?? join6(homedir4(), ".openclaw");
+  return join6(stateDir, "openclaw.json");
 }
 async function ensureMnemosparkInPluginsAllow() {
   const configPath = getOpenClawConfigPath();