mnemospark 0.1.22 → 0.2.0

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "mnemospark",
   "name": "mnemospark",
-  "version": "0.1.22",
+  "version": "0.2.0",
   "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.22",
+  "version": "0.2.0",
   "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",

package/skills/mnemospark/SKILL.md

@@ -9,26 +9,44 @@ Use this skill for mnemospark cloud backup/storage workflows, async operation tr
 - 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`)
+- Optional async orchestration context for long-running work:
+  - `--async`
+  - `--orchestrator <inline|subagent>` (default async mode: `inline`)
+  - `--timeout-seconds <n>` (valid only with `--async --orchestrator subagent`)
 
 ## 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.
+2. For long-running `backup`/`upload`/`download`, prefer `--async`.
+3. Use `--orchestrator subagent` when explicit subagent session tracking/cancel support is required.
+4. If timeout control is needed, require `--timeout-seconds <n>` with `--orchestrator subagent`.
+5. Return `operation-id` immediately for async commands.
+6. Poll with `/mnemospark_cloud op-status --operation-id <id>` until terminal status.
+7. Use `/mnemospark_cloud op-status --operation-id <id> --cancel` for subagent cancellation.
+8. Use SQLite (`state.db`) as source of truth; use JSONL streams for correlation and audit context.
+9. On ambiguity with `--name`, require `--latest` or `--at`.
+10. 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>`
+- `/mnemospark_cloud backup <file|directory> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+- `/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] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+- `/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] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+- `/mnemospark_cloud delete --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>]`
+- `/mnemospark_cloud op-status --operation-id <id> [--cancel]`
+
+## Async quick examples
+
+- Start async with subagent orchestration:
+  - `/mnemospark_cloud upload ... --async --orchestrator subagent`
+- Start async with timeout:
+  - `/mnemospark_cloud download ... --async --orchestrator subagent --timeout-seconds 900`
+- Check status:
+  - `/mnemospark_cloud op-status --operation-id <id>`
+- Cancel subagent operation:
+  - `/mnemospark_cloud op-status --operation-id <id> --cancel`
 
 ## References
 

package/skills/mnemospark/references/commands.md

@@ -1,10 +1,13 @@
 # mnemospark Commands Reference
 
-## `/mnemospark-cloud`
+## `/mnemospark_cloud`
 
 ### Backup
 
-`backup <file|directory> [--name <friendly-name>]`
+`backup <file|directory> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+
+- Purpose: create a local tar+gzip backup artifact and index metadata.
+- `--timeout-seconds <n>` only applies when `--async --orchestrator subagent`.
 
 ### Price storage quote
 
@@ -12,7 +15,10 @@
 
 ### Upload
 
-`upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async]`
+`upload --quote-id <quote-id> --wallet-address <addr> --object-id <id> --object-id-hash <hash> [--name <friendly-name>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+
+- Purpose: upload encrypted object for a valid quote.
+- `--timeout-seconds <n>` only applies when `--async --orchestrator subagent`.
 
 ### List
 
@@ -20,7 +26,10 @@
 
 ### Download
 
-`download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async]`
+`download --wallet-address <addr> [--object-key <object-key> | --name <friendly-name>] [--latest|--at <timestamp>] [--async] [--orchestrator <inline|subagent>] [--timeout-seconds <n>]`
+
+- Purpose: download object content to local filesystem.
+- `--timeout-seconds <n>` only applies when `--async --orchestrator subagent`.
 
 ### Delete
 
@@ -28,7 +37,31 @@
 
 ### Operation status
 
-`op-status --operation-id <id>`
+`op-status --operation-id <id> [--cancel]`
+
+- `--cancel` requests cancellation for subagent-orchestrated operations.
+- Cancellation is idempotent and safe to call repeatedly.
+
+## Async orchestration flags (long-running commands only)
+
+Applies to `backup`, `upload`, `download`.
+
+- `--async`
+  - Run in background and return immediately with `operation-id`.
+- `--orchestrator <inline|subagent>`
+  - Select async execution mode.
+  - Current default when omitted with `--async`: `inline`.
+  - Use `subagent` for explicit subagent session metadata and cancel controls.
+- `--timeout-seconds <n>`
+  - Positive integer timeout in seconds.
+  - Valid only with `--async --orchestrator subagent`.
+
+## Async examples
+
+- `/mnemospark_cloud upload ... --async --orchestrator subagent`
+- `/mnemospark_cloud download ... --async --orchestrator subagent --timeout-seconds 900`
+- `/mnemospark_cloud op-status --operation-id <id>`
+- `/mnemospark_cloud op-status --operation-id <id> --cancel`
 
 ## Name selector rules
 

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

@@ -33,6 +33,46 @@ Cross-stream troubleshooting should correlate by:
 - `object_id`
 - `object_key`
 
+## Operation lifecycle status values
+
+`operations.status` values used by async orchestration:
+
+- `started`
+- `running`
+- `succeeded`
+- `failed`
+- `cancelled`
+- `timed_out`
+
+Common async terminal error codes:
+
+- `ASYNC_FAILED`
+- `ASYNC_EXCEPTION`
+- `ASYNC_CANCELLED`
+- `ASYNC_TIMEOUT`
+- `ASYNC_DISPATCH_FAILED`
+
+## Orchestration metadata in operations
+
+For async runs, `operations` may include:
+
+- `trace_id`
+- `orchestrator` (`inline` or `subagent`)
+- `subagent_session_id`
+- `timeout_seconds`
+- `cancel_requested_at`
+
+## Operation lifecycle JSONL events
+
+Operation lifecycle events emitted to `events.jsonl` and `proxy-events.jsonl`:
+
+- `operation.dispatched`
+- `operation.progress`
+- `operation.cancel.requested`
+- `operation.cancelled`
+- `operation.timed_out`
+- `operation.completed`
+
 ## Quick correlation command
 
 ```bash

package/skills/mnemospark/references/troubleshooting.md

@@ -2,10 +2,13 @@
 
 ## 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`.
+1. Start with `--async` for backup/upload/download.
+2. If explicit session lifecycle control is needed, add `--orchestrator subagent`.
+3. If timeout control is needed, add `--timeout-seconds <n>` with `--orchestrator subagent`.
+4. Capture `operation-id`.
+5. Query: `/mnemospark_cloud op-status --operation-id <id>`.
+6. If needed, request cancel: `/mnemospark_cloud op-status --operation-id <id> --cancel`.
+7. Correlate with `events.jsonl` and `proxy-events.jsonl`.
 
 ## One-step correlation debugger
 
@@ -25,6 +28,15 @@ If you omit `<operation-id>`, the latest operation from SQLite is used:
 
 - `Operation not found: <id>`
   - Check SQLite health or `MNEMOSPARK_DISABLE_SQLITE`.
+- `Cannot build storage object: invalid async flags`
+  - `--orchestrator`/`--timeout-seconds` require `--async`.
+  - `--timeout-seconds` requires `--orchestrator subagent`.
+- `error-code: ASYNC_DISPATCH_FAILED`
+  - Subagent dispatch could not start; inspect recent operation events.
+- `error-code: ASYNC_TIMEOUT`
+  - Operation exceeded timeout; increase `--timeout-seconds` or retry without timeout.
+- `error-code: ASYNC_CANCELLED`
+  - Operation was cancelled through `op-status --cancel`.
 - Name ambiguity for `--name`
   - Re-run with `--latest` or `--at <timestamp>`.
 - Repeated settle/upload mismatch