mnemospark 0.1.21 → 0.1.22

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "mnemospark",
   "name": "mnemospark",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "mnemospark is an OpenClaw plugin that gives agentic systems instant, secure access to cloud storage, compute, and proprietary datasets paid via x402 with USDC on Base. Wallet and go.",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnemospark",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "mnemospark is an OpenClaw plugin that gives agentic systems instant, secure access to cloud storage, compute, and proprietary datasets paid via x402 with USDC on Base. Wallet and go.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "scripts",
     "openclaw.plugin.json"
   ],

package/skills/mnemospark/SKILL.md

@@ -0,0 +1,38 @@
+# mnemospark
+
+## When to use
+
+Use this skill for mnemospark cloud backup/storage workflows, async operation tracking, and troubleshooting using SQLite + JSONL observability.
+
+## Inputs expected
+
+- User intent: backup, price-storage, upload, ls, download, delete, op-status
+- Wallet context (`--wallet-address`) where required
+- Optional selector context (`--object-key` or `--name`, plus `--latest` / `--at`)
+
+## Execution rules
+
+1. Validate required args before execution.
+2. Prefer `--async` for long-running `upload` and `download`.
+3. Return `operation-id` immediately for async commands.
+4. Poll with `/mnemospark-cloud op-status --operation-id <id>` until terminal status.
+5. Use SQLite (`state.db`) as source of truth; use JSONL streams for correlation and audit context.
+6. On ambiguity with `--name`, require `--latest` or `--at`.
+7. On SQLite unavailability, report graceful fallback and continue with JSONL + legacy logs.
+
+## Command catalog
+
+- `/mnemospark-cloud backup <file|directory> [--name <friendly-name>]`
+- `/mnemospark-cloud price-storage --wallet-address <addr> --object-id <id> --object-id-hash <hash> --gb <gb> --provider <provider> --region <region>`
+- `/mnemospark-cloud upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async]`
+- `/mnemospark-cloud ls --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`
+- `/mnemospark-cloud download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async]`
+- `/mnemospark-cloud delete --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`
+- `/mnemospark-cloud op-status --operation-id <id>`
+
+## References
+
+- `references/commands.md`
+- `references/state-and-logs.md`
+- `references/troubleshooting.md`
+- `scripts/debug-operation.sh` (one-step operation correlation debugger)

package/skills/mnemospark/references/commands.md

@@ -0,0 +1,42 @@
+# mnemospark Commands Reference
+
+## `/mnemospark-cloud`
+
+### Backup
+
+`backup <file|directory> [--name <friendly-name>]`
+
+### Price storage quote
+
+`price-storage --wallet-address <addr> --object-id <id> --object-id-hash <hash> --gb <gb> --provider <provider> --region <region>`
+
+### Upload
+
+`upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async]`
+
+### List
+
+`ls --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`
+
+### Download
+
+`download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async]`
+
+### Delete
+
+`delete --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`
+
+### Operation status
+
+`op-status --operation-id <id>`
+
+## Name selector rules
+
+- `--object-key` and `--name` are mutually exclusive.
+- If `--name` maps to multiple active objects, require `--latest` or `--at`.
+
+## One-step debug helper
+
+```bash
+./skills/mnemospark/scripts/debug-operation.sh <operation-id>
+```

package/skills/mnemospark/references/state-and-logs.md

@@ -0,0 +1,40 @@
+# mnemospark State and Logs Reference
+
+## Primary state
+
+- SQLite: `~/.openclaw/mnemospark/state.db`
+
+### Key tables
+
+- `objects`
+- `payments`
+- `cron_jobs`
+- `operations`
+- `friendly_names`
+
+## Observability streams
+
+- Client events: `~/.openclaw/mnemospark/events.jsonl`
+- Friendly-name manifest: `~/.openclaw/mnemospark/manifest.jsonl`
+- Proxy events: `~/.openclaw/mnemospark/proxy-events.jsonl`
+
+## Legacy compatibility paths
+
+- `~/.openclaw/mnemospark/object.log`
+- `~/.openclaw/mnemospark/crontab.txt`
+
+## Correlation fields
+
+Cross-stream troubleshooting should correlate by:
+
+- `operation_id`
+- `trace_id`
+- `quote_id`
+- `object_id`
+- `object_key`
+
+## Quick correlation command
+
+```bash
+./skills/mnemospark/scripts/debug-operation.sh <operation-id>
+```

package/skills/mnemospark/references/troubleshooting.md

@@ -0,0 +1,36 @@
+# mnemospark Troubleshooting Reference
+
+## Async workflow checks
+
+1. Start with `--async` for upload/download.
+2. Capture `operation-id`.
+3. Query: `/mnemospark-cloud op-status --operation-id <id>`.
+4. Correlate with `events.jsonl` and `proxy-events.jsonl`.
+
+## One-step correlation debugger
+
+From repo root:
+
+```bash
+./skills/mnemospark/scripts/debug-operation.sh <operation-id>
+```
+
+If you omit `<operation-id>`, the latest operation from SQLite is used:
+
+```bash
+./skills/mnemospark/scripts/debug-operation.sh
+```
+
+## Frequent failure patterns
+
+- `Operation not found: <id>`
+  - Check SQLite health or `MNEMOSPARK_DISABLE_SQLITE`.
+- Name ambiguity for `--name`
+  - Re-run with `--latest` or `--at <timestamp>`.
+- Repeated settle/upload mismatch
+  - Inspect `proxy-events.jsonl` `payment.settle` and `storage.call` events for matching `operation_id`.
+
+## Operator fallback
+
+- Use direct `--object-key` if friendly-name resolution is uncertain.
+- Re-run sync (without `--async`) for one-shot detailed failure output.

package/skills/mnemospark/scripts/debug-operation.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+One-step mnemospark operation debugger
+
+Usage:
+  debug-operation.sh [operation-id] [--home <home-dir>] [--tail <lines>]
+
+Examples:
+  ./skills/mnemospark/scripts/debug-operation.sh 1f7b2f0d-....
+  ./skills/mnemospark/scripts/debug-operation.sh --tail 300
+
+Behavior:
+  - If operation-id is omitted, the latest operation in SQLite is used.
+  - Correlates operation context across:
+      state.db (operations/objects/payments)
+      events.jsonl
+      proxy-events.jsonl
+      manifest.jsonl
+USAGE
+}
+
+require_cmd() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "Missing required tool: $1" >&2
+    exit 2
+  fi
+}
+
+sql_escape() {
+  printf "%s" "$1" | sed "s/'/''/g"
+}
+
+HOME_DIR="${HOME}"
+TAIL_LINES="200"
+OPERATION_ID=""
+
+while (($#)); do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --home)
+      HOME_DIR="${2:-}"
+      shift 2
+      ;;
+    --tail)
+      TAIL_LINES="${2:-}"
+      shift 2
+      ;;
+    --*)
+      echo "Unknown flag: $1" >&2
+      usage
+      exit 1
+      ;;
+    *)
+      if [[ -z "${OPERATION_ID}" ]]; then
+        OPERATION_ID="$1"
+      else
+        echo "Unexpected extra argument: $1" >&2
+        usage
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+if ! [[ "${TAIL_LINES}" =~ ^[0-9]+$ ]]; then
+  echo "--tail must be a positive integer" >&2
+  exit 1
+fi
+
+require_cmd sqlite3
+require_cmd jq
+require_cmd tail
+
+STATE_DIR="${HOME_DIR}/.openclaw/mnemospark"
+DB_PATH="${STATE_DIR}/state.db"
+EVENTS_PATH="${STATE_DIR}/events.jsonl"
+PROXY_PATH="${STATE_DIR}/proxy-events.jsonl"
+MANIFEST_PATH="${STATE_DIR}/manifest.jsonl"
+
+if [[ ! -f "${DB_PATH}" ]]; then
+  echo "SQLite state not found: ${DB_PATH}" >&2
+  exit 1
+fi
+
+if [[ -z "${OPERATION_ID}" ]]; then
+  OPERATION_ID="$(sqlite3 "${DB_PATH}" "SELECT operation_id FROM operations ORDER BY updated_at DESC LIMIT 1;")"
+  if [[ -z "${OPERATION_ID}" ]]; then
+    echo "No operations found in ${DB_PATH}" >&2
+    exit 1
+  fi
+fi
+
+ESCAPED_OP_ID="$(sql_escape "${OPERATION_ID}")"
+OP_JSON="$(sqlite3 -json "${DB_PATH}" "SELECT operation_id,type,status,error_code,error_message,started_at,finished_at,updated_at,object_id,quote_id FROM operations WHERE operation_id='${ESCAPED_OP_ID}' LIMIT 1;")"
+
+if [[ "${OP_JSON}" == "[]" ]]; then
+  echo "Operation not found in SQLite: ${OPERATION_ID}" >&2
+  exit 1
+fi
+
+OBJECT_ID="$(printf "%s" "${OP_JSON}" | jq -r '.[0].object_id // empty')"
+QUOTE_ID="$(printf "%s" "${OP_JSON}" | jq -r '.[0].quote_id // empty')"
+
+OBJECT_JSON="[]"
+OBJECT_KEY=""
+WALLET_ADDRESS=""
+if [[ -n "${OBJECT_ID}" ]]; then
+  ESCAPED_OBJECT_ID="$(sql_escape "${OBJECT_ID}")"
+  OBJECT_JSON="$(sqlite3 -json "${DB_PATH}" "SELECT object_id,object_key,wallet_address,quote_id,status,updated_at FROM objects WHERE object_id='${ESCAPED_OBJECT_ID}' ORDER BY updated_at DESC LIMIT 1;")"
+  OBJECT_KEY="$(printf "%s" "${OBJECT_JSON}" | jq -r '.[0].object_key // empty')"
+  WALLET_ADDRESS="$(printf "%s" "${OBJECT_JSON}" | jq -r '.[0].wallet_address // empty')"
+  if [[ -z "${QUOTE_ID}" ]]; then
+    QUOTE_ID="$(printf "%s" "${OBJECT_JSON}" | jq -r '.[0].quote_id // empty')"
+  fi
+fi
+
+PAYMENT_JSON="[]"
+if [[ -n "${QUOTE_ID}" ]]; then
+  ESCAPED_QUOTE_ID="$(sql_escape "${QUOTE_ID}")"
+  PAYMENT_JSON="$(sqlite3 -json "${DB_PATH}" "SELECT quote_id,wallet_address,trans_id,amount,status,settled_at,updated_at FROM payments WHERE quote_id='${ESCAPED_QUOTE_ID}' LIMIT 1;")"
+fi
+
+echo "=== mnemospark one-step operation debug ==="
+echo "home: ${HOME_DIR}"
+echo "state: ${STATE_DIR}"
+echo "operation-id: ${OPERATION_ID}"
+echo
+
+echo "---- operations row ----"
+printf "%s\n" "${OP_JSON}" | jq .
+echo
+
+if [[ "${OBJECT_JSON}" != "[]" ]]; then
+  echo "---- related object row ----"
+  printf "%s\n" "${OBJECT_JSON}" | jq .
+  echo
+fi
+
+if [[ "${PAYMENT_JSON}" != "[]" ]]; then
+  echo "---- related payment row ----"
+  printf "%s\n" "${PAYMENT_JSON}" | jq .
+  echo
+fi
+
+print_stream_matches() {
+  local file_path="$1"
+  if [[ ! -f "${file_path}" ]]; then
+    return
+  fi
+  local file_name
+  file_name="$(basename "${file_path}")"
+  echo "---- ${file_name} matches (tail ${TAIL_LINES}) ----"
+  tail -n "${TAIL_LINES}" "${file_path}" | jq -cR \
+    --arg op "${OPERATION_ID}" \
+    --arg quote "${QUOTE_ID}" \
+    --arg object "${OBJECT_ID}" \
+    --arg key "${OBJECT_KEY}" \
+    --arg wallet "${WALLET_ADDRESS}" '
+      fromjson? as $j
+      | select($j != null)
+      | select(
+          (($j.operation_id // "") == $op)
+          or ($quote != "" and ($j.quote_id // "") == $quote)
+          or ($object != "" and ($j.object_id // "") == $object)
+          or ($key != "" and ($j.object_key // "") == $key)
+          or ($wallet != "" and ($j.wallet_address // "") == $wallet)
+        )
+      | $j
+    '
+  echo
+}
+
+print_stream_matches "${EVENTS_PATH}"
+print_stream_matches "${PROXY_PATH}"
+print_stream_matches "${MANIFEST_PATH}"
+
+echo "Done."