mnemospark 0.3.0 → 0.5.0

package/dist/index.js

@@ -377,6 +377,34 @@ function normalizePaymentRequired(headers) {
 function normalizePaymentResponse(headers) {
   return headers.get("PAYMENT-RESPONSE") ?? headers.get("x-payment-response") ?? void 0;
 }
+var BYTE_SI_UNITS = ["B", "KB", "MB", "GB", "TB"];
+var BYTE_SI_BASE = 1e3;
+function formatBytesForDisplay(bytes) {
+  if (!Number.isInteger(bytes) || bytes < 0 || !Number.isFinite(bytes)) {
+    throw new Error("formatBytesForDisplay expects a non-negative integer");
+  }
+  if (bytes === 0) {
+    return "0 B";
+  }
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= BYTE_SI_BASE && unitIndex < BYTE_SI_UNITS.length - 1) {
+    value /= BYTE_SI_BASE;
+    unitIndex += 1;
+  }
+  if (unitIndex === 0) {
+    return `${bytes} B`;
+  }
+  const nearestInt = Math.round(value);
+  const pickInt = nearestInt > 0 && Math.abs(value - nearestInt) / Math.max(value, 1e-9) <= 0.01;
+  let rounded = pickInt ? nearestInt : Math.round(value * 10) / 10;
+  if (rounded >= BYTE_SI_BASE && unitIndex < BYTE_SI_UNITS.length - 1) {
+    rounded = Math.round(rounded / BYTE_SI_BASE * 10) / 10;
+    unitIndex += 1;
+  }
+  const text = Number.isInteger(rounded) ? String(rounded) : String(rounded).replace(/\.0$/, "");
+  return `${text} ${BYTE_SI_UNITS[unitIndex]}`;
+}
 
 // src/wallet-signature.ts
 function normalizeWalletSignature(value) {
@@ -1193,6 +1221,9 @@ function parseStoredAes256Key(raw, errorMessage = "Invalid key file format") {
 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 isStorageLsListResponse(r) {
+  return r.mode === "list";
+}
 var AES_GCM_TAG_BYTES = 16;
 function asBooleanOrDefault(value, defaultValue) {
   if (typeof value === "boolean") {
@@ -1280,7 +1311,7 @@ async function decryptDownloadBytes(encryptedBytes, wrappedDekBase64, walletAddr
   }
   return decryptAesGcm(encryptedBytes, dek);
 }
-async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
+async function requestJsonViaProxy(proxyPath, jsonBody, parser, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const baseUrl = normalizeBaseUrl(
     options.proxyBaseUrl ?? `http://127.0.0.1:${PROXY_PORT.toString()}`
@@ -1293,7 +1324,7 @@ async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
       },
       options.correlation
     ),
-    body: JSON.stringify(request)
+    body: JSON.stringify(jsonBody)
   });
   const bodyText = await response.text();
   if (!response.ok) {
@@ -1307,7 +1338,7 @@ async function requestJsonViaProxy(proxyPath, request, parser, options = {}) {
   }
   return parser(payload);
 }
-async function forwardStorageToBackend(path, method, request, options = {}) {
+async function forwardStorageToBackend(path, method, jsonBody, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const backendBaseUrl = (options.backendBaseUrl ?? "").trim();
   const walletSignature = normalizeWalletSignature(options.walletSignature);
@@ -1326,7 +1357,7 @@ async function forwardStorageToBackend(path, method, request, options = {}) {
       "Content-Type": "application/json",
       "X-Wallet-Signature": walletSignature
     },
-    body: JSON.stringify(request)
+    body: JSON.stringify(jsonBody)
   });
   const bodyBuffer = Buffer.from(await response.arrayBuffer());
   return {
@@ -1356,11 +1387,97 @@ function parseStorageObjectRequest(payload) {
     location
   };
 }
+function jsonBodyForObjectRequest(request) {
+  const o = {
+    wallet_address: request.wallet_address,
+    object_key: request.object_key
+  };
+  if (request.location) {
+    o.location = request.location;
+  }
+  return o;
+}
+function jsonBodyForLsRequest(request) {
+  const o = { wallet_address: request.wallet_address };
+  if (request.object_key) {
+    o.object_key = request.object_key;
+  }
+  if (request.location) {
+    o.location = request.location;
+  }
+  if (request.continuation_token) {
+    o.continuation_token = request.continuation_token;
+  }
+  if (typeof request.max_keys === "number") {
+    o.max_keys = request.max_keys;
+  }
+  if (request.prefix) {
+    o.prefix = request.prefix;
+  }
+  return o;
+}
+function parseStorageLsRequestPayload(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  if (!walletAddress) {
+    return null;
+  }
+  const objectKey = asNonEmptyString(record.object_key) ?? void 0;
+  const location = asNonEmptyString(record.location) ?? void 0;
+  const continuation_token = asNonEmptyString(record.continuation_token) ?? void 0;
+  const maxRaw = asNumber(record.max_keys);
+  const max_keys = maxRaw !== null && Number.isInteger(maxRaw) && maxRaw >= 1 ? maxRaw : void 0;
+  const prefix = asNonEmptyString(record.prefix) ?? void 0;
+  return {
+    wallet_address: walletAddress,
+    ...objectKey ? { object_key: objectKey } : {},
+    ...location ? { location } : {},
+    ...continuation_token ? { continuation_token } : {},
+    ...typeof max_keys === "number" ? { max_keys } : {},
+    ...prefix ? { prefix } : {}
+  };
+}
 function parseStorageLsResponse(payload) {
   const record = asRecord(payload);
   if (!record) {
     throw new Error("Invalid ls response payload");
   }
+  if (record.list_mode === true) {
+    const bucket2 = asNonEmptyString(record.bucket) ?? asNonEmptyString(record.bucket_name);
+    const rawObjects = record.objects;
+    if (!bucket2 || !Array.isArray(rawObjects)) {
+      throw new Error("ls list response is missing required fields");
+    }
+    const objects = [];
+    for (const item of rawObjects) {
+      const row = asRecord(item);
+      if (!row) {
+        continue;
+      }
+      const key2 = asNonEmptyString(row.key);
+      const sizeBytes2 = asNumber(row.size_bytes);
+      if (!key2 || sizeBytes2 === null || !Number.isInteger(sizeBytes2) || sizeBytes2 < 0) {
+        continue;
+      }
+      const last_modified = asNonEmptyString(row.last_modified) ?? void 0;
+      objects.push({ key: key2, size_bytes: sizeBytes2, last_modified });
+    }
+    const is_truncated = asBooleanOrDefault(record.is_truncated, false);
+    const nextRaw = record.next_continuation_token;
+    const next_continuation_token = nextRaw === void 0 || nextRaw === null ? null : String(nextRaw);
+    return {
+      mode: "list",
+      success: asBooleanOrDefault(record.success, true),
+      list_mode: true,
+      bucket: bucket2,
+      objects,
+      is_truncated,
+      next_continuation_token
+    };
+  }
   const key = asNonEmptyString(record.key) ?? asNonEmptyString(record.object_key);
   const sizeBytes = asNumber(record.size_bytes);
   const bucket = asNonEmptyString(record.bucket) ?? asNonEmptyString(record.bucket_name);
@@ -1368,7 +1485,11 @@ function parseStorageLsResponse(payload) {
   if (!key || sizeBytes === null || !bucket) {
     throw new Error("ls response is missing required fields");
   }
+  if (!Number.isInteger(sizeBytes) || sizeBytes < 0) {
+    throw new Error("ls response has invalid size_bytes; expected non-negative integer");
+  }
   return {
+    mode: "stat",
     success: asBooleanOrDefault(record.success, true),
     key,
     size_bytes: sizeBytes,
@@ -1411,12 +1532,17 @@ function parseStorageDownloadProxyResponse(payload) {
   };
 }
 async function requestStorageLsViaProxy(request, options = {}) {
-  return requestJsonViaProxy(STORAGE_LS_PROXY_PATH, request, parseStorageLsResponse, options);
+  return requestJsonViaProxy(
+    STORAGE_LS_PROXY_PATH,
+    jsonBodyForLsRequest(request),
+    parseStorageLsResponse,
+    options
+  );
 }
 async function requestStorageDownloadViaProxy(request, options = {}) {
   return requestJsonViaProxy(
     STORAGE_DOWNLOAD_PROXY_PATH,
-    request,
+    jsonBodyForObjectRequest(request),
     parseStorageDownloadProxyResponse,
     options
   );
@@ -1424,19 +1550,29 @@ async function requestStorageDownloadViaProxy(request, options = {}) {
 async function requestStorageDeleteViaProxy(request, options = {}) {
   return requestJsonViaProxy(
     STORAGE_DELETE_PROXY_PATH,
-    request,
+    jsonBodyForObjectRequest(request),
     parseStorageDeleteResponse,
     options
   );
 }
 async function forwardStorageLsToBackend(request, options = {}) {
-  return forwardStorageToBackend("/storage/ls", "POST", request, options);
+  return forwardStorageToBackend("/storage/ls", "POST", jsonBodyForLsRequest(request), options);
 }
 async function forwardStorageDownloadToBackend(request, options = {}) {
-  return forwardStorageToBackend("/storage/download", "POST", request, options);
+  return forwardStorageToBackend(
+    "/storage/download",
+    "POST",
+    jsonBodyForObjectRequest(request),
+    options
+  );
 }
 async function forwardStorageDeleteToBackend(request, options = {}) {
-  return forwardStorageToBackend("/storage/delete", "POST", request, options);
+  return forwardStorageToBackend(
+    "/storage/delete",
+    "POST",
+    jsonBodyForObjectRequest(request),
+    options
+  );
 }
 async function downloadStorageToDisk(request, backendResponse, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -2272,13 +2408,13 @@ async function startProxy(options) {
           });
           return;
         }
-        const requestPayload = parseStorageObjectRequest(payload);
+        const requestPayload = parseStorageLsRequestPayload(payload);
         if (!requestPayload) {
           logProxyEvent("warn", "proxy_ls_missing_fields");
           emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
           sendJson(res, 400, {
             error: "Bad request",
-            message: "Missing required fields: wallet_address, object_key"
+            message: "Missing required field: wallet_address"
           });
           return;
         }
@@ -2800,6 +2936,259 @@ import { homedir as homedir6 } from "os";
 import { basename as basename2, dirname as dirname5, join as join8, resolve as resolve2 } from "path";
 import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
 
+// src/cloud-ls-format.ts
+import { CronExpressionParser } from "cron-parser";
+var LS_NAME_DISPLAY_MAX = 72;
+var LS_PAY_DISPLAY_MAX = 28;
+var LS_CRON_ID_MAX = 14;
+var LS_TIME_FIELD_WIDTH = 12;
+var MONTHS_SHORT = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+function formatLsTimeFieldUtc(iso, now) {
+  const placeholder = "         -  ".slice(0, LS_TIME_FIELD_WIDTH);
+  if (!iso) {
+    return placeholder.padEnd(LS_TIME_FIELD_WIDTH, " ");
+  }
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) {
+    return placeholder.padEnd(LS_TIME_FIELD_WIDTH, " ");
+  }
+  const mon = MONTHS_SHORT[d.getUTCMonth()] ?? "???";
+  const day = String(d.getUTCDate()).padStart(2, " ");
+  const y = d.getUTCFullYear();
+  const nowY = now.getUTCFullYear();
+  let core;
+  if (y === nowY) {
+    const hh = String(d.getUTCHours()).padStart(2, "0");
+    const mm = String(d.getUTCMinutes()).padStart(2, "0");
+    core = `${mon} ${day} ${hh}:${mm}`;
+  } else {
+    core = `${mon} ${day}  ${y}`;
+  }
+  return core.padEnd(LS_TIME_FIELD_WIDTH, " ");
+}
+function truncateEnd(value, max) {
+  if (value.length <= max) {
+    return value;
+  }
+  if (max <= 1) {
+    return "\u2026";
+  }
+  return `${value.slice(0, max - 1)}\u2026`;
+}
+function truncateMiddle(value, max, suffixMin) {
+  if (value.length <= max) {
+    return value;
+  }
+  if (max < suffixMin + 5) {
+    return truncateEnd(value, max);
+  }
+  const suffixLen = Math.min(suffixMin, max - 5);
+  const prefixLen = max - 3 - suffixLen;
+  return `${value.slice(0, prefixLen)} \u2026 ${value.slice(-suffixLen)}`;
+}
+function formatCronIdCell(cronId, width) {
+  if (!cronId) {
+    return "         -  ".slice(0, width).padStart(width, " ");
+  }
+  const t = truncateEnd(cronId, width);
+  return t.padStart(width, " ");
+}
+function formatPaymentCell(amount, network, maxWidth) {
+  if (amount === null) {
+    return "         -  ".slice(0, maxWidth).padStart(maxWidth, " ");
+  }
+  let s = amount.toFixed(6).replace(/\.?0+$/, "");
+  if (network && network.trim()) {
+    s = `${s} (${network.trim()})`;
+  }
+  return truncateEnd(s, maxWidth).padStart(maxWidth, " ");
+}
+function formatNextCronUtc(schedule, cronStatus, now) {
+  const blank = "         -  ".slice(0, LS_TIME_FIELD_WIDTH).padEnd(LS_TIME_FIELD_WIDTH, " ");
+  if (cronStatus !== "active") {
+    return blank;
+  }
+  try {
+    const expr = CronExpressionParser.parse(schedule, { tz: "UTC", currentDate: now });
+    const next = expr.next().toDate();
+    return formatLsTimeFieldUtc(next.toISOString(), now);
+  } catch {
+    return "?".padEnd(LS_TIME_FIELD_WIDTH, " ");
+  }
+}
+async function prepareRows(objects, walletAddress, datastore, now) {
+  const sorted = [...objects].sort((a, b) => {
+    const ta = a.last_modified ? Date.parse(a.last_modified) : Number.NaN;
+    const tb = b.last_modified ? Date.parse(b.last_modified) : Number.NaN;
+    const aOk = Number.isFinite(ta);
+    const bOk = Number.isFinite(tb);
+    if (aOk && bOk && tb !== ta) {
+      return tb - ta;
+    }
+    if (aOk && !bOk) {
+      return -1;
+    }
+    if (!aOk && bOk) {
+      return 1;
+    }
+    return a.key.localeCompare(b.key);
+  });
+  const rows = [];
+  for (const obj of sorted) {
+    const friendly = await datastore.findLatestFriendlyNameForObjectKey(walletAddress, obj.key);
+    const cp = await datastore.findCronAndPaymentForObjectKey(walletAddress, obj.key);
+    const sizeStr = formatBytesForDisplay(obj.size_bytes);
+    const s3time = formatLsTimeFieldUtc(obj.last_modified, now);
+    let cronIdDisp = null;
+    let nextRun = "         -  ".slice(0, LS_TIME_FIELD_WIDTH).padEnd(LS_TIME_FIELD_WIDTH, " ");
+    let payCell = "";
+    if (cp) {
+      cronIdDisp = cp.cronId;
+      nextRun = formatNextCronUtc(cp.schedule, cp.cronStatus, now);
+      payCell = formatPaymentCell(cp.amount, cp.network, LS_PAY_DISPLAY_MAX);
+    } else {
+      payCell = formatPaymentCell(null, null, LS_PAY_DISPLAY_MAX);
+    }
+    const nameRaw = friendly ? `${friendly} (${obj.key})` : obj.key;
+    rows.push({
+      perm: "----------",
+      ln: " 1",
+      user: "-       ",
+      grp: "-       ",
+      sizeStr,
+      s3time,
+      cronIdRaw: cronIdDisp,
+      nextRun,
+      payRaw: payCell,
+      nameRaw: truncateMiddle(nameRaw, LS_NAME_DISPLAY_MAX, 8)
+    });
+  }
+  return rows;
+}
+function columnWidths(rows) {
+  let sizeW = 4;
+  let cronW = 4;
+  let payW = 3;
+  for (const r of rows) {
+    sizeW = Math.max(sizeW, r.sizeStr.length);
+    const cid = r.cronIdRaw ? truncateEnd(r.cronIdRaw, LS_CRON_ID_MAX) : "";
+    cronW = Math.max(cronW, cid.length || 1);
+    payW = Math.max(payW, r.payRaw.length);
+  }
+  cronW = Math.min(Math.max(cronW, 4), LS_CRON_ID_MAX);
+  payW = Math.min(Math.max(payW, 3), LS_PAY_DISPLAY_MAX);
+  return { sizeW, cronW, payW };
+}
+function renderRow(r, w) {
+  const cronPadded = formatCronIdCell(r.cronIdRaw, w.cronW);
+  const sizePadded = r.sizeStr.padStart(w.sizeW, " ");
+  const payPadded = r.payRaw.padStart(w.payW, " ");
+  return [
+    r.perm,
+    r.ln,
+    r.user,
+    r.grp,
+    sizePadded,
+    r.s3time,
+    cronPadded,
+    r.nextRun,
+    payPadded,
+    r.nameRaw
+  ].join(" ");
+}
+function renderHeader(w) {
+  return [
+    "PERM      ",
+    "LN",
+    "USER    ",
+    "GRP     ",
+    "SIZE".padStart(w.sizeW, " "),
+    "S3_TIME     ".slice(0, LS_TIME_FIELD_WIDTH).padEnd(LS_TIME_FIELD_WIDTH, " "),
+    "CRON".padStart(w.cronW, " "),
+    "NEXT        ".slice(0, LS_TIME_FIELD_WIDTH).padEnd(LS_TIME_FIELD_WIDTH, " "),
+    "PAY".padStart(w.payW, " "),
+    "NAME"
+  ].join(" ");
+}
+async function buildMnemosparkLsMessage(result, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  if (isStorageLsListResponse(result)) {
+    const disclaimer2 = "Names, cron, and payment columns come from this machine's SQLite catalog when available; `-` means unknown locally. S3 is authoritative for which keys exist.";
+    const legend2 = "Legend: S3_TIME and NEXT are UTC. NEXT is the next cron fire from the stored expression.";
+    const bucketLine = `bucket: ${result.bucket}`;
+    const sortLine = "sorted by: S3 last_modified descending (missing dates last), then key ascending.";
+    if (result.objects.length === 0) {
+      const lines = [disclaimer2, "", bucketLine, "", "No objects in this bucket."];
+      return lines.join("\n");
+    }
+    const rows = await prepareRows(result.objects, ctx.walletAddress, ctx.datastore, now);
+    const w2 = columnWidths(rows);
+    const header2 = renderHeader(w2);
+    const bodyLines = rows.map((r) => renderRow(r, w2));
+    const totalLine = `total ${String(result.objects.length)}`;
+    const truncLine = result.is_truncated ? "List truncated; more objects in bucket." : null;
+    const prose2 = [disclaimer2, legend2, bucketLine, sortLine, totalLine, truncLine].filter((x) => Boolean(x)).join("\n");
+    const fence2 = ["```", [header2, ...bodyLines].join("\n"), "```"].join("\n");
+    return `${prose2}
+
+${fence2}`;
+  }
+  const friendly = await ctx.datastore.findLatestFriendlyNameForObjectKey(
+    ctx.walletAddress,
+    result.key
+  );
+  const cp = await ctx.datastore.findCronAndPaymentForObjectKey(ctx.walletAddress, result.key);
+  const sizeStr = formatBytesForDisplay(result.size_bytes);
+  const s3time = formatLsTimeFieldUtc(void 0, now);
+  let payCell = formatPaymentCell(null, null, LS_PAY_DISPLAY_MAX);
+  let cronIdDisp = null;
+  let nextRun = "         -  ".slice(0, LS_TIME_FIELD_WIDTH).padEnd(LS_TIME_FIELD_WIDTH, " ");
+  if (cp) {
+    cronIdDisp = cp.cronId;
+    nextRun = formatNextCronUtc(cp.schedule, cp.cronStatus, now);
+    payCell = formatPaymentCell(cp.amount, cp.network, LS_PAY_DISPLAY_MAX);
+  }
+  const nameShown = truncateMiddle(
+    friendly ? `${friendly} (${result.key})` : result.key,
+    LS_NAME_DISPLAY_MAX,
+    8
+  );
+  const prep = {
+    perm: "----------",
+    ln: " 1",
+    user: "-       ",
+    grp: "-       ",
+    sizeStr,
+    s3time,
+    cronIdRaw: cronIdDisp,
+    nextRun,
+    payRaw: payCell,
+    nameRaw: nameShown
+  };
+  const w = columnWidths([prep]);
+  const header = renderHeader(w);
+  const line = renderRow(prep, w);
+  const disclaimer = "Names, cron, and payment columns come from this machine's SQLite catalog when available; `-` means unknown locally.";
+  const legend = "Legend: S3_TIME and NEXT are UTC.";
+  const prose = [disclaimer, legend, `bucket: ${result.bucket}`, ""].join("\n");
+  const fence = ["```", [header, line].join("\n"), "```"].join("\n");
+  return `${prose}
+${fence}`;
+}
+
 // src/cloud-datastore.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { mkdir as mkdir4 } from "fs/promises";
@@ -2835,6 +3224,7 @@ async function createCloudDatastore(homeDir) {
     const nextDb = new DatabaseSyncCtor(dbPath);
     nextDb.exec("PRAGMA journal_mode=WAL;");
     nextDb.exec("PRAGMA foreign_keys=ON;");
+    nextDb.exec("PRAGMA busy_timeout=5000;");
     nextDb.exec(`
       CREATE TABLE IF NOT EXISTS schema_migrations (
         version INTEGER PRIMARY KEY,
@@ -2883,6 +3273,7 @@ async function createCloudDatastore(homeDir) {
         updated_at TEXT NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_cron_jobs_object_key ON cron_jobs(object_key);
+      CREATE INDEX IF NOT EXISTS idx_cron_jobs_quote_id ON cron_jobs(quote_id);
 
       CREATE TABLE IF NOT EXISTS operations (
         operation_id TEXT PRIMARY KEY,
@@ -3083,6 +3474,38 @@ async function createCloudDatastore(homeDir) {
       if (!row) return null;
       return { cronId: row.cron_id, objectId: row.object_id };
     }, null),
+    findCronByQuoteId: async (quoteId) => safe(() => {
+      const row = db.prepare(
+        `SELECT cron_id, object_id, object_key, quote_id, schedule, command, status
+             FROM cron_jobs WHERE quote_id = ? ORDER BY updated_at DESC LIMIT 1`
+      ).get(quoteId);
+      if (!row) return null;
+      return {
+        cron_id: row.cron_id,
+        object_id: row.object_id,
+        object_key: row.object_key,
+        quote_id: row.quote_id,
+        schedule: row.schedule,
+        command: row.command,
+        status: row.status
+      };
+    }, null),
+    findPaymentByQuoteId: async (quoteId) => safe(() => {
+      const row = db.prepare(
+        `SELECT quote_id, wallet_address, trans_id, amount, network, status, settled_at
+             FROM payments WHERE quote_id = ? LIMIT 1`
+      ).get(quoteId);
+      if (!row) return null;
+      return {
+        quote_id: row.quote_id,
+        wallet_address: row.wallet_address,
+        trans_id: row.trans_id,
+        amount: row.amount,
+        network: row.network,
+        status: row.status,
+        settled_at: row.settled_at
+      };
+    }, null),
     upsertOperation: async (row) => {
       await safe(() => {
         const ts = nowIso();
@@ -3209,7 +3632,63 @@ async function createCloudDatastore(homeDir) {
              WHERE wallet_address = ? AND friendly_name = ? AND is_active = 1`
       ).get(normalizedWalletAddress, friendlyName);
       return Number(row?.cnt ?? 0);
-    }, 0)
+    }, 0),
+    findLatestFriendlyNameForObjectKey: async (walletAddress, objectKey) => safe(() => {
+      const w = normalizeWalletAddress(walletAddress);
+      const byKey = db.prepare(
+        `SELECT friendly_name
+             FROM friendly_names
+             WHERE wallet_address = ? AND object_key = ? AND is_active = 1
+             ORDER BY created_at DESC
+             LIMIT 1`
+      ).get(w, objectKey);
+      if (byKey) {
+        return byKey.friendly_name;
+      }
+      const obj = db.prepare(
+        `SELECT object_id FROM objects WHERE wallet_address = ? AND object_key = ? LIMIT 1`
+      ).get(w, objectKey);
+      if (!obj) {
+        return null;
+      }
+      const byObj = db.prepare(
+        `SELECT friendly_name
+             FROM friendly_names
+             WHERE wallet_address = ? AND object_id = ? AND is_active = 1
+             ORDER BY created_at DESC
+             LIMIT 1`
+      ).get(w, obj.object_id);
+      return byObj?.friendly_name ?? null;
+    }, null),
+    findCronAndPaymentForObjectKey: async (walletAddress, objectKey) => safe(() => {
+      const w = normalizeWalletAddress(walletAddress);
+      const cron = db.prepare(
+        `SELECT c.cron_id, c.quote_id, c.schedule, c.status
+             FROM cron_jobs c
+             INNER JOIN objects o ON o.object_id = c.object_id
+             WHERE c.object_key = ? AND o.wallet_address = ?
+             ORDER BY c.updated_at DESC
+             LIMIT 1`
+      ).get(objectKey, w);
+      if (!cron) {
+        return null;
+      }
+      const pay = db.prepare(
+        `SELECT amount, network, status
+             FROM payments
+             WHERE quote_id = ? AND wallet_address = ?
+             LIMIT 1`
+      ).get(cron.quote_id, w);
+      return {
+        cronId: cron.cron_id,
+        schedule: cron.schedule,
+        quoteId: cron.quote_id,
+        cronStatus: cron.status,
+        amount: pay?.amount ?? null,
+        network: pay?.network ?? null,
+        paymentStatus: pay?.status ?? null
+      };
+    }, null)
   };
 }
 
@@ -3229,7 +3708,16 @@ 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_PAYMENT_SETTLE = "--quote-id and --wallet-address";
 var REQUIRED_STORAGE_OBJECT = "--wallet-address and one of (--object-key | --name [--latest|--at])";
+var REQUIRED_LS = "--wallet-address (for one object add --object-key or --name [--latest|--at]; omit both to list the bucket)";
+var PAYMENT_SETTLE_FLAG_NAMES = /* @__PURE__ */ new Set([
+  "quote-id",
+  "wallet-address",
+  "object-id",
+  "object-key",
+  "storage-price"
+]);
 var BOOLEAN_SELECTOR_FLAGS = /* @__PURE__ */ new Set(["latest"]);
 var BOOLEAN_ASYNC_FLAGS = /* @__PURE__ */ new Set(["async"]);
 var BOOLEAN_OP_STATUS_FLAGS = /* @__PURE__ */ new Set(["cancel"]);
@@ -3262,9 +3750,13 @@ var CLOUD_HELP_TEXT = [
   "  Purpose: upload an encrypted object using a valid quote-id.",
   "  Required: " + REQUIRED_UPLOAD,
   "",
-  "\u2022 `/mnemospark_cloud ls --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
-  "  Purpose: look up remote object metadata.",
-  "  Required: " + REQUIRED_STORAGE_OBJECT,
+  "\u2022 `/mnemospark_cloud payment-settle --quote-id <quote-id> --wallet-address <addr> [--object-id <id>] [--object-key <key>] [--storage-price <n>]`",
+  "  Purpose: settle storage payment for a quote (e.g. monthly cron). Uses the same proxy + x402 path as upload pre-settlement.",
+  "  Required: --quote-id, --wallet-address (wallet private key must match the address).",
+  "",
+  "\u2022 `/mnemospark_cloud ls --wallet-address <addr> [--object-key <key> | --name <friendly-name> | omit both to list bucket] [--latest|--at <timestamp>]`",
+  "  Purpose: stat one object or list all keys in the wallet bucket (S3).",
+  "  Required: " + REQUIRED_LS,
   "",
   "\u2022 `/mnemospark_cloud download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`",
   "  Purpose: fetch an object to local disk.",
@@ -3296,7 +3788,7 @@ var CLOUD_HELP_TEXT = [
   "\u2022 `/mnemospark_cloud op-status --operation-id <id>`",
   "\u2022 `/mnemospark_cloud op-status --operation-id <id> --cancel`",
   "",
-  "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."
+  "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. Commands price-storage, upload, ls, download, delete, and payment-settle require --wallet-address."
 ].join("\n");
 var UnsupportedBackupPlatformError = class extends Error {
   constructor(platform) {
@@ -3367,6 +3859,18 @@ function parseObjectSelector(flags) {
   if (objectKey) return { objectKey };
   return { nameSelector: { name, latest, at } };
 }
+function parseLsObjectSelector(flags) {
+  const objectKey = flags["object-key"]?.trim();
+  const name = flags.name?.trim();
+  const latest = flags.latest === "true";
+  const at = flags.at?.trim();
+  if (objectKey && name) return null;
+  if (latest && at) return null;
+  if (!objectKey && !name && (latest || at)) return null;
+  if (objectKey) return { objectKey };
+  if (name) return { nameSelector: { name, latest, at } };
+  return {};
+}
 function parseStorageObjectRequestInput(flags, selector) {
   const walletAddress = flags["wallet-address"]?.trim();
   if (!walletAddress) {
@@ -3537,20 +4041,76 @@ function parseCloudArgs(args) {
       }
     };
   }
+  if (subcommand === "payment-settle") {
+    const flags = parseNamedFlags(rest);
+    if (!flags) {
+      return { mode: "payment-settle-invalid" };
+    }
+    for (const key of Object.keys(flags)) {
+      if (!PAYMENT_SETTLE_FLAG_NAMES.has(key)) {
+        return { mode: "payment-settle-invalid" };
+      }
+    }
+    const quoteId = flags["quote-id"]?.trim();
+    const walletAddress = flags["wallet-address"]?.trim();
+    if (!quoteId || !walletAddress) {
+      return { mode: "payment-settle-invalid" };
+    }
+    let storagePrice;
+    if (flags["storage-price"] !== void 0 && flags["storage-price"] !== "") {
+      const raw = flags["storage-price"]?.trim() ?? "";
+      const n = Number.parseFloat(raw);
+      if (!Number.isFinite(n) || n < 0) {
+        return { mode: "payment-settle-invalid" };
+      }
+      storagePrice = n;
+    }
+    return {
+      mode: "payment-settle",
+      paymentSettleRequest: {
+        quote_id: quoteId,
+        wallet_address: walletAddress,
+        object_id: flags["object-id"]?.trim() || void 0,
+        object_key: flags["object-key"]?.trim() || void 0,
+        storage_price: storagePrice
+      }
+    };
+  }
   if (subcommand === "ls") {
     const flags = parseNamedFlags(rest, BOOLEAN_SELECTOR_FLAGS);
     if (!flags) {
       return { mode: "ls-invalid" };
     }
-    const selector = parseObjectSelector(flags);
-    if (!selector) {
+    const walletAddress = flags["wallet-address"]?.trim() ?? flags["wallet_address"]?.trim() ?? "";
+    if (!walletAddress) {
       return { mode: "ls-invalid" };
     }
-    const request = parseStorageObjectRequestInput(flags, selector);
-    if (!request) {
+    const selector = parseLsObjectSelector(flags);
+    if (!selector) {
       return { mode: "ls-invalid" };
     }
-    return { mode: "ls", storageObjectRequest: request, nameSelector: selector.nameSelector };
+    const location = flags.location?.trim() || flags.region?.trim() || void 0;
+    if (selector.nameSelector) {
+      return {
+        mode: "ls",
+        storageObjectRequest: { wallet_address: walletAddress, location },
+        nameSelector: selector.nameSelector
+      };
+    }
+    if (selector.objectKey) {
+      return {
+        mode: "ls",
+        storageObjectRequest: {
+          wallet_address: walletAddress,
+          object_key: selector.objectKey,
+          location
+        }
+      };
+    }
+    return {
+      mode: "ls",
+      storageObjectRequest: { wallet_address: walletAddress, location }
+    };
   }
   if (subcommand === "download") {
     const flags = parseNamedFlags(rest, BOOLEAN_SELECTOR_AND_ASYNC_FLAGS);
@@ -3897,7 +4457,8 @@ function quoteCronArgument(value) {
 }
 function buildStoragePaymentCronCommand(job) {
   return [
-    "mnemospark-pay-storage",
+    "/mnemospark_cloud",
+    "payment-settle",
     "--quote-id",
     quoteCronArgument(job.quoteId),
     "--wallet-address",
@@ -4186,16 +4747,28 @@ function extractUploadErrorMessage(error) {
   }
   return message;
 }
+function extractLsErrorMessage(error) {
+  if (!(error instanceof Error)) {
+    return null;
+  }
+  const message = error.message.trim();
+  if (!message) {
+    return null;
+  }
+  if (message.startsWith("ls response") || message.startsWith("ls list response") || message.startsWith("Invalid ls response payload")) {
+    return `Cannot list storage object: ${message}`;
+  }
+  if (message === "formatBytesForDisplay expects a non-negative integer") {
+    return "Cannot list storage object: ls response has invalid size_bytes; expected non-negative integer";
+  }
+  return null;
+}
 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 /mnemospark_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 createInProcessSubagentOrchestrator() {
   const sessions = /* @__PURE__ */ new Map();
   const completeSession = async (sessionId, handler) => {
@@ -4319,10 +4892,12 @@ function createCloudCommand(options = {}) {
           requestStorageLsFn: options.requestStorageLsFn ?? requestStorageLsViaProxy,
           requestStorageDownloadFn: options.requestStorageDownloadFn ?? requestStorageDownloadViaProxy,
           requestStorageDeleteFn: options.requestStorageDeleteFn ?? requestStorageDeleteViaProxy,
+          requestPaymentSettleViaProxyFn: options.requestPaymentSettleViaProxyFn ?? requestPaymentSettleViaProxy,
           objectLogHomeDir: options.objectLogHomeDir ?? options.backupOptions?.homeDir,
           backupOptions: options.backupOptions,
           proxyQuoteOptions: options.proxyQuoteOptions,
           proxyUploadOptions: options.proxyUploadOptions,
+          proxySettleOptions: options.proxySettleOptions,
           proxyUploadConfirmOptions: options.proxyUploadConfirmOptions,
           subagentOrchestrator,
           proxyStorageOptions: options.proxyStorageOptions
@@ -4371,7 +4946,23 @@ async function resolveFriendlyNameFromManifest(params, homeDir) {
 }
 async function resolveNameSelectorIfNeeded(datastore, request, selector, homeDir) {
   if (!selector) {
-    const parsedRequest2 = parseStorageObjectRequest(request);
+    const walletAddress = request.wallet_address?.trim();
+    if (!walletAddress) {
+      return { error: "Cannot resolve storage object request." };
+    }
+    const objectKey = request.object_key?.trim();
+    if (!objectKey) {
+      const listRequest = { wallet_address: walletAddress };
+      if (request.location) {
+        listRequest.location = request.location;
+      }
+      return { request: listRequest };
+    }
+    const parsedRequest2 = parseStorageObjectRequest({
+      wallet_address: walletAddress,
+      object_key: objectKey,
+      location: request.location
+    });
     if (!parsedRequest2) {
       return { error: "Cannot resolve storage object request." };
     }
@@ -4432,6 +5023,21 @@ async function resolveNameSelectorIfNeeded(datastore, request, selector, homeDir
     degradedWarning
   };
 }
+function toStorageObjectRequestOrError(request, missingKeyMessage) {
+  const key = request.object_key?.trim();
+  if (!key) {
+    return { ok: false, error: missingKeyMessage };
+  }
+  const parsed = parseStorageObjectRequest({
+    wallet_address: request.wallet_address,
+    object_key: key,
+    location: request.location
+  });
+  if (!parsed) {
+    return { ok: false, error: "Cannot resolve storage object request." };
+  }
+  return { ok: true, request: parsed };
+}
 async function emitCloudEvent(eventType, details, homeDir) {
   await appendJsonlEvent(
     "events.jsonl",
@@ -4486,6 +5092,117 @@ function buildRequestCorrelation(forcedOperationId, forcedTraceId) {
   const traceId = forcedTraceId?.trim() || randomUUID3();
   return { operationId, traceId };
 }
+function parseTransIdFromPaymentSettleBody(bodyText) {
+  const trimmed = bodyText.trim();
+  if (!trimmed.startsWith("{")) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    const tid = parsed.trans_id;
+    return typeof tid === "string" && tid.trim() ? tid.trim() : null;
+  } catch {
+    return null;
+  }
+}
+async function resolveAmountForPaymentSettle(quoteId, storagePriceFromFlag, datastore, homeDir) {
+  if (storagePriceFromFlag !== void 0 && Number.isFinite(storagePriceFromFlag)) {
+    return storagePriceFromFlag;
+  }
+  const quoteLookup = await datastore.findQuoteById(quoteId);
+  if (quoteLookup && Number.isFinite(quoteLookup.storagePrice)) {
+    return quoteLookup.storagePrice;
+  }
+  const logged = await findLoggedPriceStorageQuote(quoteId, homeDir);
+  if (logged && Number.isFinite(logged.storagePrice)) {
+    return logged.storagePrice;
+  }
+  const payment = await datastore.findPaymentByQuoteId(quoteId);
+  if (payment && Number.isFinite(payment.amount)) {
+    return payment.amount;
+  }
+  return 0;
+}
+async function emitPaymentSettleClientObservationBestEffort(params) {
+  try {
+    const {
+      phase,
+      correlation,
+      quoteId,
+      walletAddress,
+      objectId,
+      objectKey,
+      httpStatus,
+      outcomeStatus,
+      homeDir
+    } = params;
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    if (phase === "start") {
+      await emitCloudEventBestEffort(
+        "payment-settle.started",
+        {
+          operation_id: correlation.operationId,
+          trace_id: correlation.traceId,
+          quote_id: quoteId,
+          wallet_address: walletAddress,
+          object_id: objectId,
+          object_key: objectKey,
+          status: "running"
+        },
+        homeDir
+      );
+      await appendJsonlEvent(
+        "proxy-events.jsonl",
+        {
+          ts,
+          event_type: "payment.settle",
+          status: "start",
+          trace_id: correlation.traceId,
+          operation_id: correlation.operationId,
+          quote_id: quoteId,
+          wallet_address: walletAddress,
+          object_id: objectId ?? null,
+          object_key: objectKey ?? null,
+          details: { source: "client" }
+        },
+        homeDir
+      );
+      return;
+    }
+    const terminal = outcomeStatus ?? "failed";
+    await emitCloudEventBestEffort(
+      "payment-settle.completed",
+      {
+        operation_id: correlation.operationId,
+        trace_id: correlation.traceId,
+        quote_id: quoteId,
+        wallet_address: walletAddress,
+        object_id: objectId,
+        object_key: objectKey,
+        status: terminal === "succeeded" ? "succeeded" : "failed",
+        http_status: httpStatus
+      },
+      homeDir
+    );
+    await appendJsonlEvent(
+      "proxy-events.jsonl",
+      {
+        ts,
+        event_type: "payment.settle",
+        status: "result",
+        trace_id: correlation.traceId,
+        operation_id: correlation.operationId,
+        quote_id: quoteId,
+        wallet_address: walletAddress,
+        object_id: objectId ?? null,
+        object_key: objectKey ?? null,
+        details: { http_status: httpStatus ?? null, source: "client" }
+      },
+      homeDir
+    );
+  } catch {
+  }
+}
 async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const parsed = parseCloudArgs(ctx.args);
   const objectLogHomeDir = options.objectLogHomeDir;
@@ -4501,6 +5218,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const requestStorageLs = options.requestStorageLsFn;
   const requestStorageDownload = options.requestStorageDownloadFn;
   const requestStorageDelete = options.requestStorageDeleteFn;
+  const requestPaymentSettleViaProxy2 = options.requestPaymentSettleViaProxyFn;
   const subagentOrchestrator = options.subagentOrchestrator;
   if (parsed.mode === "help" || parsed.mode === "unknown") {
     return {
@@ -4538,9 +5256,15 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       isError: true
     };
   }
+  if (parsed.mode === "payment-settle-invalid") {
+    return {
+      text: `Cannot settle payment: required arguments are ${REQUIRED_PAYMENT_SETTLE}. Optional: --object-id, --object-key, --storage-price.`,
+      isError: true
+    };
+  }
   if (parsed.mode === "ls-invalid") {
     return {
-      text: `Cannot list storage object: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
+      text: `Cannot list storage object: required arguments are ${REQUIRED_LS}.`,
       isError: true
     };
   }
@@ -4682,6 +5406,142 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
     }
     return formatOperationStatus(operation);
   }
+  if (parsed.mode === "payment-settle") {
+    const req = parsed.paymentSettleRequest;
+    let walletKey;
+    try {
+      walletKey = await resolveWalletKey(objectLogHomeDir);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { text: message.trim() || "Cannot resolve wallet key.", isError: true };
+    }
+    const walletAccount = privateKeyToAccount5(walletKey);
+    if (walletAccount.address.toLowerCase() !== req.wallet_address.toLowerCase()) {
+      return {
+        text: `Cannot settle payment: wallet key address ${walletAccount.address} does not match --wallet-address ${req.wallet_address}.`,
+        isError: true
+      };
+    }
+    const correlation = buildRequestCorrelation();
+    const settleFetch = createPayment(walletKey).fetch;
+    const objectId = req.object_id;
+    const objectKey = req.object_key;
+    await emitPaymentSettleClientObservationBestEffort({
+      phase: "start",
+      correlation,
+      quoteId: req.quote_id,
+      walletAddress: req.wallet_address,
+      objectId,
+      objectKey,
+      homeDir: objectLogHomeDir
+    });
+    let settleResult;
+    try {
+      settleResult = await requestPaymentSettleViaProxy2(req.quote_id, req.wallet_address, {
+        ...options.proxySettleOptions,
+        correlation,
+        fetchImpl: (input, init) => settleFetch(input, init)
+      });
+    } catch (err) {
+      const amountErr = await resolveAmountForPaymentSettle(
+        req.quote_id,
+        req.storage_price,
+        datastore,
+        objectLogHomeDir
+      );
+      await datastore.upsertPayment({
+        quote_id: req.quote_id,
+        wallet_address: req.wallet_address,
+        trans_id: null,
+        amount: amountErr,
+        network: null,
+        status: "settle_failed",
+        settled_at: null
+      });
+      const cronErr = await datastore.findCronByQuoteId(req.quote_id);
+      if (cronErr) {
+        await datastore.upsertCronJob({ ...cronErr, status: "active" });
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      await emitPaymentSettleClientObservationBestEffort({
+        phase: "result",
+        correlation,
+        quoteId: req.quote_id,
+        walletAddress: req.wallet_address,
+        objectId,
+        objectKey,
+        outcomeStatus: "failed",
+        homeDir: objectLogHomeDir
+      });
+      return { text: `Payment settle failed: ${msg}`, isError: true };
+    }
+    const amount = await resolveAmountForPaymentSettle(
+      req.quote_id,
+      req.storage_price,
+      datastore,
+      objectLogHomeDir
+    );
+    const transId = settleResult.status === 200 ? parseTransIdFromPaymentSettleBody(settleResult.bodyText ?? "") : null;
+    if (settleResult.status === 200) {
+      await datastore.upsertPayment({
+        quote_id: req.quote_id,
+        wallet_address: req.wallet_address,
+        trans_id: transId,
+        amount,
+        network: null,
+        status: "settled",
+        settled_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const cronRow = await datastore.findCronByQuoteId(req.quote_id);
+      if (cronRow) {
+        await datastore.upsertCronJob({ ...cronRow, status: "active" });
+      }
+      await emitPaymentSettleClientObservationBestEffort({
+        phase: "result",
+        correlation,
+        quoteId: req.quote_id,
+        walletAddress: req.wallet_address,
+        objectId,
+        objectKey,
+        httpStatus: settleResult.status,
+        outcomeStatus: "succeeded",
+        homeDir: objectLogHomeDir
+      });
+      return {
+        text: transId ? `Payment settled for quote ${req.quote_id} (trans_id: ${transId}).` : `Payment settled for quote ${req.quote_id}.`
+      };
+    }
+    await datastore.upsertPayment({
+      quote_id: req.quote_id,
+      wallet_address: req.wallet_address,
+      trans_id: transId,
+      amount,
+      network: null,
+      status: "settle_failed",
+      settled_at: null
+    });
+    const cronRowFailed = await datastore.findCronByQuoteId(req.quote_id);
+    if (cronRowFailed) {
+      await datastore.upsertCronJob({ ...cronRowFailed, status: "active" });
+    }
+    await emitPaymentSettleClientObservationBestEffort({
+      phase: "result",
+      correlation,
+      quoteId: req.quote_id,
+      walletAddress: req.wallet_address,
+      objectId,
+      objectKey,
+      httpStatus: settleResult.status,
+      outcomeStatus: "failed",
+      homeDir: objectLogHomeDir
+    });
+    const bodySnippet = settleResult.bodyText?.trim();
+    const detail = bodySnippet && bodySnippet.length > 500 ? `${bodySnippet.slice(0, 500)}\u2026` : bodySnippet;
+    return {
+      text: detail ? `Payment settle failed (HTTP ${settleResult.status}): ${detail}` : `Payment settle failed with HTTP ${settleResult.status}.`,
+      isError: true
+    };
+  }
   if ((parsed.mode === "backup" || parsed.mode === "upload" || parsed.mode === "download") && parsed.async) {
     const asyncCorrelation = buildRequestCorrelation();
     const operationId = asyncCorrelation.operationId;
@@ -5192,7 +6052,7 @@ operation-id: ${operationId}`,
       const shouldSettleBeforeUpload = requestStorageUpload !== requestStorageUploadViaProxy;
       if (shouldSettleBeforeUpload) {
         const paymentFetch = createPayment(walletKey).fetch;
-        const settleResult = await requestPaymentSettleViaProxy(
+        const settleResult = await requestPaymentSettleViaProxy2(
           parsed.uploadRequest.quote_id,
           parsed.uploadRequest.wallet_address,
           {
@@ -5399,15 +6259,17 @@ operation-id: ${operationId}`,
         "name_resolution.degraded",
         {
           wallet_address: resolvedRequest.wallet_address,
-          object_key: resolvedRequest.object_key,
+          object_key: resolvedRequest.object_key ?? null,
           warning: resolved.degradedWarning
         },
         objectLogHomeDir
       );
     }
+    const objectKeyForLs = resolvedRequest.object_key?.trim();
+    const isBucketList = !objectKeyForLs;
     const correlation = buildRequestCorrelation();
     const operationId = correlation.operationId;
-    const knownObject = await datastore.findObjectByObjectKey(resolvedRequest.object_key);
+    const knownObject = isBucketList ? null : await datastore.findObjectByObjectKey(objectKeyForLs);
     const operationObjectId = knownObject?.object_id ?? null;
     await datastore.upsertOperation({
       operation_id: operationId,
@@ -5441,17 +6303,23 @@ operation-id: ${operationId}`,
           operation_id: operationId,
           trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
-          object_key: resolvedRequest.object_key,
-          status: "succeeded"
+          object_key: resolvedRequest.object_key ?? null,
+          status: "succeeded",
+          list_mode: isBucketList
         },
         objectLogHomeDir
       );
-      const lsText = formatStorageLsUserMessage(lsResult, resolvedRequest.object_key);
+      const lsText = await buildMnemosparkLsMessage(lsResult, {
+        walletAddress: resolvedRequest.wallet_address,
+        datastore
+      });
       return {
         text: resolved.degradedWarning ? `${resolved.degradedWarning}
+
 ${lsText}` : lsText
       };
-    } catch {
+    } catch (error) {
+      const lsErrorMessage = extractLsErrorMessage(error) ?? "Cannot list storage object";
       await datastore.upsertOperation({
         operation_id: operationId,
         type: "ls",
@@ -5459,7 +6327,7 @@ ${lsText}` : lsText
         quote_id: null,
         status: "failed",
         error_code: "LS_FAILED",
-        error_message: "Cannot list storage object"
+        error_message: lsErrorMessage
       });
       await emitCloudEventBestEffort(
         "ls.completed",
@@ -5467,13 +6335,14 @@ ${lsText}` : lsText
           operation_id: operationId,
           trace_id: correlation.traceId,
           wallet_address: resolvedRequest.wallet_address,
-          object_key: resolvedRequest.object_key,
-          status: "failed"
+          object_key: resolvedRequest.object_key ?? null,
+          status: "failed",
+          list_mode: isBucketList
         },
         objectLogHomeDir
       );
       return {
-        text: "Cannot list storage object",
+        text: lsErrorMessage,
         isError: true
       };
     }
@@ -5488,7 +6357,14 @@ ${lsText}` : lsText
     if (resolved.error || !resolved.request) {
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
-    const resolvedRequest = resolved.request;
+    const narrowed = toStorageObjectRequestOrError(
+      resolved.request,
+      `Cannot download file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`
+    );
+    if (!narrowed.ok) {
+      return { text: narrowed.error, isError: true };
+    }
+    const resolvedRequest = narrowed.request;
     if (resolved.degradedWarning) {
       await emitCloudEventBestEffort(
         "name_resolution.degraded",
@@ -5586,7 +6462,14 @@ ${downloadText}` : downloadText
     if (resolved.error || !resolved.request) {
       return { text: resolved.error ?? "Cannot resolve storage object request.", isError: true };
     }
-    const resolvedRequest = resolved.request;
+    const narrowedDelete = toStorageObjectRequestOrError(
+      resolved.request,
+      `Cannot delete file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`
+    );
+    if (!narrowedDelete.ok) {
+      return { text: narrowedDelete.error, isError: true };
+    }
+    const resolvedRequest = narrowedDelete.request;
     if (resolved.degradedWarning) {
       await emitCloudEventBestEffort(
         "name_resolution.degraded",