mnemospark 2026.4.7 → 2026.4.9

package/README.md

@@ -5,6 +5,8 @@ _No forms. No email. Just Base. 💙_
 
 mnemospark is an agentic service layer for OpenClaw plus a standalone x402 payment + verification backend. It enables encrypted, authenticated, fully autonomous cloud and data workflows—paid via x402 with USDC on Base. No human onboarding. No API keys. The blockchain transaction is the record.
 
+For the story behind the product—agent-native encrypted cloud storage on x402 with USDC on Base—see the [launch post on Paragraph](https://paragraph.com/@mnemospark/launched-mnemospark-agent-native-encrypted-cloud-storage-on-x402-usdc).
+
 ---
 
 ## What is mnemospark?
@@ -28,10 +30,10 @@ openclaw plugins install mnemospark --dangerously-force-unsafe-install
 openclaw gateway start
 ```
 
-> Plugin registration is done by `openclaw plugins install mnemospark`.
-> The install also bundles the `skills/mnemospark` skill package so the main agent can delegate mnemospark workflows.
+Plugin registration is done by `openclaw plugins install mnemospark`.
+The install also bundles the `skills/mnemospark` skill package so the main agent can delegate mnemospark workflows. Tell your agent to read it!
 
-By default the plugin uses the production mnemospark API at **https://api.mnemospark.ai**. Set **`MNEMOSPARK_BACKEND_API_BASE_URL`** only when you need a different endpoint (for example staging or a private API URL).
+By default the plugin uses the mnemospark API at **https://api.mnemospark.ai**.
 
 ### 2) Restart gateway after updates
 

package/dist/cli.js

@@ -1189,6 +1189,7 @@ function parseStoredAes256Key(raw, errorMessage = "Invalid key file format") {
 
 // src/cloud-storage.ts
 var STORAGE_LS_PROXY_PATH = "/mnemospark/storage/ls";
+var STORAGE_LS_WEB_SESSION_PROXY_PATH = "/mnemospark/storage/ls-web/session";
 var STORAGE_DOWNLOAD_PROXY_PATH = "/mnemospark/storage/download";
 var STORAGE_DELETE_PROXY_PATH = "/mnemospark/storage/delete";
 function isStorageLsListResponse(r) {
@@ -1432,6 +1433,13 @@ function jsonBodyForLsRequest(request) {
   }
   return o;
 }
+function jsonBodyForLsWebSessionRequest(request) {
+  const o = { wallet_address: request.wallet_address };
+  if (request.location) {
+    o.location = request.location;
+  }
+  return o;
+}
 function parseStorageLsRequestPayload(payload) {
   const record = asRecord(payload);
   if (!record) {
@@ -1456,6 +1464,21 @@ function parseStorageLsRequestPayload(payload) {
     ...prefix ? { prefix } : {}
   };
 }
+function parseStorageLsWebSessionRequestPayload(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    return null;
+  }
+  const walletAddress = asNonEmptyString(record.wallet_address);
+  if (!walletAddress) {
+    return null;
+  }
+  const location = asNonEmptyString(record.location) ?? void 0;
+  return {
+    wallet_address: walletAddress,
+    ...location ? { location } : {}
+  };
+}
 function parseStorageLsResponse(payload) {
   const record = asRecord(payload);
   if (!record) {
@@ -1513,6 +1536,23 @@ function parseStorageLsResponse(payload) {
     object_id: objectId
   };
 }
+function parseStorageLsWebSessionResponse(payload) {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new Error("Invalid ls-web session response payload");
+  }
+  const code = asNonEmptyString(record.code) ?? asNonEmptyString(record.exchange_code);
+  const appUrl = asNonEmptyString(record.app_url) ?? asNonEmptyString(record.appUrl) ?? void 0;
+  const expiresAt = asNonEmptyString(record.expires_at) ?? asNonEmptyString(record.expiresAt) ?? void 0;
+  if (!code || !expiresAt) {
+    throw new Error("ls-web session response is missing required fields");
+  }
+  return {
+    code,
+    ...appUrl ? { app_url: appUrl } : {},
+    expires_at: expiresAt
+  };
+}
 function parseStorageDeleteResponse(payload) {
   const record = asRecord(payload);
   if (!record) {
@@ -1555,6 +1595,14 @@ async function requestStorageLsViaProxy(request, options = {}) {
     options
   );
 }
+async function requestStorageLsWebSessionViaProxy(request, options = {}) {
+  return requestJsonViaProxy(
+    STORAGE_LS_WEB_SESSION_PROXY_PATH,
+    jsonBodyForLsWebSessionRequest(request),
+    parseStorageLsWebSessionResponse,
+    options
+  );
+}
 async function requestStorageDownloadViaProxy(request, options = {}) {
   return requestJsonViaProxy(
     STORAGE_DOWNLOAD_PROXY_PATH,
@@ -1574,6 +1622,14 @@ async function requestStorageDeleteViaProxy(request, options = {}) {
 async function forwardStorageLsToBackend(request, options = {}) {
   return forwardStorageToBackend("/storage/ls", "POST", jsonBodyForLsRequest(request), options);
 }
+async function forwardStorageLsWebSessionToBackend(request, options = {}) {
+  return forwardStorageToBackend(
+    "/storage/ls-web/session",
+    "POST",
+    jsonBodyForLsWebSessionRequest(request),
+    options
+  );
+}
 async function forwardStorageDownloadToBackend(request, options = {}) {
   return forwardStorageToBackend(
     "/storage/download",
@@ -2552,6 +2608,101 @@ async function startProxy(options) {
       }
       return;
     }
+    if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_LS_WEB_SESSION_PROXY_PATH)) {
+      const correlation = createProxyCorrelation(req.headers);
+      logProxyEvent("info", "proxy_ls_web_session_received");
+      emitProxyEvent("request.received", "start", correlation, {
+        path: STORAGE_LS_WEB_SESSION_PROXY_PATH
+      });
+      try {
+        let payload;
+        try {
+          payload = await readProxyJsonBody(req);
+        } catch {
+          logProxyEvent("warn", "proxy_ls_web_session_invalid_json");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "invalid_json" });
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Invalid JSON body for /mnemospark cloud ls-web"
+          });
+          return;
+        }
+        const requestPayload = parseStorageLsWebSessionRequestPayload(payload);
+        if (!requestPayload) {
+          logProxyEvent("warn", "proxy_ls_web_session_missing_fields");
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "missing_fields" });
+          sendJson(res, 400, {
+            error: "Bad request",
+            message: "Missing required field: wallet_address"
+          });
+          return;
+        }
+        correlation.wallet_address = requestPayload.wallet_address;
+        if (requestPayload.wallet_address.toLowerCase() !== proxyWalletAddressLower) {
+          logProxyEvent("warn", "proxy_ls_web_session_wallet_mismatch");
+          emitProxyTerminalFromStatus(correlation, 403, { reason: "wallet_mismatch" });
+          sendJson(res, 403, {
+            error: "wallet_proof_invalid",
+            message: "wallet proof invalid"
+          });
+          return;
+        }
+        const walletSignature = await createBackendWalletSignature(
+          "POST",
+          "/storage/ls-web/session",
+          requestPayload.wallet_address
+        );
+        if (!walletSignature) {
+          logProxyEvent("warn", "proxy_ls_web_session_wallet_signature_missing");
+          sendWalletRequired(res);
+          emitProxyTerminalFromStatus(correlation, 400, { reason: "wallet_signature_missing" });
+          return;
+        }
+        emitProxyEvent("storage.call", "start", correlation, { target: "storage/ls-web/session" });
+        const backendResponse = await forwardStorageLsWebSessionToBackend(requestPayload, {
+          backendBaseUrl: MNEMOSPARK_BACKEND_API_BASE_URL,
+          walletSignature
+        });
+        logProxyEvent("info", "proxy_ls_web_session_backend_response", {
+          status: backendResponse.status
+        });
+        emitProxyEvent("storage.call", "result", correlation, { status: backendResponse.status });
+        const authFailure = normalizeBackendAuthFailure(
+          backendResponse.status,
+          backendResponse.bodyText
+        );
+        if (authFailure) {
+          logProxyEvent("warn", "proxy_ls_web_session_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);
+          emitProxyTerminalFromStatus(correlation, authFailure.status, { reason: "auth_failure" });
+          return;
+        }
+        const responseHeaders = createBackendForwardHeaders(backendResponse);
+        res.writeHead(backendResponse.status, responseHeaders);
+        res.end(backendResponse.bodyText);
+        emitProxyTerminalFromStatus(correlation, backendResponse.status);
+      } catch (err) {
+        emitProxyEvent("terminal.failure", "failure", correlation, {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        logProxyEvent("error", "proxy_ls_web_session_forward_failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        sendJson(res, 502, {
+          error: "proxy_error",
+          message: `Failed to forward /mnemospark cloud ls-web session: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return;
+    }
     if (req.method === "POST" && matchesProxyPath(req.url, STORAGE_DOWNLOAD_PROXY_PATH)) {
       const correlation = createProxyCorrelation(req.headers);
       logProxyEvent("info", "proxy_download_received");
@@ -4257,6 +4408,13 @@ var lsSchema = {
     { name: "region" }
   ]
 };
+var lsWebSchema = {
+  args: [
+    { name: "wallet-address", aliases: ["wallet"], required: true },
+    { name: "location" },
+    { name: "region" }
+  ]
+};
 var downloadSchema = {
   args: [
     { name: "wallet-address", aliases: ["wallet"], required: true },
@@ -4572,6 +4730,10 @@ var CLOUD_HELP_TEXT = [
   "  Purpose: stat one object or list all keys in the wallet bucket (S3).",
   "  Required: " + REQUIRED_LS,
   "",
+  "\u2022 `/mnemospark cloud ls-web wallet-address:<addr>`",
+  "  Purpose: run `ls` in list mode (identical output), then mint a short-lived web session and print a browse URL + expiry.",
+  "  Required: wallet-address:<addr>",
+  "",
   "\u2022 `/mnemospark cloud download wallet-address:<addr> [object-key:<object-key> | name:<friendly-name>] [latest:true|at:<timestamp>] [async:true] [orchestrator:<inline|subagent>] [timeout-seconds:<n>]`",
   "  Purpose: fetch an object to local disk.",
   "  Required: " + REQUIRED_STORAGE_OBJECT,
@@ -4987,6 +5149,26 @@ function parseCloudArgs(args) {
       }
     };
   }
+  if (subcommand === "ls-web") {
+    const parsed = parseCommandArgs(rest, lsWebSchema);
+    if (!parsed.ok) {
+      return {
+        mode: "arg-parse-failure",
+        errors: parsed.errors,
+        warnings: mergeArgParseWarnings(normWarnings, parsed.warnings)
+      };
+    }
+    const flags = valuesToStringRecord(parsed.values);
+    const walletAddress = flags["wallet-address"]?.trim() ?? "";
+    if (!walletAddress) {
+      return { mode: "ls-web-invalid" };
+    }
+    const location = flags.location?.trim() || flags.region?.trim() || void 0;
+    return {
+      mode: "ls-web",
+      storageObjectRequest: { wallet_address: walletAddress, location }
+    };
+  }
   if (subcommand === "ls") {
     const parsed = parseCommandArgs(rest, lsSchema);
     if (!parsed.ok) {
@@ -5922,6 +6104,7 @@ function createCloudCommand(options = {}) {
           nowDateFn: options.nowDateFn ?? (() => /* @__PURE__ */ new Date()),
           idempotencyKeyFn: options.idempotencyKeyFn ?? randomUUID4,
           requestStorageLsFn: options.requestStorageLsFn ?? requestStorageLsViaProxy,
+          requestStorageLsWebSessionFn: options.requestStorageLsWebSessionFn ?? requestStorageLsWebSessionViaProxy,
           requestStorageDownloadFn: options.requestStorageDownloadFn ?? requestStorageDownloadViaProxy,
           requestStorageDeleteFn: options.requestStorageDeleteFn ?? requestStorageDeleteViaProxy,
           requestPaymentSettleViaProxyFn: options.requestPaymentSettleViaProxyFn ?? requestPaymentSettleViaProxy,
@@ -6221,6 +6404,7 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
   const nowDateFn = options.nowDateFn;
   const idempotencyKeyFn = options.idempotencyKeyFn;
   const requestStorageLs = options.requestStorageLsFn;
+  const requestStorageLsWebSession = options.requestStorageLsWebSessionFn;
   const requestStorageDownload = options.requestStorageDownloadFn;
   const requestStorageDelete = options.requestStorageDeleteFn;
   const requestPaymentSettleViaProxy2 = options.requestPaymentSettleViaProxyFn;
@@ -6289,6 +6473,12 @@ async function runCloudCommandHandler(ctx, options, executionContext = {}) {
       isError: true
     };
   }
+  if (parsed.mode === "ls-web-invalid") {
+    return {
+      text: "Cannot list storage objects: wallet-address is required.",
+      isError: true
+    };
+  }
   if (parsed.mode === "download-invalid") {
     return {
       text: `Cannot download file: required arguments are ${REQUIRED_STORAGE_OBJECT}.`,
@@ -7441,6 +7631,124 @@ operation-id: ${operationId}`,
       };
     }
   }
+  if (parsed.mode === "ls-web") {
+    const walletAddress = parsed.storageObjectRequest.wallet_address?.trim() ?? "";
+    if (!walletAddress) {
+      return { text: "Cannot list storage objects: wallet-address is required.", isError: true };
+    }
+    const listRequest = { wallet_address: walletAddress };
+    const location = parsed.storageObjectRequest.location?.trim();
+    if (location) {
+      listRequest.location = location;
+    }
+    const correlation = buildRequestCorrelation();
+    const operationId = correlation.operationId;
+    await datastore.upsertOperation({
+      operation_id: operationId,
+      type: "ls",
+      object_id: null,
+      quote_id: null,
+      status: "started",
+      error_code: null,
+      error_message: null
+    });
+    try {
+      const lsResult = await requestStorageLs(listRequest, {
+        ...options.proxyStorageOptions,
+        correlation
+      });
+      if (!lsResult.success) {
+        throw new Error("ls failed");
+      }
+      const lsText = await buildMnemosparkLsMessage(lsResult, {
+        walletAddress,
+        datastore
+      });
+      const session = await requestStorageLsWebSession(
+        { wallet_address: walletAddress, ...location ? { location } : {} },
+        {
+          ...options.proxyStorageOptions,
+          correlation
+        }
+      );
+      const browseUrl = session.app_url?.trim() || `https://app.mnemospark.ai/?code=${encodeURIComponent(session.code)}`;
+      const now = nowDateFn();
+      const expiresDate = new Date(session.expires_at);
+      const expiresUtc = Number.isNaN(expiresDate.valueOf()) ? session.expires_at : expiresDate.toUTCString();
+      let rel = "";
+      if (!Number.isNaN(expiresDate.valueOf())) {
+        const ms = expiresDate.getTime() - now.getTime();
+        if (ms > 0) {
+          const totalMinutes = Math.floor(ms / 6e4);
+          const hours = Math.floor(totalMinutes / 60);
+          const minutes = totalMinutes % 60;
+          rel = ` (in ~${hours}h ${minutes}m)`;
+        }
+      }
+      await datastore.upsertOperation({
+        operation_id: operationId,
+        type: "ls",
+        object_id: null,
+        quote_id: null,
+        status: "succeeded",
+        error_code: null,
+        error_message: null
+      });
+      await emitCloudEventBestEffort(
+        "ls.completed",
+        {
+          operation_id: operationId,
+          trace_id: correlation.traceId,
+          wallet_address: walletAddress,
+          object_key: null,
+          status: "succeeded",
+          list_mode: true
+        },
+        mnemosparkHomeDir
+      );
+      const urlBlock = ["```", browseUrl, "```"].join("\n");
+      const webBlock = [
+        "Browse your files in the web app:",
+        "",
+        urlBlock,
+        "",
+        `Expires: ${expiresUtc}${rel}`
+      ].join("\n");
+      return {
+        text: `${lsText}
+
+${webBlock}`
+      };
+    } catch (error) {
+      const lsFriendly = extractLsErrorMessage(error);
+      const message = lsFriendly ?? extractUploadErrorMessage(error) ?? "Cannot run ls-web";
+      await datastore.upsertOperation({
+        operation_id: operationId,
+        type: "ls",
+        object_id: null,
+        quote_id: null,
+        status: "failed",
+        error_code: "LS_WEB_FAILED",
+        error_message: message
+      });
+      await emitCloudEventBestEffort(
+        "ls.completed",
+        {
+          operation_id: operationId,
+          trace_id: correlation.traceId,
+          wallet_address: walletAddress,
+          object_key: null,
+          status: "failed",
+          list_mode: true
+        },
+        mnemosparkHomeDir
+      );
+      return {
+        text: message,
+        isError: true
+      };
+    }
+  }
   if (parsed.mode === "download") {
     const resolved = await resolveNameSelectorIfNeeded(
       datastore,