clanker-wallet 0.4.1 → 0.4.2

package/README.md

@@ -14,6 +14,8 @@ npx clanker-wallet
 bunx clanker-wallet
 ```
 
+Running in a sandbox (e.g. Claude Code)? Allow a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON), or `tx` fails with exit code 3. If the sandbox only lets traffic out through `HTTPS_PROXY`, run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+); Node ignores the proxy otherwise. `pair` writes `~/.clanker-wallet/` and the other commands write there too, so allow writes (see [State](#state)).
+
 ## Quick Start
 
 ```bash
@@ -34,7 +36,9 @@ clanker-wallet status
 
 ### `pair`
 
-Pair with a human's web app. Run once — identity and pairing are saved to `~/.clanker-wallet/`.
+Pair with a human's web app. Run once — `pair` writes identity and pairing to `~/.clanker-wallet/`.
+
+If the pairing JSON contains `"mode":"managed"`, the relay simulates each transaction for the human's review screen, so `tx` also sends the plain transaction fields to it. Otherwise the relay only sees ciphertext. Pair with the JSON as given.
 
 ```bash
 clanker-wallet pair '<pairing JSON from web app>'
@@ -43,7 +47,7 @@ clanker-wallet pair '<pairing JSON from web app>'
 
 ### `tx`
 
-Send a transaction request. Blocks until the human approves or rejects, for up to 1 hour by default; `--timeout <ms>` changes that.
+Send a transaction request. Blocks until the human approves or rejects, for up to 1 hour by default; `--timeout <ms>` changes that. If your shell tool kills long commands, run `tx` in the background and read its output when it exits.
 
 ```bash
 clanker-wallet tx \

package/SKILL.md

@@ -16,6 +16,16 @@ npm install -g clanker-wallet
 
 Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
+### Running in a sandbox
+
+If your commands run in a sandbox (e.g. Claude Code), the CLI needs:
+
+- **network:** a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON). Without it `tx` fails with exit code 3.
+- **the sandbox proxy:** if the sandbox only lets traffic out through `HTTPS_PROXY` (Claude Code does), Node ignores it unless you run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+). The exit-3 error says so when this applies.
+- **files:** `pair` writes your identity and the pairing to `~/.clanker-wallet/`, and the other commands write there too (they fix file permissions and create the identity if it is missing). Allow writes, not just reads.
+
+Ask the human to allow the host and the directory before you pair.
+
 ## Pairing (one-time)
 
 Before you can send transactions, check if you're already paired:
@@ -41,7 +51,9 @@ clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet
 
 If the human only pastes raw JSON (no prompt prose), pair with it directly. If they only paste the URL, ask them to click "copy prompt for agent" on the pairing screen.
 
-This saves identity and pairing to `~/.clanker-wallet/`. You only need to do this once.
+`pair` writes your identity and the pairing to `~/.clanker-wallet/`. You only need to do this once.
+
+If the JSON contains `"mode":"managed"`, the human chose managed mode: the relay simulates each transaction for the review screen, so `tx` also sends the plain transaction fields (from, to, value, data, chainId) to the relay, which shares them with its simulation provider. Without it (or with `"mode":"encrypted"`) the relay only sees ciphertext. Pair with the JSON exactly as given either way.
 
 ### Trust (first request)
 
@@ -79,7 +91,7 @@ clanker-wallet tx \
 
 This sends 0.001 ETH (`1000000000000000` wei) on Base Sepolia (chain `84532`) to the burn address `0x000000000000000000000000000000000000dEaD`.
 
-The command **blocks until the human approves or rejects**, for up to 1 hour by default. Pass `--timeout <ms>` to wait a different time (`600000` = 10 minutes). Output is JSON:
+The command **blocks until the human approves or rejects**, for up to 1 hour by default. Pass `--timeout <ms>` to wait a different time (`600000` = 10 minutes). If your shell tool kills commands after a few minutes, run `tx` in the background and read its output when it exits. Output is JSON:
 - Approved: `{"tx_hash":"0x...","status":"approved"}` (exit code 0)
 - Rejected: `{"status":"rejected","error":"..."}` (exit code 1)
 - Timeout: `{"status":"timeout","error":"..."}` (exit code 2)
@@ -166,4 +178,4 @@ clanker-wallet whoami
 - **exit code 4 / "not paired"** — run `clanker-wallet pair '<JSON>'` first
 - **exit code 2 / timeout** — human didn't respond in time, increase `--timeout` or ask them to check the web app
 - **exit code 1 / "rejected"** — human clicked reject. Explain why the tx is needed and try again if appropriate.
-- **exit code 3 / connection error** — relay may be down, try again in a few seconds
+- **exit code 3 / "relay connection error: could not reach wss://..."** — if you run in a sandbox or behind a firewall, allow that host (`relay.clanker-wallet.xyz` by default) and, if the error mentions it, rerun with `NODE_USE_ENV_PROXY=1` (see "Running in a sandbox"); otherwise the relay may be down or rate limiting, try again in a few seconds

package/bin/cli.js

@@ -241,7 +241,8 @@ exit codes:
   0  success
   1  rejected by human
   2  timeout
-  3  connection error
+  3  connection error (in a sandbox or behind a firewall, allow the relay host, wss://relay.clanker-wallet.xyz/ws by default;
+     behind HTTPS_PROXY run with NODE_USE_ENV_PROXY=1)
   4  not paired
   5  invalid arguments
 

package/dist/client.js

@@ -2,6 +2,16 @@ import { decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSe
 import { TypedEmitter } from './events.js';
 import { validateTx } from './validate.js';
 const DEFAULT_TIMEOUT_MS = 3_600_000; // 1 hour
+const UNREACHABLE_HINT = 'if you run in a sandbox or behind a firewall, allow this host; otherwise the relay may be down or rate limiting, retry in a few seconds';
+/** node's WebSocket ignores HTTPS_PROXY unless NODE_USE_ENV_PROXY is set at startup, and sandboxes (claude code) only let traffic out through that proxy */
+function proxyHint() {
+    const env = globalThis.process?.env;
+    if (!env || env.NODE_USE_ENV_PROXY)
+        return '';
+    return env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy
+        ? '; HTTPS_PROXY is set but node ignores it, rerun with NODE_USE_ENV_PROXY=1 (node 24+)'
+        : '';
+}
 export class ClankerWallet extends TypedEmitter {
     publicKey;
     secretKey;
@@ -103,8 +113,9 @@ export class ClankerWallet extends TypedEmitter {
                 return;
             }
             ws.addEventListener('error', () => {
+                // node's WebSocket error event carries no cause, so name the url: a sandbox or firewall blocking it looks the same as an outage
                 if (!settled)
-                    fail('relay connection error');
+                    fail(`relay connection error: could not reach ${relayUrl} (${UNREACHABLE_HINT}${proxyHint()})`);
             });
             ws.addEventListener('close', () => {
                 this.emit('disconnected', {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",