mnemospark 1.3.0 → 1.5.1

package/README.md

@@ -52,6 +52,20 @@ openclaw gateway restart
 
 ---
 
+## OpenClaw Install Warning
+
+If OpenClaw shows a warning about **dangerous code patterns** when installing or updating mnemospark—often mentioning shell execution (`child_process`), environment variables, and network access—here is what is going on.
+
+mnemospark is an **OpenClaw plugin** that talks to **your configured mnemospark backend**, runs a **local HTTP proxy** for storage workflows, and can **invoke the `openclaw` CLI** and system tools when needed (for example creating archives with `tar` or running `npm` when you use the update command). Those features use the same low-level Node.js APIs—`child_process` and `fetch`—that security tools also associate with risky software, so the installer may warn you even when the behavior is intentional and benign.
+
+We also read **environment variables** you set on purpose (such as `MNEMOSPARK_BACKEND_API_BASE_URL`, `MNEMOSPARK_PROXY_PORT`, or wallet-related settings) so you can configure the plugin without editing code. Automated scans sometimes flag “environment access + network” as a possible credential-stealing pattern. In mnemospark, that combination exists because the plugin is **configurable and networked by design**, not because we are harvesting your unrelated secrets.
+
+mnemospark is **open source**. If you want extra assurance, review the repository, search for `child_process`, `process.env`, and `fetch`, and run your own tests in a safe environment. The warning helps keep the ecosystem safe; for mnemospark it reflects **capabilities**, not a finding of malicious intent.
+
+Have ChatGPT or your favorite LLM evaluate the mnemospark codebase. Here's a [starter link](https://chatgpt.com/share/69ce6119-52cc-8394-b9f9-c06528d85ea7).
+
+---
+
 ## Slash command reference
 
 **Syntax**
@@ -93,8 +107,6 @@ Use other regions by changing `provider:` and `region:` (defaults: `aws` / `us-e
 /mnemospark cloud upload quote-id:<quote-id> wallet-address:<addr> object-id:<id> object-id-hash:<sha256>
 ```
 
-On **OpenClaw 2026.4.x**, the first successful upload applies the **Mnemospark Renewal Agent Runbook** for you: it ensures a dedicated agent (`mnemospark-renewal` by default) with `tools.deny: ["subagents"]` and `tools.exec.ask: "off"`, updates `~/.openclaw/exec-approvals.json` so `/usr/bin/node` is allowlisted for that agent, runs `openclaw config validate`, and best-effort `openclaw gateway restart`. It then registers the monthly renewal cron with `--no-deliver`, `--agent`, and a `Command: /usr/bin/node …/dist/cli.js cloud payment-settle --renewal …` message. Override paths with `MNEMOSPARK_CRON_AGENT_ID` and `MNEMOSPARK_CRON_NODE_BIN` if your system differs.
-
 ### List objects
 
 ```text
@@ -156,8 +168,7 @@ Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 | `MNEMOSPARK_PROXY_VERBOSE_404`       | When `1`, `true`, or `yes`, the local HTTP proxy includes a `message` field on **404** responses describing supported paths. Default (unset) is a generic JSON body `{ "error": "Not found" }` only (reduces reconnaissance).             |
 | `MNEMOSPARK_CRON_AGENT_ID`           | OpenClaw agent id used for the monthly renewal cron (default `mnemospark-renewal`).                                                                                                                                                       |
 | `MNEMOSPARK_CRON_NODE_BIN`           | Absolute path to `node` for renewal cron exec (default `/usr/bin/node`).                                                                                                                                                                  |
-| `MNEMOSPARK_DISABLE_OPENCLAW_PREREQ` | Set to `1` to skip automatic runbook application (for advanced debugging only).                                                                                                                                                           |
-| `MNEMOSPARK_SKIP_GATEWAY_RESTART`    | Set to `1` to skip best-effort `openclaw gateway restart` after prerequisite writes.                                                                                                                                                      |
+| `MNEMOSPARK_DISABLE_OPENCLAW_PREREQ` | Set to `1` to skip automatic runbook application everywhere it runs (plugin load, CLI install/update; for advanced debugging only).                                                                                                       |
 
 ---
 
@@ -171,15 +182,9 @@ Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 
 ---
 
-## OpenClaw Install Warning
-
-If OpenClaw shows a warning about **dangerous code patterns** when installing or updating mnemospark—often mentioning shell execution (`child_process`), environment variables, and network access—here is what is going on.
+## mnemospark Exec Approvals Runbook
 
-mnemospark is an **OpenClaw plugin** that talks to **your configured mnemospark backend**, runs a **local HTTP proxy** for storage workflows, and can **invoke the `openclaw` CLI** and system tools when needed (for example creating archives with `tar` or running `npm` when you use the update command). Those features use the same low-level Node.js APIs—`child_process` and `fetch`—that security tools also associate with risky software, so the installer may warn you even when the behavior is intentional and benign.
-
-We also read **environment variables** you set on purpose (such as `MNEMOSPARK_BACKEND_API_BASE_URL`, `MNEMOSPARK_PROXY_PORT`, or wallet-related settings) so you can configure the plugin without editing code. Automated scans sometimes flag “environment access + network” as a possible credential-stealing pattern. In mnemospark, that combination exists because the plugin is **configurable and networked by design**, not because we are harvesting your unrelated secrets.
-
-mnemospark is **open source**. If you want extra assurance, review the repository, search for `child_process`, `process.env`, and `fetch`, and run your own tests in a safe environment. The warning helps keep the ecosystem safe; for mnemospark it reflects **capabilities**, not a finding of malicious intent.
+On **OpenClaw 2026.4.x**, the **Mnemospark Renewal Agent Runbook** is applied when you install or update mnemospark (including `npx mnemospark install`, `npx mnemospark update`, `openclaw plugins install`, and when the gateway loads the plugin): it ensures a dedicated agent (`mnemospark-renewal` by default) with `tools.deny: ["subagents"]` and `tools.exec.ask: "off"`, updates `~/.openclaw/exec-approvals.json` so `/usr/bin/node` is allowlisted for that agent, and runs `openclaw config validate`. OpenClaw restarts the gateway when a plugin is installed or updated; mnemospark does not call `openclaw gateway restart` itself. After a **successful upload**, mnemospark registers the monthly renewal cron only (`--no-deliver`, `--agent`, and a `Command: /usr/bin/node …/dist/cli.js cloud payment-settle --renewal …` message). Override paths with `MNEMOSPARK_CRON_AGENT_ID` and `MNEMOSPARK_CRON_NODE_BIN` if your system differs.
 
 ---
 
@@ -189,6 +194,7 @@ mnemospark is **open source**. If you want extra assurance, review the repositor
 - **402 payment required**: expected in challenge flow; ensure client retries with payment authorization.
 - **Upload/storage backend errors**: verify cloud permissions (e.g. bucket access + IAM role rights).
 - **Command not recognized**: confirm plugin installed and gateway restarted.
+- **Renewal cron / exec failures after upload**: ensure mnemospark was installed or updated through the normal path so the runbook ran (gateway load, `npx mnemospark install`, or `openclaw plugins install`). If the gateway never loaded the plugin, run install again or restart the gateway.
 - **One-step operation correlation**: run `./skills/mnemospark/scripts/debug-operation.sh <operation-id>` (or omit ID to use latest).
 
 ---

package/dist/cli.js

@@ -3211,6 +3211,20 @@ function renderHeader(w) {
     HDR_FILE_OR_KEY
   ].join(" ");
 }
+function formatLsCommandCopyBlock(commandLine) {
+  return ["```", commandLine, "```"].join("\n");
+}
+function formatLsWhatsNextFooter(walletAddress) {
+  const downloadLine = `/mnemospark cloud download wallet-address:${walletAddress} [object-key:<object-key> | name:<friendly-name>] [latest:true|at:<timestamp>] [async:true] [orchestrator:<inline|subagent>] [timeout-seconds:<n>]`;
+  const deleteLine = `/mnemospark cloud delete wallet-address:${walletAddress} [object-key:<object-key> | name:<friendly-name>] [latest:true|at:<timestamp>]`;
+  return [
+    "What's next? Would you like to download or delete a file:",
+    "",
+    formatLsCommandCopyBlock(downloadLine),
+    "",
+    formatLsCommandCopyBlock(deleteLine)
+  ].join("\n");
+}
 async function buildMnemosparkLsMessage(result, ctx) {
   const now = ctx.now ?? /* @__PURE__ */ new Date();
   if (isStorageLsListResponse(result)) {
@@ -3227,7 +3241,9 @@ async function buildMnemosparkLsMessage(result, ctx) {
     const fence2 = ["```", [header2, ...bodyLines].join("\n"), "```"].join("\n");
     return `${prose2}
 
-${fence2}`;
+${fence2}
+
+${formatLsWhatsNextFooter(ctx.walletAddress)}`;
   }
   const friendly = await ctx.datastore.findLatestFriendlyNameForObjectKey(
     ctx.walletAddress,
@@ -3264,7 +3280,9 @@ ${fence2}`;
   const fence = ["```", [header, line].join("\n"), "```"].join("\n");
   return `${prose}
 
-${fence}`;
+${fence}
+
+${formatLsWhatsNextFooter(ctx.walletAddress)}`;
 }
 
 // src/cloud-datastore.ts
@@ -4392,7 +4410,7 @@ async function ensureOpenClawRenewalPrerequisites(options = {}) {
     parsed = JSON.parse(configRaw);
   } catch {
     throw new Error(
-      `openclaw.json at ${configPath} is not valid JSON; fix or remove it before upload.`
+      `openclaw.json at ${configPath} is not valid JSON; fix or remove it before applying renewal prerequisites.`
     );
   }
   const agents = isRecord(parsed.agents) ? parsed.agents : {};
@@ -4424,13 +4442,6 @@ async function ensureOpenClawRenewalPrerequisites(options = {}) {
     await writeFileAtomic(execPath, `${JSON.stringify(mergedExec, null, 2)}
 `);
   }
-  const skipRestart = options.skipGatewayRestart ?? process.env.MNEMOSPARK_SKIP_GATEWAY_RESTART === "1";
-  if (!skipRestart && (agentChanged || execChanged)) {
-    try {
-      await runOpenClawCli(["gateway", "restart", "--json"], homeDir);
-    } catch {
-    }
-  }
 }
 
 // src/cloud-command.ts
@@ -5335,7 +5346,6 @@ async function removeStoragePaymentCronJob(cronId, adapter) {
   return adapter.remove(cronId);
 }
 async function createStoragePaymentCronJob(upload, storagePrice, openClawCronAdapter, openClawHomeDir, nowDateFn = () => /* @__PURE__ */ new Date()) {
-  await ensureOpenClawRenewalPrerequisites({ homeDir: openClawHomeDir });
   const renewalFields = {
     walletAddress: upload.addr,
     objectId: upload.object_id,
@@ -7950,6 +7960,14 @@ async function promptOrRunOpenClawPluginInstall() {
     });
     if (exitCode === 0) {
       await ensureMnemosparkInPluginsAllow();
+      try {
+        await ensureOpenClawRenewalPrerequisites();
+      } catch (err) {
+        console.warn(
+          "[mnemospark] Renewal prerequisites:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
     } else {
       console.log(
         "\n[mnemospark] OpenClaw plugin install did not succeed. Run manually: openclaw plugins install mnemospark"
@@ -8049,6 +8067,14 @@ async function runUpdate() {
     try {
       execSync(`npm install mnemospark@${latest}`, { stdio: "inherit" });
       console.log(`[mnemospark] Updated to ${latest}.`);
+      try {
+        await ensureOpenClawRenewalPrerequisites();
+      } catch (err) {
+        console.warn(
+          "[mnemospark] Renewal prerequisites:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
     } catch {
       console.log(
         "[mnemospark] npm install failed. You can update manually: npm install mnemospark@latest"