mnemospark 1.6.0 → 2026.4.7

package/README.md

@@ -31,6 +31,8 @@ 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.
 
+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).
+
 ### 2) Restart gateway after updates
 
 ```bash
@@ -148,20 +150,21 @@ The blockchain transaction is the payment record.
 
 Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 
-| Variable                             | Purpose                                                                                                                                                                                                                                   |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MNEMOSPARK_BACKEND_API_BASE_URL`    | Base URL for the mnemospark backend API (required for the local HTTP proxy to forward storage calls). Example: `https://{api-id}.execute-api.{region}.amazonaws.com/{stage}`.                                                             |
-| `MNEMOSPARK_PROXY_PORT`              | TCP port for the mnemospark HTTP proxy (default `7120`).                                                                                                                                                                                  |
-| `MNEMOSPARK_DOWNLOAD_DIR`            | Directory where the proxy writes downloaded objects (default `~/.openclaw/mnemospark/downloads/`).                                                                                                                                        |
-| `MNEMOSPARK_WALLET_KEY`              | Path to the wallet private key file when not using the default `~/.openclaw/mnemospark/wallet/wallet.key`.                                                                                                                                |
-| `MNEMOSPARK_REMOVE_BACKUP_FILE`      | After a **successful** cloud upload, delete the local backup archive under `~/.openclaw/mnemospark/backup/`. **Default when unset:** remove the file. Set to `0`, `false`, `no`, or `n` to keep it; `1`, `true`, `yes`, or `y` to remove. |
-| `MNEMOSPARK_DISABLED`                | Set to `true` or `1` to disable plugin registration.                                                                                                                                                                                      |
-| `MNEMOSPARK_DISABLE_SQLITE`          | Set to `1` to disable local SQLite (`state.db`); cloud commands that need local state will fail.                                                                                                                                          |
-| `MNEMOSPARK_SQLITE_STRICT`           | Set to `1` so certain SQLite consistency checks (e.g. friendly-name verification after upload) throw instead of warning.                                                                                                                  |
-| `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 everywhere it runs (plugin load, CLI install/update; for advanced debugging only).                                                                                                       |
+| Variable                             | Purpose                                                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MNEMOSPARK_BACKEND_API_BASE_URL`    | Base URL for the mnemospark backend API (required for the local HTTP proxy to forward storage calls). **Default:** `https://api.mnemospark.ai` (production). Set this variable only to override—for example staging or a custom API Gateway URL. |
+| `MNEMOSPARK_PROXY_PORT`              | TCP port for the mnemospark HTTP proxy (default `7120`).                                                                                                                                                                                         |
+| `MNEMOSPARK_DOWNLOAD_DIR`            | Directory where the proxy writes downloaded objects (default `~/.openclaw/mnemospark/downloads/`).                                                                                                                                               |
+| `MNEMOSPARK_WALLET_KEY`              | Path to the wallet private key file when not using the default `~/.openclaw/mnemospark/wallet/wallet.key`.                                                                                                                                       |
+| `MNEMOSPARK_REMOVE_BACKUP_FILE`      | After a **successful** cloud upload, delete the local backup archive under `~/.openclaw/mnemospark/backup/`. **Default when unset:** remove the file. Set to `0`, `false`, `no`, or `n` to keep it; `1`, `true`, `yes`, or `y` to remove.        |
+| `MNEMOSPARK_DISABLED`                | Set to `true` or `1` to disable plugin registration.                                                                                                                                                                                             |
+| `MNEMOSPARK_DISABLE_SQLITE`          | Set to `1` to disable local SQLite (`state.db`); cloud commands that need local state will fail.                                                                                                                                                 |
+| `MNEMOSPARK_SQLITE_STRICT`           | Set to `1` so certain SQLite consistency checks (e.g. friendly-name verification after upload) throw instead of warning.                                                                                                                         |
+| `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_AGENT_ID`                | OpenClaw agent id for interactive wallet/cloud CLI via the dedicated-agent runbook (default `mnemospark`). Distinct from `MNEMOSPARK_CRON_AGENT_ID`.                                                                                             |
+| `MNEMOSPARK_CRON_NODE_BIN`           | Absolute path to `node` for dedicated-agent exec allowlists and renewal cron payloads (default `/usr/bin/node`).                                                                                                                                 |
+| `MNEMOSPARK_DISABLE_OPENCLAW_PREREQ` | Set to `1` to skip automatic runbook application everywhere it runs (plugin load, CLI install/update; for advanced debugging only).                                                                                                              |
 
 ---
 
@@ -177,7 +180,12 @@ Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 
 ## mnemospark Exec Approvals Runbook
 
-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.
+On **OpenClaw 2026.4.x**, mnemospark applies **two** dedicated-agent runbooks when you install or update (including `npx mnemospark install`, `npx mnemospark update`, `openclaw plugins install`, and when the gateway loads the plugin):
+
+1. **`mnemospark-renewal`** (default; override `MNEMOSPARK_CRON_AGENT_ID`) — monthly storage renewal cron: `tools.deny: ["subagents"]`, `tools.exec.ask: "off"`, and `/usr/bin/node` allowlisted for that agent in `~/.openclaw/exec-approvals.json`.
+2. **`mnemospark`** (default; override `MNEMOSPARK_AGENT_ID`) — interactive wallet and cloud CLI work: same tool policy and its **own** `/usr/bin/node` allowlist entry under that agent id.
+
+The plugin merges both into `agents.list` via `openclaw config set` + `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) against the renewal agent id. For interactive automation, route through the general agent (see bundled skill `skills/mnemospark/references/openclaw-routing.md`). Override the node path with `MNEMOSPARK_CRON_NODE_BIN` if your system differs.
 
 ---
 
@@ -187,7 +195,8 @@ On **OpenClaw 2026.4.x**, the **Mnemospark Renewal Agent Runbook** is applied wh
 - **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.
+- **Renewal cron / exec failures after upload**: ensure mnemospark was installed or updated through the normal path so both dedicated-agent runbooks ran (gateway load, `npx mnemospark install`, or `openclaw plugins install`). If the gateway never loaded the plugin, run install again or restart the gateway.
+- **Interactive Mnemospark exec denied on main**: use a dedicated `mnemospark` agent and route with `openclaw agent --agent mnemospark …` (see skill reference `openclaw-routing.md`); renewal-only setup does not cover general plugin usage.
 - **One-step operation correlation**: run `./skills/mnemospark/scripts/debug-operation.sh <operation-id>` (or omit ID to use latest).
 
 ---

package/dist/cli.js

@@ -146,6 +146,7 @@ var BalanceMonitor = class {
 
 // src/config.ts
 var DEFAULT_PORT = 7120;
+var DEFAULT_BACKEND_API_BASE_URL = "https://api.mnemospark.ai";
 var PROXY_PORT = (() => {
   const envPort = process.env.MNEMOSPARK_PROXY_PORT;
   if (envPort) {
@@ -156,7 +157,7 @@ var PROXY_PORT = (() => {
   }
   return DEFAULT_PORT;
 })();
-var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL ?? "").trim();
+var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL || DEFAULT_BACKEND_API_BASE_URL).trim();
 var MNEMOSPARK_PROXY_VERBOSE_404 = (() => {
   const v = process.env.MNEMOSPARK_PROXY_VERBOSE_404?.trim().toLowerCase();
   return v === "1" || v === "true" || v === "yes";
@@ -4351,16 +4352,21 @@ import { homedir as homedir6 } from "os";
 import { dirname as dirname5, join as join9 } from "path";
 import { randomUUID as randomUUID3 } from "crypto";
 var DEFAULT_RENEWAL_AGENT_ID = "mnemospark-renewal";
+var DEFAULT_MNEMOSPARK_AGENT_ID = "mnemospark";
 var RENEWAL_NODE_ALLOWLIST_ID = "node-usr-bin-node";
 function getRenewalAgentId() {
   const fromEnv = process.env.MNEMOSPARK_CRON_AGENT_ID?.trim();
   return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_RENEWAL_AGENT_ID;
 }
+function getMnemosparkAgentId() {
+  const fromEnv = process.env.MNEMOSPARK_AGENT_ID?.trim();
+  return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_MNEMOSPARK_AGENT_ID;
+}
 function getRenewalNodeBinary() {
   const fromEnv = process.env.MNEMOSPARK_CRON_NODE_BIN?.trim();
   return fromEnv && fromEnv.length > 0 ? fromEnv : "/usr/bin/node";
 }
-function runbookRenewalAgentEntry(agentId = getRenewalAgentId()) {
+function runbookDedicatedAgentEntry(agentId) {
   return {
     id: agentId,
     tools: {
@@ -4369,10 +4375,13 @@ function runbookRenewalAgentEntry(agentId = getRenewalAgentId()) {
     }
   };
 }
+function runbookRenewalAgentEntry(agentId = getRenewalAgentId()) {
+  return runbookDedicatedAgentEntry(agentId);
+}
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function renewalAgentEntrySatisfied(existing, desired) {
+function dedicatedAgentEntrySatisfied(existing, desired) {
   if (!isRecord(existing)) {
     return false;
   }
@@ -4399,7 +4408,7 @@ function mergeRenewalAgentIntoAgentsList(list, desired) {
   if (idx === -1) {
     return { list: [...arr, desired], changed: true };
   }
-  if (renewalAgentEntrySatisfied(arr[idx], desired)) {
+  if (dedicatedAgentEntrySatisfied(arr[idx], desired)) {
     return { list: arr, changed: false };
   }
   const next = [...arr];
@@ -4444,8 +4453,10 @@ async function ensureOpenClawRenewalPrerequisites(options = {}) {
     return;
   }
   const homeDir = options.homeDir ?? homedir6();
-  const agentId = getRenewalAgentId();
-  const desired = runbookRenewalAgentEntry(agentId);
+  const renewalId = getRenewalAgentId();
+  const pluginAgentId = getMnemosparkAgentId();
+  const desiredRenewal = runbookRenewalAgentEntry(renewalId);
+  const desiredPlugin = runbookDedicatedAgentEntry(pluginAgentId);
   const nodeBinary = getRenewalNodeBinary();
   const configPath = await resolveOpenClawConfigFilePath(homeDir);
   let configRaw = "{}";
@@ -4461,14 +4472,18 @@ 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 applying renewal prerequisites.`
+      `openclaw.json at ${configPath} is not valid JSON; fix or remove it before applying mnemospark OpenClaw prerequisites.`
     );
   }
   const agents = isRecord(parsed.agents) ? parsed.agents : {};
-  const { list: mergedList, changed: agentChanged } = mergeRenewalAgentIntoAgentsList(
-    agents.list,
-    desired
-  );
+  let mergedList = [];
+  let agentChanged = false;
+  const afterRenewal = mergeRenewalAgentIntoAgentsList(agents.list, desiredRenewal);
+  mergedList = afterRenewal.list;
+  agentChanged = afterRenewal.changed;
+  const afterPlugin = mergeRenewalAgentIntoAgentsList(mergedList, desiredPlugin);
+  mergedList = afterPlugin.list;
+  agentChanged = agentChanged || afterPlugin.changed;
   if (agentChanged) {
     const listJson = JSON.stringify(mergedList);
     await runOpenClawCli(["config", "set", "agents.list", listJson, "--strict-json"], homeDir);
@@ -4484,11 +4499,13 @@ async function ensureOpenClawRenewalPrerequisites(options = {}) {
       throw err;
     }
   }
-  const { doc: mergedExec, changed: execChanged } = mergeExecApprovalsAllowlist(
-    execDoc,
-    agentId,
-    nodeBinary
-  );
+  let mergedExec = execDoc;
+  let execChanged = false;
+  for (const id of [renewalId, pluginAgentId]) {
+    const { doc, changed } = mergeExecApprovalsAllowlist(mergedExec, id, nodeBinary);
+    mergedExec = doc;
+    execChanged = execChanged || changed;
+  }
   if (execChanged) {
     await writeFileAtomic(execPath, `${JSON.stringify(mergedExec, null, 2)}
 `);
@@ -8035,7 +8052,7 @@ async function promptOrRunOpenClawPluginInstall() {
         await ensureOpenClawRenewalPrerequisites();
       } catch (err) {
         console.warn(
-          "[mnemospark] Renewal prerequisites:",
+          "[mnemospark] OpenClaw prerequisites:",
           err instanceof Error ? err.message : String(err)
         );
       }
@@ -8142,7 +8159,7 @@ async function runUpdate() {
         await ensureOpenClawRenewalPrerequisites();
       } catch (err) {
         console.warn(
-          "[mnemospark] Renewal prerequisites:",
+          "[mnemospark] OpenClaw prerequisites:",
           err instanceof Error ? err.message : String(err)
         );
       }