@xpr-agents/openclaw 0.3.2 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @xpr-agents/openclaw
 
-OpenClaw plugin for the XPR Network Trustless Agent Registry — 72 MCP tools for AI assistants to autonomously manage agents, jobs, feedback, validations, and escrow on-chain.
+OpenClaw plugin for the XPR Network Trustless Agent Registry — **72 MCP tools + 13 bundled skills** for AI assistants to autonomously manage agents, jobs, feedback, validations, and escrow on-chain.
 
 ## XPR Agents Ecosystem
 
@@ -8,19 +8,45 @@ OpenClaw plugin for the XPR Network Trustless Agent Registry — 72 MCP tools fo
 |---------|-------------|
 | [`create-xpr-agent`](https://www.npmjs.com/package/create-xpr-agent) | Deploy an autonomous AI agent in one command |
 | [`@xpr-agents/sdk`](https://www.npmjs.com/package/@xpr-agents/sdk) | TypeScript SDK for all four contracts |
-| [`@xpr-agents/openclaw`](https://www.npmjs.com/package/@xpr-agents/openclaw) | 72 MCP tools for AI assistants |
+| [`@xpr-agents/openclaw`](https://www.npmjs.com/package/@xpr-agents/openclaw) | 72 MCP tools + 13 skills for AI assistants |
 
 ## Quick Start
 
-Deploy your own agent:
+Deploy your own self-contained autonomous agent on a host you own:
 
 ```bash
 npx create-xpr-agent my-agent
 cd my-agent
-./setup.sh
+./start.sh --account myagent --api-key sk-ant-yourkey --network mainnet
 ```
 
-## Tools (55 total)
+Or install just the plugin inside an existing OpenClaw harness (Pinata, gateway-hosted, etc.) — see [`docs/PINATA.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/PINATA.md):
+
+```bash
+npm install @xpr-agents/openclaw
+```
+
+## Bundled Skills (13 total — since v0.4.0)
+
+The plugin ships pre-built skills in its tarball; the `openclaw.plugin.json` manifest lists them so harnesses auto-load them once registered.
+
+| Skill | Purpose |
+|-------|---------|
+| `xpr-agent-operator` | System prompt for autonomous job-board behavior |
+| `creative` | Image / video generation, IPFS upload, PDF, GitHub repos |
+| `web-scraping` | Page fetch / parse, structured data extraction |
+| `code-sandbox` | Sandboxed JS execution in VM |
+| `structured-data` | CSV / JSON parsing, chart generation |
+| `defi` | DEX trading, AMM swaps, OTC, yield farming, liquidity, msig |
+| `nft` | AtomicAssets / AtomicMarket NFT lifecycle |
+| `lending` | LOAN Protocol — supply, borrow, repay, redeem, rewards |
+| `governance` | XPR Network governance — proposals, voting, communities |
+| `xmd` | Metal Dollar stablecoin — mint, redeem, analytics |
+| `smart-contracts` | Chain inspection, contract scaffolding, auditing |
+| `tax` | Crypto tax reporting |
+| `shellbook` | Shellbook.io social network |
+
+## Tools (72 total)
 
 ### Agent Management (10 tools)
 `xpr_register_agent`, `xpr_update_agent`, `xpr_get_agent`, `xpr_list_agents`, `xpr_get_trust_score`, `xpr_set_agent_status`, `xpr_stake_agent`, `xpr_add_plugin`, `xpr_remove_plugin`, `xpr_list_agent_plugins`

package/openclaw.plugin.json

@@ -42,5 +42,19 @@
     "indexerUrl": { "label": "Indexer URL" },
     "confirmHighRisk": { "label": "Confirm High-Risk Actions" }
   },
-  "skills": ["skills/xpr-agent-operator"]
+  "skills": [
+    "skills/xpr-agent-operator",
+    "skills/creative",
+    "skills/web-scraping",
+    "skills/code-sandbox",
+    "skills/structured-data",
+    "skills/defi",
+    "skills/nft",
+    "skills/tax",
+    "skills/lending",
+    "skills/governance",
+    "skills/xmd",
+    "skills/smart-contracts",
+    "skills/shellbook"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpr-agents/openclaw",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "OpenClaw plugin for XPR Network Trustless Agent Registry - autonomous agent operation, escrow jobs, feedback, and validation",
   "author": "XPR Network",
   "repository": {
@@ -33,8 +33,10 @@
     ]
   },
   "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
+    "build": "npm run build:plugin && npm run build:skills",
+    "build:plugin": "tsc",
+    "build:skills": "node scripts/build-skills.mjs",
+    "clean": "rm -rf dist skills/*/dist",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -42,7 +44,8 @@
   },
   "dependencies": {
     "@xpr-agents/sdk": "^0.2.0",
-    "@proton/js": "^28.1.2"
+    "@proton/js": "^28.1.2",
+    "@shellbook/sdk": "^0.2.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/skills/code-sandbox/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: code-sandbox
+description: Execute JavaScript code in a sandboxed VM for data processing and computation
+---
+
+## Code Sandbox
+
+You have sandboxed JavaScript execution tools for computation and data processing:
+
+**Full scripts:**
+- `execute_js` — run JavaScript code in an isolated V8 sandbox
+  - Pass data via the `input` parameter (JSON) — access it as `INPUT` in your code
+  - Use `console.log()` to capture intermediate values (returned in `logs` array)
+  - Available globals: `JSON`, `Math`, `Date`, `Array`, `Object`, `String`, `Number`, `RegExp`, `Map`, `Set`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `atob`, `btoa`
+  - No network access, no filesystem, no imports — pure computation only
+  - Default timeout 5 seconds, max 30 seconds
+  - 10MB output limit
+
+**Quick expressions:**
+- `eval_expression` — evaluate a single JavaScript expression and return the result
+  - Use for quick math: `"15 * 4500 * 0.01"` → `675`
+  - Date calculations: `"new Date().toISOString()"`
+  - Array operations: `"[1,2,3].map(x => x*x)"` → `[1, 4, 9]`
+
+**Best practices:**
+- Use `execute_js` for multi-step data processing, algorithm testing, code validation
+- Use `eval_expression` for quick math, string ops, date calculations
+- Pass large datasets via `input` parameter rather than embedding in code
+- Combine with `parse_csv` (structured-data skill) for CSV → transform → output workflows
+- Combine with `store_deliverable` to save computed results as job evidence

package/skills/code-sandbox/skill.json

@@ -0,0 +1,13 @@
+{
+  "name": "code-sandbox",
+  "version": "1.0.0",
+  "description": "Execute JavaScript code in a sandboxed V8 context using Node.js vm module",
+  "author": "xpr-agents",
+  "category": "compute",
+  "tags": ["code", "javascript", "sandbox", "vm", "compute"],
+  "capabilities": ["code-execution", "computation"],
+  "tools": ["execute_js", "eval_expression"],
+  "requires": {
+    "env": []
+  }
+}

package/skills/code-sandbox/src/index.ts

@@ -0,0 +1,212 @@
+/**
+ * Code Sandbox Skill — execute JavaScript in a sandboxed V8 context
+ *
+ * Zero external dependencies — uses Node.js built-in `vm` module.
+ */
+
+import vm from 'vm';
+
+interface ToolDef {
+  name: string;
+  description: string;
+  parameters: { type: 'object'; required?: string[]; properties: Record<string, unknown> };
+  handler: (params: any) => Promise<unknown>;
+}
+
+interface SkillApi {
+  registerTool(tool: ToolDef): void;
+  getConfig(): Record<string, unknown>;
+}
+
+// ── Constants ───────────────────────────────────
+
+const DEFAULT_TIMEOUT = 5000;
+const MAX_TIMEOUT = 30000;
+const MAX_OUTPUT_SIZE = 10 * 1024 * 1024; // 10MB
+
+// ── Sandbox helpers ─────────────────────────────
+
+function createSandboxGlobals(input: unknown, logs: string[]): Record<string, unknown> {
+  // Capture console methods
+  const consoleMock = {
+    log: (...args: unknown[]) => {
+      logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
+    },
+    warn: (...args: unknown[]) => {
+      logs.push('[warn] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
+    },
+    error: (...args: unknown[]) => {
+      logs.push('[error] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '));
+    },
+  };
+
+  return {
+    INPUT: input,
+    console: consoleMock,
+    JSON,
+    Math,
+    Date,
+    Array,
+    Object,
+    String,
+    Number,
+    RegExp,
+    Map,
+    Set,
+    parseInt,
+    parseFloat,
+    isNaN,
+    isFinite,
+    encodeURIComponent,
+    decodeURIComponent,
+    atob: (s: string) => Buffer.from(s, 'base64').toString('binary'),
+    btoa: (s: string) => Buffer.from(s, 'binary').toString('base64'),
+    // Explicitly undefined — blocked
+    require: undefined,
+    process: undefined,
+    globalThis: undefined,
+    global: undefined,
+  };
+}
+
+function serializeResult(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  try {
+    const str = JSON.stringify(value, null, 2);
+    if (str.length > MAX_OUTPUT_SIZE) {
+      return str.slice(0, MAX_OUTPUT_SIZE) + '\n... [truncated at 10MB]';
+    }
+    return str;
+  } catch {
+    return String(value);
+  }
+}
+
+// ── Skill entry point ───────────────────────────
+
+export default function codeSandboxSkill(api: SkillApi): void {
+  // ── execute_js ──
+  api.registerTool({
+    name: 'execute_js',
+    description: [
+      'Run JavaScript code in a sandboxed V8 context.',
+      'Pass data via "input" (JSON), access it as INPUT in code.',
+      'console.log/warn/error are captured in the "logs" array.',
+      'Available: JSON, Math, Date, Array, Object, String, Number, RegExp, Map, Set,',
+      'parseInt, parseFloat, isNaN, isFinite, encodeURIComponent, decodeURIComponent, atob, btoa.',
+      'No network, filesystem, require, or import access. Max 30s timeout, 10MB output.',
+    ].join(' '),
+    parameters: {
+      type: 'object',
+      required: ['code'],
+      properties: {
+        code: { type: 'string', description: 'JavaScript code to execute. The last expression value is returned as the result.' },
+        input: { description: 'Optional JSON data available as INPUT in the code.' },
+        timeout: { type: 'number', description: 'Execution timeout in milliseconds (default 5000, max 30000).' },
+      },
+    },
+    handler: async ({ code, input, timeout }: {
+      code: string; input?: unknown; timeout?: number;
+    }) => {
+      if (!code || typeof code !== 'string') {
+        return { error: 'code parameter is required and must be a string' };
+      }
+
+      const timeoutMs = Math.min(Math.max(timeout || DEFAULT_TIMEOUT, 100), MAX_TIMEOUT);
+      const logs: string[] = [];
+      const startTime = Date.now();
+
+      try {
+        const globals = createSandboxGlobals(input, logs);
+        const context = vm.createContext(globals, {
+          codeGeneration: { strings: false, wasm: false },
+        });
+
+        // Wrap code so the last expression is returned
+        const wrapped = `(function() {\n${code}\n})()`;
+        const script = new vm.Script(wrapped, { filename: 'sandbox.js' });
+        const result = script.runInContext(context, { timeout: timeoutMs });
+        const durationMs = Date.now() - startTime;
+
+        const serialized = serializeResult(result);
+        if (serialized.length > MAX_OUTPUT_SIZE) {
+          return {
+            result: serialized.slice(0, 1000) + '... [truncated]',
+            logs,
+            duration_ms: durationMs,
+            warning: 'Output exceeded 10MB limit and was truncated',
+          };
+        }
+
+        // Parse back to preserve types (arrays, objects)
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(serialized);
+        } catch {
+          parsed = serialized === 'undefined' ? undefined : serialized;
+        }
+
+        return { result: parsed, logs, duration_ms: durationMs };
+      } catch (err: any) {
+        const durationMs = Date.now() - startTime;
+        const message = err.message || String(err);
+
+        // Provide helpful error context
+        if (message.includes('Script execution timed out')) {
+          return { error: `Execution timed out after ${timeoutMs}ms. Keep code efficient or increase timeout (max ${MAX_TIMEOUT}ms).`, logs, duration_ms: durationMs };
+        }
+        if (message.includes('Code generation from strings disallowed')) {
+          return { error: 'eval() and Function() constructor are blocked in the sandbox. Use direct code instead.', logs, duration_ms: durationMs };
+        }
+
+        return { error: message, logs, duration_ms: durationMs };
+      }
+    },
+  });
+
+  // ── eval_expression ──
+  api.registerTool({
+    name: 'eval_expression',
+    description: [
+      'Evaluate a single JavaScript expression and return the result.',
+      'Lightweight alternative to execute_js for quick calculations.',
+      'Examples: "15 * 4500 * 0.01", "new Date().toISOString()", "[1,2,3].map(x => x*x)".',
+    ].join(' '),
+    parameters: {
+      type: 'object',
+      required: ['expression'],
+      properties: {
+        expression: { type: 'string', description: 'A JavaScript expression to evaluate.' },
+      },
+    },
+    handler: async ({ expression }: { expression: string }) => {
+      if (!expression || typeof expression !== 'string') {
+        return { error: 'expression parameter is required and must be a string' };
+      }
+
+      try {
+        const globals = createSandboxGlobals(undefined, []);
+        const context = vm.createContext(globals, {
+          codeGeneration: { strings: false, wasm: false },
+        });
+
+        const script = new vm.Script(`(${expression})`, { filename: 'expr.js' });
+        const result = script.runInContext(context, { timeout: DEFAULT_TIMEOUT });
+
+        let serialized: unknown;
+        try {
+          serialized = JSON.parse(JSON.stringify(result));
+        } catch {
+          serialized = String(result);
+        }
+
+        return {
+          result: serialized,
+          type: result === null ? 'null' : Array.isArray(result) ? 'array' : typeof result,
+        };
+      } catch (err: any) {
+        return { error: err.message || String(err) };
+      }
+    },
+  });
+}

package/skills/creative/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: creative
+description: Creative deliverable tools for AI agents
+---
+## Creative Deliverables
+
+You have powerful creative capabilities for delivering job results:
+
+**Text & Documents:**
+- `store_deliverable` with content_type "text/markdown" — rich Markdown (default)
+- `store_deliverable` with content_type "application/pdf" — write Markdown, auto-generates PDF
+  - Use ![alt text](https://image-url) to embed images — they are downloaded and embedded in the PDF
+  - Write CLEAN Markdown only — no HTML tags, no <cite> tags, no raw HTML
+- `store_deliverable` with content_type "text/csv" — structured data
+
+**Images (AI-generated) — IMPORTANT:**
+- Call `generate_image` with prompt AND job_id — it generates, uploads to IPFS, and returns evidence_uri in ONE step
+- Then just call `xpr_deliver_job` with the evidence_uri
+- Do NOT write markdown descriptions of images — generate the actual image!
+
+**Video (AI-generated):**
+- Call `generate_video` with prompt AND job_id — generates, uploads to IPFS, returns evidence_uri
+- Then call `xpr_deliver_job` with the evidence_uri
+
+**Images/Media from the web:**
+- Use `web_search` to find suitable content, then `store_deliverable` with source_url
+
+**Code repositories:**
+- `create_github_repo` with all source files — creates a public GitHub repo
+
+NEVER say you can't create images or videos — you have the tools!
+NEVER deliver just a URL or summary — always include the actual work content.

package/skills/creative/skill.json

@@ -0,0 +1,13 @@
+{
+  "name": "creative",
+  "version": "1.0.0",
+  "description": "AI image/video generation, PDF creation, GitHub repo delivery, and IPFS storage for job deliverables",
+  "author": "xpr-agents",
+  "category": "ai",
+  "tags": ["image", "video", "pdf", "github", "ipfs", "deliverables"],
+  "capabilities": ["image-generation", "video-generation", "pdf-generation", "github-repos", "ipfs-storage"],
+  "tools": ["store_deliverable", "create_github_repo", "generate_image", "generate_video"],
+  "requires": {
+    "env": []
+  }
+}