mnemospark 0.4.0 → 0.6.0

package/dist/cli.js

@@ -332,6 +332,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) {
@@ -1148,6 +1176,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") {
@@ -1235,7 +1266,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()}`
@@ -1248,7 +1279,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) {
@@ -1262,7 +1293,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);
@@ -1281,7 +1312,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 {
@@ -1311,11 +1342,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);
@@ -1323,7 +1440,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,
@@ -1366,12 +1487,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
   );
@@ -1379,19 +1505,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;
@@ -2227,13 +2363,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;
         }
@@ -2749,6 +2885,254 @@ 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_S3_COL_WIDTH = 12;
+var LS_NEXT_COL_WIDTH = Math.max(LS_S3_COL_WIDTH, "NEXT PAYMENT DATE".length);
+var HDR_SIZE = "SIZE";
+var HDR_S3_TIME = "S3_TIME";
+var HDR_CRON_JOB = "CRON JOB";
+var HDR_NEXT_PAYMENT = "NEXT PAYMENT DATE";
+var HDR_AMOUNT_DUE = "AMOUNT DUE";
+var HDR_FILE_OR_KEY = "FILE NAME OR OBJECT-KEY";
+var MONTHS_SHORT = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+function formatLsTimeFieldUtc(iso, now, fieldWidth = LS_S3_COL_WIDTH) {
+  const placeholder = "         -  ".slice(0, fieldWidth);
+  if (!iso) {
+    return placeholder.padEnd(fieldWidth, " ");
+  }
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) {
+    return placeholder.padEnd(fieldWidth, " ");
+  }
+  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(fieldWidth, " ");
+}
+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_NEXT_COL_WIDTH).padEnd(LS_NEXT_COL_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, LS_NEXT_COL_WIDTH);
+  } catch {
+    return "?".padEnd(LS_NEXT_COL_WIDTH, " ");
+  }
+}
+function buildLsProseIntro(bucket) {
+  return [
+    "\u2601\uFE0F mnemospark cloud files",
+    `S3 bucket: ${bucket}`,
+    "The columns: CRON JOB, NEXT PAYMENT DATE, AMOUNT DUE, FILE NAME are from this host's mnemospark SQLite catalog",
+    "mnemospark cloud only stores the OBJECT-KEY for privacy"
+  ];
+}
+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, LS_S3_COL_WIDTH);
+    let cronIdDisp = null;
+    let nextRun = "         -  ".slice(0, LS_NEXT_COL_WIDTH).padEnd(LS_NEXT_COL_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({
+      sizeStr,
+      s3time,
+      cronIdRaw: cronIdDisp,
+      nextRun,
+      payRaw: payCell,
+      nameRaw: truncateMiddle(nameRaw, LS_NAME_DISPLAY_MAX, 8)
+    });
+  }
+  return rows;
+}
+function columnWidths(rows) {
+  let sizeW = HDR_SIZE.length;
+  let s3W = Math.max(LS_S3_COL_WIDTH, HDR_S3_TIME.length);
+  let nextW = LS_NEXT_COL_WIDTH;
+  let cronW = HDR_CRON_JOB.length;
+  let payW = HDR_AMOUNT_DUE.length;
+  for (const r of rows) {
+    sizeW = Math.max(sizeW, r.sizeStr.length);
+    s3W = Math.max(s3W, r.s3time.length);
+    nextW = Math.max(nextW, r.nextRun.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, HDR_CRON_JOB.length), LS_CRON_ID_MAX);
+  payW = Math.min(Math.max(payW, HDR_AMOUNT_DUE.length), LS_PAY_DISPLAY_MAX);
+  return { sizeW, s3W, cronW, nextW, payW };
+}
+function renderRow(r, w) {
+  const cronPadded = formatCronIdCell(r.cronIdRaw, w.cronW);
+  return [
+    r.sizeStr.padStart(w.sizeW, " "),
+    r.s3time.padEnd(w.s3W, " "),
+    cronPadded,
+    r.nextRun.padEnd(w.nextW, " "),
+    r.payRaw.padStart(w.payW, " "),
+    r.nameRaw
+  ].join(" ");
+}
+function renderHeader(w) {
+  return [
+    HDR_SIZE.padStart(w.sizeW, " "),
+    HDR_S3_TIME.padEnd(w.s3W, " "),
+    HDR_CRON_JOB.padStart(w.cronW, " "),
+    HDR_NEXT_PAYMENT.padEnd(w.nextW, " "),
+    HDR_AMOUNT_DUE.padStart(w.payW, " "),
+    HDR_FILE_OR_KEY
+  ].join(" ");
+}
+async function buildMnemosparkLsMessage(result, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  if (isStorageLsListResponse(result)) {
+    const intro = buildLsProseIntro(result.bucket);
+    if (result.objects.length === 0) {
+      return [...intro, "", "No objects in this bucket."].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 truncLine = result.is_truncated ? "List truncated; more objects in bucket." : null;
+    const prose2 = [...intro, ...truncLine ? [truncLine] : []].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, LS_S3_COL_WIDTH);
+  let payCell = formatPaymentCell(null, null, LS_PAY_DISPLAY_MAX);
+  let cronIdDisp = null;
+  let nextRun = "         -  ".slice(0, LS_NEXT_COL_WIDTH).padEnd(LS_NEXT_COL_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 = {
+    sizeStr,
+    s3time,
+    cronIdRaw: cronIdDisp,
+    nextRun,
+    payRaw: payCell,
+    nameRaw: nameShown
+  };
+  const w = columnWidths([prep]);
+  const header = renderHeader(w);
+  const line = renderRow(prep, w);
+  const prose = buildLsProseIntro(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";
@@ -3192,7 +3576,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)
   };
 }
 
@@ -3214,6 +3654,7 @@ var REQUIRED_PRICE_STORAGE = "--wallet-address, --object-id, --object-id-hash, -
 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",
@@ -3257,9 +3698,9 @@ var CLOUD_HELP_TEXT = [
   "  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 <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`",
-  "  Purpose: look up remote object metadata.",
-  "  Required: " + REQUIRED_STORAGE_OBJECT,
+  "\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.",
@@ -3362,6 +3803,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) {
@@ -3572,15 +4025,36 @@ function parseCloudArgs(args) {
     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);
@@ -4217,16 +4691,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) => {
@@ -4404,7 +4890,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." };
     }
@@ -4465,6 +4967,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",
@@ -4691,7 +5208,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   }
   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
     };
   }
@@ -5686,15 +6203,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,
@@ -5728,17 +6247,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",
@@ -5746,7 +6271,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",
@@ -5754,13 +6279,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
       };
     }
@@ -5775,7 +6301,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",
@@ -5873,7 +6406,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",