@xpr-agents/openclaw 0.4.1 → 0.4.3

package/README.md

@@ -27,44 +27,92 @@ cd my-agent
 
 ### Inside an OpenClaw harness
 
+The supported install path on OpenClaw runtimes (OpenClaw 2026.3.x verified, Pinata Agents verified):
+
+```bash
+# 1. Install via OpenClaw's plugin CLI (NOT `npm install` — see "Why not
+#    plain npm install" below)
+openclaw plugins install @xpr-agents/openclaw
+```
+
+This downloads the package from npm, copies it to `~/.openclaw/extensions/openclaw/`, and **auto-writes** the following to your `~/.openclaw/openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "openclaw": { "enabled": true }
+    },
+    "installs": {
+      "openclaw": {
+        "source": "npm",
+        "spec": "@xpr-agents/openclaw",
+        "version": "0.4.2",
+        "installPath": "/home/<user>/.openclaw/extensions/openclaw",
+        "integrity": "sha512-<...>",
+        "shasum": "<...>",
+        "installedAt": "<iso-timestamp>"
+      }
+    }
+  }
+}
+```
+
 ```bash
-# 1. Install
-npm install @xpr-agents/openclaw
-
-# 2. Register with the harness. The mechanism depends on the runtime:
-#    - Pinata Agents: see docs/PINATA.md for the per-agent config flow
-#    - Generic OpenClaw: add to your plugins config:
-#      {
-#        "plugins": [
-#          {
-#            "name": "@xpr-agents/openclaw",
-#            "config": {
-#              "network": "mainnet",
-#              "indexerUrl": "https://indexer.xpragents.com"
-#            }
-#          }
-#        ]
-#      }
-#
-# 3. Restart the agent. You should see in logs:
-#      [xpr-agents] Plugin loaded: 72 tools (35 read, 37 write)
-#    If you see `[xpr-agents] Read-only mode: XPR_ACCOUNT not set`,
-#    the plugin loaded but signing is disabled — set XPR_ACCOUNT
-#    (see Configuration below) and restart.
-#
-# 4. Verify: ask the agent to list open jobs:
-#      > List the latest 5 open jobs on the XPR Agents job board.
-#    Expect a real list. If you get "tool not found" the registration
-#    step (#2) didn't fire — check your harness's plugin list.
+# 2. Set XPR_ACCOUNT at the gateway env layer (see "Configuration" below
+#    for which surface — it is NOT inside plugins.entries.openclaw.config).
+
+# 3. Restart the gateway. Most OpenClaw harnesses restart automatically
+#    when openclaw.json is patched (a SIGUSR1 fires). If yours doesn't,
+#    use whichever restart command your harness supports.
+
+# 4. Verify the load by tailing the gateway log. Look for:
+#      [xpr-agents] Plugin loaded: 72 tools, mainnet (https://proton.eosusa.io)
+#    If you also see `[xpr-agents] Read-only mode: XPR_ACCOUNT not set.`,
+#    the plugin loaded but signing is disabled — re-check step 2.
+
+# 5. Run your first signed write (the plugin auto-registration in the
+#    standalone scaffold does NOT fire on the harness path):
+#      > Register <your-agent> as an agent with name '...', description
+#        '...', endpoint '...', protocol 'https', capabilities ['general',
+#        'jobs', 'bidding'].
+#    Expect `xpr_register_agent` → real `transaction_id` in the response →
+#    `[proton-cli] action agentcore::register auth=<your-agent>@active`
+#    in the gateway log.
 ```
 
-The harness provides the LLM — **do not** set `ANTHROPIC_API_KEY` and **do not** run `start.sh` on this path. Plugin path is install + register only. Full walkthrough for Pinata Agents specifically: [`docs/PINATA.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/PINATA.md).
+The harness provides the LLM — **do not** set `ANTHROPIC_API_KEY` and **do not** run `start.sh` on this path. Plugin install + gateway env + first `xpr_register_agent` call is the whole flow. Full walkthrough for Pinata Agents specifically: [`docs/PINATA.md`](https://github.com/XPRNetwork/xpr-agents/blob/main/docs/PINATA.md).
+
+#### Why not plain `npm install`?
+
+OpenClaw harnesses do **not** auto-scan workspace `node_modules` for plugins. They scan:
+- `plugins.load.paths` (explicit)
+- `~/.openclaw/extensions/<plugin>/`
+- bundled `/app/extensions/<plugin>/`
+
+So `npm install @xpr-agents/openclaw` puts the package on disk but doesn't make it discoverable. Use `openclaw plugins install` (above) or, for monorepo development, add the workspace path to `plugins.load.paths` manually.
+
+#### Why the harness path doesn't auto-register
+
+The standalone `create-xpr-agent` scaffold auto-registers the agent in `agentcore::agents` on first boot via the runner's `ensureRegistered()`. The harness path loads only the plugin — not the runner — so the account is **not** in the registry until you explicitly call `xpr_register_agent`. Until then, every `xpr_update_*` / `xpr_set_agent_status` call returns `Agent not found`. Tracked for v0.5 to optionally self-register on first signed call when `XPR_ACCOUNT` is set.
+
+## Security notes (read this if your OpenClaw install scanner flags us)
+
+OpenClaw's plugin installer statically scans every package before install and reports patterns it considers risky. As of 0.4.2 it flags **19 patterns** in `@xpr-agents/openclaw`. Every one of them is intentional and named below — do not bail on the install when you see them.
+
+| Count | Pattern | Where | Why it's intentional |
+|---|---|---|---|
+| 16× | "Environment variable access combined with network send — possible credential harvesting" | `skills/{creative,defi,governance,lending,nft,smart-contracts,tax,xmd}/{src,dist}/index.ts:<line>`, `dist/tools/a2a.js`, `dist/tools/shellbook.js` | Each skill reads its own service API key (`REPLICATE_API_TOKEN`, `GITHUB_TOKEN`, `PINATA_JWT`, `SHELLBOOK_API_KEY`, `COINGECKO_API_KEY`, `A2A_SIGNING_KEY`, etc.) and calls that service's HTTPS API. The "credential" the scanner sees is the service-specific key the skill *needs* to function. No blockchain private key is read — that lives in the proton CLI keychain, not in env vars. |
+| 1× | "Shell command execution (child_process)" | `dist/proton-cli.js:<line>` | **This is the post-charliebot security feature itself.** All on-chain signing shells out to `proton transaction:push`. The whole reason for v0.4.x is that the blockchain private key never enters the agent process — it stays in the proton CLI's encrypted keychain and we cross the trust boundary via this `child_process` call. If you'd rather hold the key in process, use a different package. |
+| 2× | "Dynamic code execution detected" | `skills/code-sandbox/{src,dist}/index.ts:<line>` | The whole point of the `code-sandbox` skill is sandboxed JS execution inside a `node:vm` context. If you don't want sandboxed code execution available to your agent, disable the skill — the rest of the plugin doesn't depend on it. |
+
+If your harness lets you set `plugins.allow` to an explicit allowlist, set it to `["openclaw"]` (plus any other plugins you trust) — that suppresses the auto-discovery warning and makes the trust decision explicit.
 
 ## 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 OpenClaw harnesses that honor the `skills` field auto-load them after the agent restarts. Verify by asking the agent `list your skills` — you should see 13.
+The plugin ships pre-built skills in its tarball; the `openclaw.plugin.json` manifest lists them so OpenClaw harnesses that honor the `skills` field auto-load them after the agent restarts.
 
-If your harness doesn't honor the manifest's `skills` field, the skill folders are still on disk at `node_modules/@xpr-agents/openclaw/skills/<name>/` and can be registered manually.
+When you install via `openclaw plugins install @xpr-agents/openclaw`, the skill folders land at `~/.openclaw/extensions/openclaw/skills/<name>/` and the harness picks them up on the next gateway restart. If your harness ignores the manifest's `skills` array, the skill folders are still on disk and can be registered through whatever per-skill mechanism your runtime exposes.
 
 | Skill | Purpose |
 |-------|---------|
@@ -155,6 +203,29 @@ XPR_ACCOUNT=myagent                       # REQUIRED — without this, the plugi
 XPR_NETWORK=mainnet                       # mainnet | testnet  (default: mainnet)
 ```
 
+> **Where to put `XPR_ACCOUNT` matters.** On OpenClaw harnesses it goes in the gateway environment layer, NOT in the plugin's config:
+>
+> ```jsonc
+> // ~/.openclaw/openclaw.json — CORRECT
+> {
+>   "env": {
+>     "vars": {
+>       "XPR_ACCOUNT": "myagent"
+>     }
+>   },
+>   "plugins": {
+>     "entries": {
+>       "openclaw": {
+>         "enabled": true,
+>         "config": { "network": "mainnet" }
+>       }
+>     }
+>   }
+> }
+> ```
+>
+> Putting `XPR_ACCOUNT` inside `plugins.entries.openclaw.config` does NOT work — the plugin reads it from `process.env`, which is populated from `env.vars`, not from per-plugin config. We verified this empirically on OpenClaw 2026.3.x.
+
 ### Optional environment variables
 
 ```env

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,SAAS,CAAC;AAGvE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAElG;;;GAGG;AACH,UAAU,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,IAAI,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;YAChE,OAAO,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SACjD,CAAC,CAAC;KACJ,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA0BD,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CA8DpF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,SAAS,CAAC;AAGvE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAElG;;;GAGG;AACH,UAAU,iBAAiB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,IAAI,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;YAChE,OAAO,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SACjD,CAAC,CAAC;KACJ,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA0BD,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAyEpF"}

package/dist/index.js

@@ -98,17 +98,28 @@ function xprAgentsPlugin(realApi) {
         confirmHighRisk: rawConfig.confirmHighRisk !== false,
         maxTransferAmount: rawConfig.maxTransferAmount || 10000000,
     };
-    // Register all tool groups
-    (0, agent_1.registerAgentTools)(api, config);
-    (0, feedback_1.registerFeedbackTools)(api, config);
-    (0, validation_1.registerValidationTools)(api, config);
-    (0, escrow_1.registerEscrowTools)(api, config);
-    (0, indexer_1.registerIndexerTools)(api, config);
-    (0, a2a_1.registerA2ATools)(api, config);
-    (0, shellbook_1.registerShellbookTools)(api);
+    // Register all tool groups. Wrap registerTool with a counter so the boot
+    // log can report the actual count — operators grep for this line to
+    // confirm the plugin loaded fully, and a count that drifts from the docs
+    // makes that signal worthless.
+    let toolCount = 0;
+    const countingApi = {
+        ...api,
+        registerTool: (tool) => {
+            toolCount++;
+            return api.registerTool(tool);
+        },
+    };
+    (0, agent_1.registerAgentTools)(countingApi, config);
+    (0, feedback_1.registerFeedbackTools)(countingApi, config);
+    (0, validation_1.registerValidationTools)(countingApi, config);
+    (0, escrow_1.registerEscrowTools)(countingApi, config);
+    (0, indexer_1.registerIndexerTools)(countingApi, config);
+    (0, a2a_1.registerA2ATools)(countingApi, config);
+    (0, shellbook_1.registerShellbookTools)(countingApi);
     if (!hasCredentials) {
         console.log('[xpr-agents] Read-only mode: XPR_ACCOUNT not set. Write tools will fail.');
     }
-    console.log(`[xpr-agents] Plugin loaded: ${config.network} (${rpcEndpoint})`);
+    console.log(`[xpr-agents] Plugin loaded: ${toolCount} tools, ${config.network} (${rpcEndpoint})`);
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AA0EH,kCAyEC;AAjJD,uCAA6D;AAC7D,yCAAmD;AACnD,+CAAyD;AACzD,mDAA6D;AAC7D,2CAAqD;AACrD,6CAAuD;AACvD,qCAA+C;AAC/C,iDAA2D;AAO3D,sEAAsE;AACtE,wEAAwE;AACxE,6CAA+D;AAAtD,+GAAA,gBAAgB,OAAA;AAAE,2GAAA,YAAY,OAAA;AAEvC,2CAOsB;AANpB,wGAAA,UAAU,OAAA;AACV,iHAAA,mBAAmB,OAAA;AACnB,0GAAA,YAAY,OAAA;AACZ,4GAAA,cAAc,OAAA;AACd,oHAAA,sBAAsB,OAAA;AACtB,4GAAA,cAAc,OAAA;AAwBhB;;;GAGG;AACH,SAAS,aAAa,CAAC,OAA0B;IAC/C,OAAO;QACL,YAAY,CAAC,IAAoB;YAC/B,OAAO,CAAC,YAAY,CAAC;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,MAA+B;oBACxD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;oBAC1C,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;oBACnF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC/C,CAAC;aACF,CAAC,CAAC;QACL,CAAC;QACD,SAAS;YACP,OAAO,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAwB,eAAe,CAAC,OAAsC;IAC5E,6EAA6E;IAC7E,mFAAmF;IACnF,MAAM,GAAG,GAAc,OAAQ,OAAe,CAAC,SAAS,KAAK,UAAU;QACrE,CAAC,CAAC,OAAoB;QACtB,CAAC,CAAC,aAAa,CAAC,OAA4B,CAAC,CAAC;IAEhD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;IAElC,MAAM,OAAO,GAAI,SAAS,CAAC,OAAkB,IAAI,SAAS,CAAC;IAC3D,MAAM,UAAU,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACnG,MAAM,WAAW,GAAI,SAAS,CAAC,WAAsB,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,UAAU,CAAC;IAEpG,yEAAyE;IACzE,wEAAwE;IACxE,2EAA2E;IAC3E,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAEjD,6CAA6C;IAC7C,IAAI,GAAG,CAAC;IACR,IAAI,OAAO,CAAC;IAEZ,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,IAAA,uBAAa,EAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAC9C,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACjB,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,IAAA,2BAAiB,EAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,YAAY,GAAG,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAA2B,CAAC;IAE3E,MAAM,MAAM,GAAiB;QAC3B,GAAG,EAAE,GAAU;QACf,OAAO;QACP,OAAO,EAAG,SAAS,CAAC,OAAiC,IAAI,SAAS;QAClE,WAAW;QACX,UAAU,EAAG,SAAS,CAAC,UAAqB,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,+BAA+B;QAC1G,SAAS,EAAE;YACT,SAAS,EAAE,YAAY,CAAC,SAAS,IAAI,WAAW;YAChD,SAAS,EAAE,YAAY,CAAC,SAAS,IAAI,WAAW;YAChD,UAAU,EAAE,YAAY,CAAC,UAAU,IAAI,YAAY;YACnD,WAAW,EAAE,YAAY,CAAC,WAAW,IAAI,aAAa;SACvD;QACD,eAAe,EAAE,SAAS,CAAC,eAAe,KAAK,KAAK;QACpD,iBAAiB,EAAG,SAAS,CAAC,iBAA4B,IAAI,QAAQ;KACvE,CAAC;IAEF,yEAAyE;IACzE,oEAAoE;IACpE,yEAAyE;IACzE,+BAA+B;IAC/B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,WAAW,GAAc;QAC7B,GAAG,GAAG;QACN,YAAY,EAAE,CAAC,IAAS,EAAE,EAAE;YAC1B,SAAS,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;IACF,IAAA,0BAAkB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACxC,IAAA,gCAAqB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAA,oCAAuB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAA,4BAAmB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACzC,IAAA,8BAAoB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAA,sBAAgB,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACtC,IAAA,kCAAsB,EAAC,WAAW,CAAC,CAAC;IAEpC,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,0EAA0E,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,+BAA+B,SAAS,WAAW,MAAM,CAAC,OAAO,KAAK,WAAW,GAAG,CAAC,CAAC;AACpG,CAAC"}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@xpr-agents/openclaw",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "OpenClaw plugin for XPR Network Trustless Agent Registry - autonomous agent operation, escrow jobs, feedback, and validation",
   "author": "XPR Network",
+  "bin": {
+    "xpr-agents-setup-security": "scripts/setup-security.sh"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/XPRNetwork/xpr-agents.git",

package/scripts/setup-security.sh

@@ -0,0 +1,504 @@
+#!/usr/bin/env bash
+# setup-security.sh — Pillar 2 lockdown for an XPR Agents account.
+#
+# Delegates the agent's `owner` permission to a separate human-controlled
+# account, so even if the agent's active key is compromised the attacker
+# cannot rotate the account away from you.
+#
+# Idempotent: if owner is already controlled by a non-raw-key account
+# permission, exits cleanly with no changes.
+#
+# Refuses to run unattended — TTY required, explicit yes/no on every
+# prompt, type-to-confirm account names, hard-fails on any precondition
+# (account doesn't exist, key not in keychain, etc).
+#
+# See docs/SECURITY.md for the full security model.
+
+set -eu
+
+# ── Colors ─────────────────────────────────────
+if [ -t 1 ]; then
+  RED=$'\033[31m'
+  GREEN=$'\033[32m'
+  YELLOW=$'\033[33m'
+  BOLD=$'\033[1m'
+  NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; BOLD=''; NC=''
+fi
+
+err()    { printf "${RED}${BOLD}ERROR:${NC} %s\n" "$*" >&2; }
+warn()   { printf "${YELLOW}!${NC} %s\n" "$*"; }
+ok()     { printf "${GREEN}✓${NC} %s\n" "$*"; }
+info()   { printf "  %s\n" "$*"; }
+step()   { printf "\n${BOLD}[%s]${NC} %s\n" "$1" "$2"; }
+abort()  { err "$*"; exit 1; }
+
+# ── Hard preconditions ─────────────────────────
+
+# Require a TTY. We will NOT run this from a pipe, a heredoc, or under
+# automation. The whole point is human-in-the-loop.
+if [ ! -t 0 ] || [ ! -t 1 ]; then
+  err "setup-security.sh requires an interactive terminal."
+  err "Do not pipe input or run this from automation."
+  exit 1
+fi
+
+# Require proton CLI on PATH.
+if ! command -v proton >/dev/null 2>&1; then
+  err "proton CLI not found on PATH."
+  info "Install it: npm i -g @proton/cli"
+  info "Then add the npm global bin to PATH:"
+  info "  export PATH=\"\$(npm config get prefix)/bin:\$PATH\""
+  exit 1
+fi
+
+# Require XPR_ACCOUNT or --account arg.
+AGENT_ACCOUNT="${XPR_ACCOUNT:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --account) AGENT_ACCOUNT="$2"; shift 2 ;;
+    --help|-h)
+      cat <<'EOF'
+Usage: ./setup-security.sh [--account <agent-account>]
+
+Locks down the agent's `owner` permission so that only a human-controlled
+XPR account can change permissions. Run once per agent. Idempotent.
+
+The agent's `active` key stays in the proton CLI keychain — daily signing
+is unchanged. Only the `owner` permission moves to your human account.
+
+See docs/SECURITY.md for the full rationale.
+EOF
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [ -z "$AGENT_ACCOUNT" ]; then
+  err "Agent account not specified."
+  info "Pass --account <name> or set XPR_ACCOUNT in env."
+  exit 1
+fi
+
+# Validate name shape (EOSIO: 1-12 chars, .12345abcdefghijklmnopqrstuvwxyz)
+if ! printf '%s' "$AGENT_ACCOUNT" | grep -qE '^[.1-5a-z]{1,12}$'; then
+  abort "'$AGENT_ACCOUNT' is not a valid XPR Network account name (1-12 chars from .12345a-z)."
+fi
+
+# ── Banner ─────────────────────────────────────
+cat <<EOF
+
+========================================================================
+  ${BOLD}XPR AGENTS — SECURITY SETUP${NC} (Pillar 2: lock down owner)
+========================================================================
+
+  Target agent account: ${BOLD}${AGENT_ACCOUNT}${NC}
+
+  This script will delegate '$AGENT_ACCOUNT's owner permission to a
+  separate human-controlled XPR account. After this:
+
+    • Your human account controls recovery if the agent's key leaks.
+    • The agent's active key stays in the proton CLI keychain — daily
+      signing is unchanged.
+    • The agent's owner permission will have NO raw keys — only your
+      human account can change permissions.
+
+  This is recommended but not automatic. See docs/SECURITY.md for the
+  full security model.
+
+EOF
+
+# ── Step 1: Read current account state ─────────
+step "1/6" "Reading current state for '$AGENT_ACCOUNT'..."
+
+if ! ACCOUNT_JSON=$(proton account "$AGENT_ACCOUNT" --json 2>/dev/null); then
+  # Fallback: --json may not be supported on older proton CLI versions
+  if ! ACCOUNT_OUT=$(proton account "$AGENT_ACCOUNT" 2>&1); then
+    err "Failed to look up account '$AGENT_ACCOUNT'."
+    info "Does the account exist? Check: proton account $AGENT_ACCOUNT"
+    info "Are you on the right chain? Check: proton chain"
+    exit 1
+  fi
+  # No JSON support — fall back to text parsing. Less robust.
+  ACCOUNT_JSON=""
+fi
+
+# Extract permissions. Prefer JSON if available.
+if [ -n "$ACCOUNT_JSON" ]; then
+  OWNER_KEYS=$(printf '%s' "$ACCOUNT_JSON" | node -e "
+    let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+      try {
+        const a = JSON.parse(s);
+        const owner = (a.permissions||[]).find(p=>p.perm_name==='owner');
+        if (!owner) { console.log(''); return; }
+        const keys = (owner.required_auth?.keys||[]).map(k=>k.key);
+        console.log(keys.join(','));
+      } catch(e) { console.log(''); }
+    });
+  " <<< "$ACCOUNT_JSON")
+  OWNER_ACCOUNTS=$(printf '%s' "$ACCOUNT_JSON" | node -e "
+    let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+      try {
+        const a = JSON.parse(s);
+        const owner = (a.permissions||[]).find(p=>p.perm_name==='owner');
+        if (!owner) { console.log(''); return; }
+        const accts = (owner.required_auth?.accounts||[]).map(x=>x.permission.actor+'@'+x.permission.permission);
+        console.log(accts.join(','));
+      } catch(e) { console.log(''); }
+    });
+  " <<< "$ACCOUNT_JSON")
+  ACTIVE_KEYS=$(printf '%s' "$ACCOUNT_JSON" | node -e "
+    let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+      try {
+        const a = JSON.parse(s);
+        const active = (a.permissions||[]).find(p=>p.perm_name==='active');
+        if (!active) { console.log(''); return; }
+        const keys = (active.required_auth?.keys||[]).map(k=>k.key);
+        console.log(keys.join(','));
+      } catch(e) { console.log(''); }
+    });
+  " <<< "$ACCOUNT_JSON")
+else
+  abort "proton account output format not recognized. Update proton CLI: npm i -g @proton/cli"
+fi
+
+info "owner perm keys:     ${OWNER_KEYS:-(none)}"
+info "owner perm accounts: ${OWNER_ACCOUNTS:-(none)}"
+info "active perm keys:    ${ACTIVE_KEYS:-(none)}"
+
+# Idempotency check: if owner has no raw keys, we're already done.
+if [ -z "$OWNER_KEYS" ] && [ -n "$OWNER_ACCOUNTS" ]; then
+  ok "Already secured. owner is controlled by: $OWNER_ACCOUNTS"
+  info "No changes needed. If you want to change the owner-controlling account,"
+  info "run a manual updateauth — see docs/SECURITY.md."
+  exit 0
+fi
+
+if [ -z "$OWNER_KEYS" ]; then
+  abort "owner permission has no keys AND no accounts? This is unusual. Check: proton account $AGENT_ACCOUNT"
+fi
+
+# We have raw keys on owner. Proceed.
+warn "owner permission currently has raw keys. This is the default after account creation."
+warn "If that key leaks, an attacker can rotate you out of your own account."
+
+# ── Step 2: Verify we can sign as <agent>@owner ─
+step "2/6" "Verifying we can sign as ${AGENT_ACCOUNT}@owner..."
+
+KEYLIST=$(proton key:list 2>/dev/null || true)
+MATCHED_OWNER_KEY=""
+IFS=',' read -ra OWNER_KEY_ARR <<< "$OWNER_KEYS"
+for k in "${OWNER_KEY_ARR[@]}"; do
+  if printf '%s' "$KEYLIST" | grep -qF "\"publicKey\": \"$k\""; then
+    MATCHED_OWNER_KEY="$k"
+    break
+  fi
+done
+
+if [ -z "$MATCHED_OWNER_KEY" ]; then
+  err "None of the owner-permission keys are loaded in the proton CLI keychain."
+  info "Owner keys on chain: $OWNER_KEYS"
+  info ""
+  info "Load the owner private key (PVT_K1_...) into the keychain:"
+  info "  proton key:add"
+  info ""
+  info "For WebAuth-created accounts: the K1 backup key is in your wallet"
+  info "(WebAuth → Settings → Backup → reveal key)."
+  exit 1
+fi
+ok "Found matching key for ${AGENT_ACCOUNT}@owner: $MATCHED_OWNER_KEY"
+
+# Determine the K1 we'll put on active. If active is currently a WA key
+# (WebAuth biometric, unusable for autonomous signing), we replace it with
+# the K1 currently on owner. If active is already a K1, we leave it alone.
+NEW_ACTIVE_KEY=""
+ACTIVE_NEEDS_REWRITE="no"
+
+ACTIVE_HAS_WA="no"
+IFS=',' read -ra ACTIVE_KEY_ARR <<< "$ACTIVE_KEYS"
+for k in "${ACTIVE_KEY_ARR[@]}"; do
+  case "$k" in
+    PUB_WA_*) ACTIVE_HAS_WA="yes" ;;
+  esac
+done
+
+if [ "$ACTIVE_HAS_WA" = "yes" ]; then
+  # WebAuth case — must rewrite active to the K1.
+  NEW_ACTIVE_KEY="$MATCHED_OWNER_KEY"
+  ACTIVE_NEEDS_REWRITE="yes"
+  info "active permission is WebAuth-only (PUB_WA_...) — agent can't sign autonomously."
+  info "Will replace active with the K1 currently on owner: $MATCHED_OWNER_KEY"
+elif [ -z "$ACTIVE_KEYS" ]; then
+  err "active permission has no keys. This is unusual — check manually:"
+  info "  proton account $AGENT_ACCOUNT"
+  exit 1
+else
+  # Active already has K1(s). Leave alone.
+  NEW_ACTIVE_KEY="$(printf '%s' "$ACTIVE_KEYS" | cut -d, -f1)"
+  ACTIVE_NEEDS_REWRITE="no"
+  info "active permission already has K1 key: $NEW_ACTIVE_KEY"
+  info "No change to active needed."
+fi
+
+# Verify the K1 we want on active is in the keychain (whether we're
+# rewriting or leaving alone — either way, the agent needs to sign with
+# it daily).
+if ! printf '%s' "$KEYLIST" | grep -qF "\"publicKey\": \"$NEW_ACTIVE_KEY\""; then
+  err "Final active key ($NEW_ACTIVE_KEY) is not in the proton CLI keychain."
+  err "The agent would not be able to sign after this change. Aborting."
+  info "Load the matching PVT_K1_ key first: proton key:add"
+  exit 1
+fi
+ok "Final active key ($NEW_ACTIVE_KEY) is in the keychain."
+
+# ── Step 3: Ask for human account ──────────────
+step "3/6" "Your personal XPR account"
+
+cat <<EOF
+
+  ${YELLOW}This account will control recovery of '$AGENT_ACCOUNT' forever.${NC}
+
+  It MUST be an account you fully control TODAY. Strongly recommended:
+    • KYC-verified (gives the agent +30 trust score via the claim system)
+    • WebAuth-secured (Face ID / fingerprint signing, key never on a server)
+    • Not an account you share with anyone
+    • Not the same account as the agent itself
+
+  Be CAREFUL: a typo here delegates owner to a nonexistent or someone
+  else's account, and you will lose control of '$AGENT_ACCOUNT' forever.
+
+EOF
+
+read -rp "  Your personal XPR account name: " HUMAN_ACCOUNT
+HUMAN_ACCOUNT="$(printf '%s' "$HUMAN_ACCOUNT" | tr -d '[:space:]')"
+
+if [ -z "$HUMAN_ACCOUNT" ]; then
+  abort "No account name given. Aborting."
+fi
+if ! printf '%s' "$HUMAN_ACCOUNT" | grep -qE '^[.1-5a-z]{1,12}$'; then
+  abort "'$HUMAN_ACCOUNT' is not a valid XPR Network account name (1-12 chars from .12345a-z)."
+fi
+if [ "$HUMAN_ACCOUNT" = "$AGENT_ACCOUNT" ]; then
+  abort "The human account cannot be the same as the agent account. That defeats the entire purpose."
+fi
+
+info ""
+info "Looking up '$HUMAN_ACCOUNT' on chain..."
+if ! HUMAN_JSON=$(proton account "$HUMAN_ACCOUNT" --json 2>/dev/null); then
+  err "Account '$HUMAN_ACCOUNT' not found on chain."
+  info "Did you typo it? Verify at:"
+  info "  https://explorer.xprnetwork.org/account/$HUMAN_ACCOUNT"
+  info ""
+  abort "Refusing to delegate owner to a nonexistent account."
+fi
+
+# Extract human account info for display
+HUMAN_BALANCE=$(printf '%s' "$HUMAN_JSON" | node -e "
+  let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+    try {
+      const a = JSON.parse(s);
+      console.log(a.core_liquid_balance || '0 XPR');
+    } catch(e) { console.log('?'); }
+  });
+" <<< "$HUMAN_JSON")
+HUMAN_CREATED=$(printf '%s' "$HUMAN_JSON" | node -e "
+  let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+    try {
+      const a = JSON.parse(s);
+      console.log((a.created || '').slice(0,10) || '?');
+    } catch(e) { console.log('?'); }
+  });
+" <<< "$HUMAN_JSON")
+HUMAN_ACTIVE_KEYS=$(printf '%s' "$HUMAN_JSON" | node -e "
+  let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+    try {
+      const a = JSON.parse(s);
+      const active = (a.permissions||[]).find(p=>p.perm_name==='active');
+      const keys = (active?.required_auth?.keys||[]).map(k=>k.key);
+      console.log(keys.join(',') || '(no raw keys)');
+    } catch(e) { console.log('?'); }
+  });
+" <<< "$HUMAN_JSON")
+
+ok "Account exists"
+info "  Created:           $HUMAN_CREATED"
+info "  XPR balance:       $HUMAN_BALANCE"
+info "  active perm keys:  $HUMAN_ACTIVE_KEYS"
+
+# Warn if human account isn't WebAuth-secured (recommendation, not a block)
+case "$HUMAN_ACTIVE_KEYS" in
+  *PUB_WA_*) info "  ✓ active key is WebAuth (biometric) — good." ;;
+  *) warn "  active key is NOT WebAuth-biometric. This is allowed but weaker." ;;
+esac
+
+# ── Step 4: Critical confirmation ──────────────
+step "4/6" "${BOLD}${RED}CRITICAL CONFIRMATION${NC}"
+
+cat <<EOF
+
+  Open this URL in your browser ${BOLD}right now${NC}:
+      ${BOLD}https://explorer.xprnetwork.org/account/$HUMAN_ACCOUNT${NC}
+
+  Visually verify on the explorer:
+    ☐ The account name is exactly '$HUMAN_ACCOUNT' (no typos)
+    ☐ The balance / activity look like YOUR account
+    ☐ You can sign transactions from this account today
+
+  If ANY of these are wrong, hit ${BOLD}Ctrl+C${NC} now and start over.
+
+  After this script completes, '$AGENT_ACCOUNT' is controlled by '$HUMAN_ACCOUNT'
+  forever — only '$HUMAN_ACCOUNT' can change it back.
+
+EOF
+
+read -rp "  Type the agent account name '${AGENT_ACCOUNT}' to confirm target: " CONFIRM_AGENT
+if [ "$CONFIRM_AGENT" != "$AGENT_ACCOUNT" ]; then
+  abort "Agent account didn't match. Aborting (no changes made)."
+fi
+
+read -rp "  Type the human account name '${HUMAN_ACCOUNT}' to confirm controller: " CONFIRM_HUMAN
+if [ "$CONFIRM_HUMAN" != "$HUMAN_ACCOUNT" ]; then
+  abort "Human account didn't match. Aborting (no changes made)."
+fi
+
+# ── Step 5: Show transaction plan ──────────────
+step "5/6" "Transaction plan"
+
+cat <<EOF
+
+  Will push ONE atomic transaction to '$AGENT_ACCOUNT' with the
+  following updateauth actions:
+
+EOF
+
+if [ "$ACTIVE_NEEDS_REWRITE" = "yes" ]; then
+  cat <<EOF
+  ${BOLD}action 1: active → K1${NC}
+    permission: active
+    parent:     owner
+    threshold:  1
+    keys:       [$NEW_ACTIVE_KEY]
+    accounts:   []
+    (was: $ACTIVE_KEYS)
+EOF
+fi
+
+cat <<EOF
+
+  ${BOLD}action $([ "$ACTIVE_NEEDS_REWRITE" = "yes" ] && echo 2 || echo 1): owner → human account${NC}
+    permission: owner
+    parent:     (root)
+    threshold:  1
+    keys:       []
+    accounts:   [${HUMAN_ACCOUNT}@active]
+    (was raw key: $MATCHED_OWNER_KEY)
+
+  Signed by: ${AGENT_ACCOUNT}@owner (from your proton CLI keychain)
+
+  ${RED}${BOLD}This is irreversible from the agent side.${NC} After this lands,
+  only ${HUMAN_ACCOUNT}@active can change ${AGENT_ACCOUNT}'s permissions.
+
+EOF
+
+read -rp "  Type ${BOLD}'yes I understand'${NC} to proceed (anything else aborts): " FINAL
+if [ "$FINAL" != "yes I understand" ]; then
+  abort "Aborted at final confirmation. No changes made."
+fi
+
+# ── Step 6: Build and push transaction ─────────
+step "6/6" "Pushing transaction..."
+
+# Build the actions array
+ACTIONS_JSON=""
+if [ "$ACTIVE_NEEDS_REWRITE" = "yes" ]; then
+  ACTIONS_JSON="{\"account\":\"eosio\",\"name\":\"updateauth\",\"authorization\":[{\"actor\":\"${AGENT_ACCOUNT}\",\"permission\":\"owner\"}],\"data\":{\"account\":\"${AGENT_ACCOUNT}\",\"permission\":\"active\",\"parent\":\"owner\",\"auth\":{\"threshold\":1,\"keys\":[{\"key\":\"${NEW_ACTIVE_KEY}\",\"weight\":1}],\"accounts\":[],\"waits\":[]}}},"
+fi
+ACTIONS_JSON="${ACTIONS_JSON}{\"account\":\"eosio\",\"name\":\"updateauth\",\"authorization\":[{\"actor\":\"${AGENT_ACCOUNT}\",\"permission\":\"owner\"}],\"data\":{\"account\":\"${AGENT_ACCOUNT}\",\"permission\":\"owner\",\"parent\":\"\",\"auth\":{\"threshold\":1,\"keys\":[],\"accounts\":[{\"permission\":{\"actor\":\"${HUMAN_ACCOUNT}\",\"permission\":\"active\"},\"weight\":1}],\"waits\":[]}}}"
+
+TX_JSON="{\"actions\":[${ACTIONS_JSON}]}"
+
+# Push. Capture both stdout and stderr.
+if ! TX_RESULT=$(proton transaction:push "$TX_JSON" 2>&1); then
+  err "Transaction failed:"
+  printf '%s\n' "$TX_RESULT"
+  err ""
+  err "No permission changes were made (EOSIO transactions are atomic)."
+  err "If this is recoverable, re-run the script. Otherwise check:"
+  info "  proton account $AGENT_ACCOUNT"
+  exit 1
+fi
+
+# Extract tx id from the result (proton CLI prints it)
+TX_ID=$(printf '%s' "$TX_RESULT" | grep -oE '[a-f0-9]{64}' | head -1)
+if [ -n "$TX_ID" ]; then
+  ok "tx $TX_ID submitted"
+else
+  warn "Transaction submitted but tx id not parsed from output."
+  info "Output: $TX_RESULT"
+fi
+
+# Wait a beat for the tx to land
+sleep 3
+
+# Re-fetch and verify end-state
+info ""
+info "Verifying final state..."
+if ! POST_JSON=$(proton account "$AGENT_ACCOUNT" --json 2>/dev/null); then
+  err "Failed to re-fetch account state. Verify manually:"
+  info "  proton account $AGENT_ACCOUNT"
+  info "  https://explorer.xprnetwork.org/account/$AGENT_ACCOUNT"
+  exit 1
+fi
+
+POST_OWNER_KEYS=$(printf '%s' "$POST_JSON" | node -e "
+  let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+    try {
+      const a = JSON.parse(s);
+      const owner = (a.permissions||[]).find(p=>p.perm_name==='owner');
+      const keys = (owner?.required_auth?.keys||[]).map(k=>k.key);
+      console.log(keys.join(','));
+    } catch(e) { console.log(''); }
+  });
+" <<< "$POST_JSON")
+POST_OWNER_ACCOUNTS=$(printf '%s' "$POST_JSON" | node -e "
+  let s=''; process.stdin.on('data',d=>s+=d); process.stdin.on('end',()=>{
+    try {
+      const a = JSON.parse(s);
+      const owner = (a.permissions||[]).find(p=>p.perm_name==='owner');
+      const accts = (owner?.required_auth?.accounts||[]).map(x=>x.permission.actor+'@'+x.permission.permission);
+      console.log(accts.join(','));
+    } catch(e) { console.log(''); }
+  });
+" <<< "$POST_JSON")
+
+if [ -n "$POST_OWNER_KEYS" ]; then
+  err "owner still has raw keys after the change: $POST_OWNER_KEYS"
+  err "Pillar 2 is NOT in place. Investigate via the explorer."
+  exit 1
+fi
+
+if [ "$POST_OWNER_ACCOUNTS" != "${HUMAN_ACCOUNT}@active" ]; then
+  err "owner is not what we expected. Got: $POST_OWNER_ACCOUNTS"
+  err "Investigate via the explorer."
+  exit 1
+fi
+
+ok "owner now controlled by: ${HUMAN_ACCOUNT}@active (no raw keys)"
+ok "Pillar 2 is in place."
+
+cat <<EOF
+
+${GREEN}${BOLD}Done.${NC} '$AGENT_ACCOUNT' is secured.
+
+  • Daily signing: still works (active key is in the proton CLI keychain).
+  • Recovery: signed from ${HUMAN_ACCOUNT}@active if you ever need to rotate active.
+
+  Verify visually:
+    https://explorer.xprnetwork.org/account/$AGENT_ACCOUNT
+
+  Next steps (optional):
+    • Dry-run the recovery: see docs/SECURITY.md → "Optional: test recovery".
+    • Claim the agent via your KYC'd human account for +30 trust score.
+
+EOF

package/skills/xpr-agent-operator/SKILL.md

@@ -208,13 +208,14 @@ When a job involves token swaps, OTC deals, or any financial trade:
 ## Safety Rules
 
 1. **Never reveal private keys** — Your blockchain key lives in the proton CLI's encrypted keychain (loaded once via `proton key:add`) and never enters this process's memory. Do not attempt to read it, dump it, or print it. Recommend operators use a dedicated agent account, not their personal account.
-2. **Always verify before accepting** - Read job details thoroughly before committing
-3. **Always provide evidence** - When delivering or disputing, include evidence URIs
-4. **Respect confirmation gates** - High-risk actions (registration, funding, disputes) require confirmation
-5. **Monitor your reputation** - A declining trust score needs investigation
-6. **Don't over-commit** - Only accept jobs you can realistically complete
-7. **Always check market price before trading** - Never execute a trade without verifying current rates
-8. **Never sell tokens below market rate** - Protect your holdings from bad deals
+2. **Two-pillar security model** — Your account should be secured at two layers: (a) **active key** lives in the proton CLI keychain — you sign every transaction via shell-out (Pillar 1). (b) **owner permission** should point at the operator's separate human XPR account, not a raw key (Pillar 2). If the operator hasn't done Pillar 2, recommend they run `./setup-security.sh` (standalone scaffold) or `npx @xpr-agents/openclaw xpr-agents-setup-security --account <name>` (harness). The boot-time security warning from start.sh will flag this. See `docs/SECURITY.md`.
+3. **Always verify before accepting** - Read job details thoroughly before committing
+4. **Always provide evidence** - When delivering or disputing, include evidence URIs
+5. **Respect confirmation gates** - High-risk actions (registration, funding, disputes) require confirmation
+6. **Monitor your reputation** - A declining trust score needs investigation
+7. **Don't over-commit** - Only accept jobs you can realistically complete
+8. **Always check market price before trading** - Never execute a trade without verifying current rates
+9. **Never sell tokens below market rate** - Protect your holdings from bad deals
 
 ## Tool Quick Reference