@dimcool/dimclaw 0.1.14 → 0.1.18

package/dist/index.js

@@ -6513,14 +6513,14 @@ var require_url_state_machine = __commonJS({
       return url3.replace(/\u0009|\u000A|\u000D/g, "");
     }
     function shortenPath(url3) {
-      const path2 = url3.path;
-      if (path2.length === 0) {
+      const path3 = url3.path;
+      if (path3.length === 0) {
         return;
       }
-      if (url3.scheme === "file" && path2.length === 1 && isNormalizedWindowsDriveLetter(path2[0])) {
+      if (url3.scheme === "file" && path3.length === 1 && isNormalizedWindowsDriveLetter(path3[0])) {
         return;
       }
-      path2.pop();
+      path3.pop();
     }
     function includesCredentials(url3) {
       return url3.username !== "" || url3.password !== "";
@@ -7577,7 +7577,7 @@ var require_node_gyp_build = __commonJS({
   "../../node_modules/node-gyp-build/node-gyp-build.js"(exports, module) {
     "use strict";
     var fs = __require("fs");
-    var path2 = __require("path");
+    var path3 = __require("path");
     var os = __require("os");
     var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require;
     var vars = process.config && process.config.variables || {};
@@ -7594,21 +7594,21 @@ var require_node_gyp_build = __commonJS({
       return runtimeRequire(load.resolve(dir));
     }
     load.resolve = load.path = function(dir) {
-      dir = path2.resolve(dir || ".");
+      dir = path3.resolve(dir || ".");
       try {
-        var name = runtimeRequire(path2.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
+        var name = runtimeRequire(path3.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
         if (process.env[name + "_PREBUILD"]) dir = process.env[name + "_PREBUILD"];
       } catch (err) {
       }
       if (!prebuildsOnly) {
-        var release = getFirst(path2.join(dir, "build/Release"), matchBuild);
+        var release = getFirst(path3.join(dir, "build/Release"), matchBuild);
         if (release) return release;
-        var debug12 = getFirst(path2.join(dir, "build/Debug"), matchBuild);
+        var debug12 = getFirst(path3.join(dir, "build/Debug"), matchBuild);
         if (debug12) return debug12;
       }
       var prebuild = resolve(dir);
       if (prebuild) return prebuild;
-      var nearby = resolve(path2.dirname(process.execPath));
+      var nearby = resolve(path3.dirname(process.execPath));
       if (nearby) return nearby;
       var target = [
         "platform=" + platform,
@@ -7625,14 +7625,14 @@ var require_node_gyp_build = __commonJS({
       ].filter(Boolean).join(" ");
       throw new Error("No native build was found for " + target + "\n    loaded from: " + dir + "\n");
       function resolve(dir2) {
-        var tuples = readdirSync(path2.join(dir2, "prebuilds")).map(parseTuple);
+        var tuples = readdirSync(path3.join(dir2, "prebuilds")).map(parseTuple);
         var tuple3 = tuples.filter(matchTuple(platform, arch)).sort(compareTuples)[0];
         if (!tuple3) return;
-        var prebuilds = path2.join(dir2, "prebuilds", tuple3.name);
+        var prebuilds = path3.join(dir2, "prebuilds", tuple3.name);
         var parsed = readdirSync(prebuilds).map(parseTags);
         var candidates = parsed.filter(matchTags(runtime, abi));
         var winner = candidates.sort(compareTags(runtime))[0];
-        if (winner) return path2.join(prebuilds, winner.file);
+        if (winner) return path3.join(prebuilds, winner.file);
       }
     };
     function readdirSync(dir) {
@@ -7644,7 +7644,7 @@ var require_node_gyp_build = __commonJS({
     }
     function getFirst(dir, filter) {
       var files = readdirSync(dir).filter(filter);
-      return files[0] && path2.join(dir, files[0]);
+      return files[0] && path3.join(dir, files[0]);
     }
     function matchBuild(name) {
       return /\.node$/.test(name);
@@ -18589,8 +18589,8 @@ var require_nacl_fast = __commonJS({
 });
 
 // index.ts
-import { mkdir, readFile, rename, writeFile } from "fs/promises";
-import path from "path";
+import { mkdir as mkdir2, readFile, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import path2 from "path";
 
 // ../../node_modules/@solana/web3.js/lib/index.esm.js
 import { Buffer as Buffer2 } from "buffer";
@@ -21589,8 +21589,8 @@ var StructError = class extends TypeError {
   constructor(failure, failures) {
     let cached;
     const { message, explanation, ...rest } = failure;
-    const { path: path2 } = failure;
-    const msg = path2.length === 0 ? message : `At path: ${path2.join(".")} -- ${message}`;
+    const { path: path3 } = failure;
+    const msg = path3.length === 0 ? message : `At path: ${path3.join(".")} -- ${message}`;
     super(explanation ?? msg);
     if (explanation != null)
       this.cause = msg;
@@ -21628,15 +21628,15 @@ function toFailure(result, context, struct2, value2) {
   } else if (typeof result === "string") {
     result = { message: result };
   }
-  const { path: path2, branch } = context;
+  const { path: path3, branch } = context;
   const { type: type3 } = struct2;
   const { refinement, message = `Expected a value of type \`${type3}\`${refinement ? ` with refinement \`${refinement}\`` : ""}, but received: \`${print(value2)}\`` } = result;
   return {
     value: value2,
     type: type3,
     refinement,
-    key: path2[path2.length - 1],
-    path: path2,
+    key: path3[path3.length - 1],
+    path: path3,
     branch,
     ...result,
     message
@@ -21654,8 +21654,8 @@ function* toFailures(result, context, struct2, value2) {
   }
 }
 function* run(value2, struct2, options = {}) {
-  const { path: path2 = [], branch = [value2], coerce: coerce3 = false, mask: mask3 = false } = options;
-  const ctx = { path: path2, branch, mask: mask3 };
+  const { path: path3 = [], branch = [value2], coerce: coerce3 = false, mask: mask3 = false } = options;
+  const ctx = { path: path3, branch, mask: mask3 };
   if (coerce3) {
     value2 = struct2.coercer(value2, ctx);
   }
@@ -21667,7 +21667,7 @@ function* run(value2, struct2, options = {}) {
   }
   for (let [k, v, s] of struct2.entries(value2, ctx)) {
     const ts = run(v, s, {
-      path: k === void 0 ? path2 : [...path2, k],
+      path: k === void 0 ? path3 : [...path3, k],
       branch: k === void 0 ? branch : [...branch, v],
       coerce: coerce3,
       mask: mask3,
@@ -28583,6 +28583,10 @@ var esm_default = base;
 var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 var esm_default2 = esm_default(ALPHABET);
 
+// dim-client.ts
+import { mkdir, writeFile, rename } from "fs/promises";
+import path from "path";
+
 // ../sdk/dist/index.js
 import crypto22 from "crypto";
 import crypto32 from "crypto";
@@ -29836,12 +29840,12 @@ function parse3(str) {
   uri.queryKey = queryKey(uri, uri["query"]);
   return uri;
 }
-function pathNames(obj, path2) {
-  const regx = /\/{2,9}/g, names = path2.replace(regx, "/").split("/");
-  if (path2.slice(0, 1) == "/" || path2.length === 0) {
+function pathNames(obj, path3) {
+  const regx = /\/{2,9}/g, names = path3.replace(regx, "/").split("/");
+  if (path3.slice(0, 1) == "/" || path3.length === 0) {
     names.splice(0, 1);
   }
-  if (path2.slice(-1) == "/") {
+  if (path3.slice(-1) == "/") {
     names.splice(names.length - 1, 1);
   }
   return names;
@@ -30458,7 +30462,7 @@ var protocol2 = Socket.protocol;
 // ../../node_modules/socket.io-client/build/esm-debug/url.js
 var import_debug7 = __toESM(require_src2(), 1);
 var debug7 = (0, import_debug7.default)("socket.io-client:url");
-function url2(uri, path2 = "", loc) {
+function url2(uri, path3 = "", loc) {
   let obj = uri;
   loc = loc || typeof location !== "undefined" && location;
   if (null == uri)
@@ -30492,7 +30496,7 @@ function url2(uri, path2 = "", loc) {
   obj.path = obj.path || "/";
   const ipv6 = obj.host.indexOf(":") !== -1;
   const host = ipv6 ? "[" + obj.host + "]" : obj.host;
-  obj.id = obj.protocol + "://" + host + ":" + obj.port + path2;
+  obj.id = obj.protocol + "://" + host + ":" + obj.port + path3;
   obj.href = obj.protocol + "://" + host + (loc && loc.port === obj.port ? "" : ":" + obj.port);
   return obj;
 }
@@ -32116,8 +32120,8 @@ function lookup(uri, opts) {
   const parsed = url2(uri, opts.path || "/socket.io");
   const source = parsed.source;
   const id = parsed.id;
-  const path2 = parsed.path;
-  const sameNamespace = cache[id] && path2 in cache[id]["nsps"];
+  const path3 = parsed.path;
+  const sameNamespace = cache[id] && path3 in cache[id]["nsps"];
   const newConnection = opts.forceNew || opts["force new connection"] || false === opts.multiplex || sameNamespace;
   let io;
   if (newConnection) {
@@ -38664,14 +38668,14 @@ var require_url_state_machine2 = __commonJS2({
       return url22.replace(/\u0009|\u000A|\u000D/g, "");
     }
     function shortenPath(url22) {
-      const path2 = url22.path;
-      if (path2.length === 0) {
+      const path3 = url22.path;
+      if (path3.length === 0) {
         return;
       }
-      if (url22.scheme === "file" && path2.length === 1 && isNormalizedWindowsDriveLetter(path2[0])) {
+      if (url22.scheme === "file" && path3.length === 1 && isNormalizedWindowsDriveLetter(path3[0])) {
         return;
       }
-      path2.pop();
+      path3.pop();
     }
     function includesCredentials(url22) {
       return url22.username !== "" || url22.password !== "";
@@ -39718,7 +39722,7 @@ var require_node_gyp_build3 = __commonJS2({
   "../../node_modules/node-gyp-build/node-gyp-build.js"(exports, module) {
     "use strict";
     var fs = __require2("fs");
-    var path2 = __require2("path");
+    var path3 = __require2("path");
     var os = __require2("os");
     var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require2;
     var vars = process.config && process.config.variables || {};
@@ -39735,21 +39739,21 @@ var require_node_gyp_build3 = __commonJS2({
       return runtimeRequire(load.resolve(dir));
     }
     load.resolve = load.path = function(dir) {
-      dir = path2.resolve(dir || ".");
+      dir = path3.resolve(dir || ".");
       try {
-        var name = runtimeRequire(path2.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
+        var name = runtimeRequire(path3.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
         if (process.env[name + "_PREBUILD"]) dir = process.env[name + "_PREBUILD"];
       } catch (err) {
       }
       if (!prebuildsOnly) {
-        var release = getFirst(path2.join(dir, "build/Release"), matchBuild);
+        var release = getFirst(path3.join(dir, "build/Release"), matchBuild);
         if (release) return release;
-        var debug12 = getFirst(path2.join(dir, "build/Debug"), matchBuild);
+        var debug12 = getFirst(path3.join(dir, "build/Debug"), matchBuild);
         if (debug12) return debug12;
       }
       var prebuild = resolve(dir);
       if (prebuild) return prebuild;
-      var nearby = resolve(path2.dirname(process.execPath));
+      var nearby = resolve(path3.dirname(process.execPath));
       if (nearby) return nearby;
       var target = [
         "platform=" + platform,
@@ -39766,14 +39770,14 @@ var require_node_gyp_build3 = __commonJS2({
       ].filter(Boolean).join(" ");
       throw new Error("No native build was found for " + target + "\n    loaded from: " + dir + "\n");
       function resolve(dir2) {
-        var tuples = readdirSync(path2.join(dir2, "prebuilds")).map(parseTuple);
+        var tuples = readdirSync(path3.join(dir2, "prebuilds")).map(parseTuple);
         var tuple22 = tuples.filter(matchTuple(platform, arch)).sort(compareTuples)[0];
         if (!tuple22) return;
-        var prebuilds = path2.join(dir2, "prebuilds", tuple22.name);
+        var prebuilds = path3.join(dir2, "prebuilds", tuple22.name);
         var parsed = readdirSync(prebuilds).map(parseTags);
         var candidates = parsed.filter(matchTags(runtime, abi));
         var winner = candidates.sort(compareTags(runtime))[0];
-        if (winner) return path2.join(prebuilds, winner.file);
+        if (winner) return path3.join(prebuilds, winner.file);
       }
     };
     function readdirSync(dir) {
@@ -39785,7 +39789,7 @@ var require_node_gyp_build3 = __commonJS2({
     }
     function getFirst(dir, filter) {
       var files = readdirSync(dir).filter(filter);
-      return files[0] && path2.join(dir, files[0]);
+      return files[0] && path3.join(dir, files[0]);
     }
     function matchBuild(name) {
       return /\.node$/.test(name);
@@ -46870,8 +46874,8 @@ var StructError2 = class extends TypeError {
   constructor(failure, failures) {
     let cached;
     const { message, explanation, ...rest } = failure;
-    const { path: path2 } = failure;
-    const msg = path2.length === 0 ? message : `At path: ${path2.join(".")} -- ${message}`;
+    const { path: path3 } = failure;
+    const msg = path3.length === 0 ? message : `At path: ${path3.join(".")} -- ${message}`;
     super(explanation ?? msg);
     if (explanation != null)
       this.cause = msg;
@@ -46909,15 +46913,15 @@ function toFailure2(result, context, struct2, value2) {
   } else if (typeof result === "string") {
     result = { message: result };
   }
-  const { path: path2, branch } = context;
+  const { path: path3, branch } = context;
   const { type: type22 } = struct2;
   const { refinement, message = `Expected a value of type \`${type22}\`${refinement ? ` with refinement \`${refinement}\`` : ""}, but received: \`${print2(value2)}\`` } = result;
   return {
     value: value2,
     type: type22,
     refinement,
-    key: path2[path2.length - 1],
-    path: path2,
+    key: path3[path3.length - 1],
+    path: path3,
     branch,
     ...result,
     message
@@ -46935,8 +46939,8 @@ function* toFailures2(result, context, struct2, value2) {
   }
 }
 function* run2(value2, struct2, options = {}) {
-  const { path: path2 = [], branch = [value2], coerce: coerce22 = false, mask: mask22 = false } = options;
-  const ctx = { path: path2, branch, mask: mask22 };
+  const { path: path3 = [], branch = [value2], coerce: coerce22 = false, mask: mask22 = false } = options;
+  const ctx = { path: path3, branch, mask: mask22 };
   if (coerce22) {
     value2 = struct2.coercer(value2, ctx);
   }
@@ -46948,7 +46952,7 @@ function* run2(value2, struct2, options = {}) {
   }
   for (let [k, v, s] of struct2.entries(value2, ctx)) {
     const ts = run2(v, s, {
-      path: k === void 0 ? path2 : [...path2, k],
+      path: k === void 0 ? path3 : [...path3, k],
       branch: k === void 0 ? branch : [...branch, v],
       coerce: coerce22,
       mask: mask22,
@@ -57305,6 +57309,8 @@ var DimClient = class {
   config;
   authenticated = false;
   userId = null;
+  eventQueue = [];
+  unsubscribers = [];
   constructor(config) {
     this.config = config;
     const secretKeyBytes = esm_default2.decode(config.walletPrivateKey);
@@ -57360,6 +57366,97 @@ var DimClient = class {
   async ensureConnected(timeoutMs = 1e4) {
     await this.sdk.ensureWebSocketConnected(timeoutMs);
   }
+  /**
+   * Subscribe to key WS events and buffer them for agent consumption.
+   * Call after authenticate() when the WS transport is connected.
+   */
+  startEventListeners() {
+    const events = [
+      "chat:message",
+      "notification",
+      "lobby:matched",
+      "lobby:invitation",
+      "game:turn",
+      "game:completed"
+    ];
+    for (const event of events) {
+      this.unsubscribers.push(
+        this.sdk.events.subscribe(event, (payload) => {
+          this.eventQueue.push({
+            event,
+            payload,
+            at: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          this.writeHeartbeat().catch(() => {
+          });
+        })
+      );
+    }
+  }
+  /** Write HEARTBEAT.md with pending event summary for OpenClaw's heartbeat cycle. */
+  async writeHeartbeat() {
+    if (!this.config.heartbeatPath) return;
+    const filePath = this.resolveHeartbeatPath();
+    const count = this.eventQueue.length;
+    if (count === 0) return;
+    const lines = ["# DIM Heartbeat", ""];
+    const eventTypes = new Set(this.eventQueue.map((e) => e.event));
+    if (eventTypes.has("chat:message")) {
+      lines.push("- You have new DMs \u2014 call dim_check_notifications");
+    }
+    if (eventTypes.has("notification")) {
+      lines.push(
+        "- New notifications (challenges, friend requests, game results) \u2014 call dim_check_notifications"
+      );
+    }
+    if (eventTypes.has("lobby:matched") || eventTypes.has("lobby:invitation")) {
+      lines.push("- A game match is ready \u2014 call dim_get_pending_events");
+    }
+    if (eventTypes.has("game:turn")) {
+      lines.push("- It's your turn in a game \u2014 call dim_get_pending_events");
+    }
+    if (eventTypes.has("game:completed")) {
+      lines.push("- A game has completed \u2014 call dim_get_pending_events");
+    }
+    lines.push("");
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
+    await writeFile(tmp, lines.join("\n"), "utf8");
+    await rename(tmp, filePath);
+  }
+  resolveHeartbeatPath() {
+    const p = this.config.heartbeatPath;
+    if (p.startsWith("~/") && process.env.HOME) {
+      return path.join(process.env.HOME, p.slice(2));
+    }
+    return path.resolve(p);
+  }
+  /** Drain all buffered events since last call. */
+  drainEvents() {
+    return this.eventQueue.splice(0);
+  }
+  /** Peek at buffered event count without draining. */
+  get pendingEventCount() {
+    return this.eventQueue.length;
+  }
+  // ── Daily spend tracking ──────────────────────────────────────────────
+  dailySpendMinor = 0;
+  spendResetDate = "";
+  resetDailySpendIfNeeded() {
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    if (this.spendResetDate !== today) {
+      this.dailySpendMinor = 0;
+      this.spendResetDate = today;
+    }
+  }
+  recordSpend(amountMinor) {
+    this.resetDailySpendIfNeeded();
+    this.dailySpendMinor += amountMinor;
+  }
+  get dailySpentDollars() {
+    this.resetDailySpendIfNeeded();
+    return this.dailySpendMinor / 1e6;
+  }
   getKeypair() {
     return this.keypair;
   }
@@ -57373,8 +57470,8 @@ function getPluginConfig(api) {
   return dimclawEntry?.config ?? null;
 }
 function resolveStorePath(storePath) {
-  const expanded = storePath.startsWith("~/") && process.env.HOME ? path.join(process.env.HOME, storePath.slice(2)) : storePath;
-  return path.resolve(expanded);
+  const expanded = storePath.startsWith("~/") && process.env.HOME ? path2.join(process.env.HOME, storePath.slice(2)) : storePath;
+  return path2.resolve(expanded);
 }
 async function readWalletFile(storePath) {
   try {
@@ -57394,14 +57491,14 @@ async function readWalletFile(storePath) {
   }
 }
 async function writeWalletFile(storePath, record3) {
-  await mkdir(path.dirname(storePath), { recursive: true });
+  await mkdir2(path2.dirname(storePath), { recursive: true });
   const tmp = `${storePath}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(record3, null, 2)}
+  await writeFile2(tmp, `${JSON.stringify(record3, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
   });
-  await rename(tmp, storePath);
+  await rename2(tmp, storePath);
 }
 function createWalletRecord() {
   const keypair = Keypair.generate();
@@ -57422,6 +57519,194 @@ async function resolveWalletKey(config) {
   await writeWalletFile(storePath, record3);
   return record3.walletPrivateKey;
 }
+function generateOnboardingScript(platform, referrer) {
+  const templates = {
+    openclaw: `# Connect to DIM \u2014 OpenClaw Setup
+
+## Step 1: Install the DIM plugin
+\`\`\`bash
+openclaw plugins install @dimcool/dimclaw
+\`\`\`
+
+## Step 2: Configure
+Add to your OpenClaw config under \`plugins.entries.dimclaw.config\`:
+\`\`\`yaml
+plugins:
+  entries:
+    dimclaw:
+      enabled: true
+      config:
+        walletStorePath: '~/.dim/openclaw-wallet.json'
+\`\`\`
+A wallet will be created automatically on first run.
+
+## Step 3: Restart and verify
+\`\`\`bash
+openclaw gateway restart
+\`\`\`
+
+Then ask your agent to run:
+1. \`dim_login\`
+2. \`dim_apply_referral_code\` with referralCode: \`${referrer}\`
+3. \`dim_get_balance\`
+
+## Step 4: Fund your wallet
+Send USDC on Solana to the wallet address shown by \`dim_get_balance\`. Even $5 is enough to start playing.
+
+You now have a 10% fee discount on all games thanks to the referral code!`,
+    "claude-desktop": `# Connect to DIM \u2014 Claude Desktop Setup
+
+## Step 1: Initialize wallet
+\`\`\`bash
+npx @dimcool/mcp init-wallet
+\`\`\`
+Copy the wallet store path from the output.
+
+## Step 2: Edit your Claude Desktop config
+Open \`~/Library/Application Support/Claude/claude_desktop_config.json\` (macOS) or \`%APPDATA%\\Claude\\claude_desktop_config.json\` (Windows).
+
+Add this to the \`mcpServers\` section:
+\`\`\`json
+{
+  "mcpServers": {
+    "dim": {
+      "command": "npx",
+      "args": ["@dimcool/mcp"],
+      "env": {
+        "DIM_WALLET_STORE_PATH": "/path/from/init-wallet/output",
+        "DIM_API_URL": "https://api.dim.cool",
+        "DIM_REFERRAL_CODE": "${referrer}"
+      }
+    }
+  }
+}
+\`\`\`
+Replace \`/path/from/init-wallet/output\` with the actual path from step 1.
+
+## Step 3: Restart Claude Desktop
+Quit and reopen Claude Desktop. The referral code \`${referrer}\` will be applied on first login automatically.
+
+## Step 4: Verify
+Ask Claude: "Log in to DIM and check my balance"
+Claude will call \`dim_login\` then \`dim_get_balance\`.
+
+## Step 5: Fund your wallet
+Send USDC on Solana to the wallet address shown. Even $5 is enough to start.
+
+You have a 10% fee discount on all games thanks to the referral code!`,
+    cursor: `# Connect to DIM \u2014 Cursor Setup
+
+## Step 1: Initialize wallet
+\`\`\`bash
+npx @dimcool/mcp init-wallet
+\`\`\`
+Copy the wallet store path from the output.
+
+## Step 2: Edit your Cursor MCP config
+Create or edit \`.cursor/mcp.json\` in your project root:
+\`\`\`json
+{
+  "mcpServers": {
+    "dim": {
+      "command": "npx",
+      "args": ["@dimcool/mcp"],
+      "env": {
+        "DIM_WALLET_STORE_PATH": "/path/from/init-wallet/output",
+        "DIM_API_URL": "https://api.dim.cool",
+        "DIM_REFERRAL_CODE": "${referrer}"
+      }
+    }
+  }
+}
+\`\`\`
+Replace \`/path/from/init-wallet/output\` with the actual path from step 1.
+
+## Step 3: Restart Cursor
+The referral code \`${referrer}\` will be applied on first login automatically.
+
+## Step 4: Verify
+Ask: "Log in to DIM and check my balance"
+
+## Step 5: Fund your wallet
+Send USDC on Solana to the wallet address shown. Even $5 is enough to start.`,
+    hermes: `# Connect to DIM \u2014 Hermes Setup
+
+## Step 1: Initialize wallet
+\`\`\`bash
+npx @dimcool/mcp init-wallet
+\`\`\`
+Copy the wallet store path.
+
+## Step 2: Add DIM as a Hermes skill
+In your Hermes config, add:
+\`\`\`yaml
+skills:
+  dim:
+    command: npx
+    args: ["@dimcool/mcp"]
+    env:
+      DIM_WALLET_STORE_PATH: "/path/from/init-wallet/output"
+      DIM_API_URL: "https://api.dim.cool"
+      DIM_REFERRAL_CODE: "${referrer}"
+\`\`\`
+
+## Step 3: Restart Hermes
+The referral code \`${referrer}\` will be applied on first login.
+
+## Step 4: Verify
+Call \`dim_login\` then \`dim_get_balance\`.
+
+## Step 5: Fund your wallet
+Send USDC on Solana to the wallet address shown.`,
+    "node-sdk": `# Connect to DIM \u2014 Node.js SDK Setup
+
+## Step 1: Install packages
+\`\`\`bash
+npm install @dimcool/sdk @dimcool/wallet
+\`\`\`
+
+## Step 2: Initialize and connect
+\`\`\`typescript
+import { SDK, NodeStorage } from '@dimcool/sdk';
+import { Wallet } from '@dimcool/wallet';
+
+const wallet = new Wallet({
+  enabledNetworks: ['solana'],
+  fromPrivateKey: process.env.DIM_WALLET_PRIVATE_KEY!,
+});
+
+const sdk = new SDK({
+  appId: 'dim-agents',
+  baseUrl: 'https://api.dim.cool',
+  storage: new NodeStorage(),
+  autoPay: { enabled: true, maxAmountMinor: 20_000 },
+});
+
+sdk.wallet.setSigner(wallet.getSigner());
+
+const { access_token, user } = await sdk.auth.loginWithWallet({
+  referralCode: '${referrer}',
+});
+
+sdk.wsTransport.setAccessToken(access_token);
+await sdk.ensureWebSocketConnected(10000);
+
+console.log('Connected as', user.username, '\u2014 wallet:', wallet.getAddresses().solana);
+\`\`\`
+
+## Step 3: Fund your wallet
+Send USDC on Solana to the wallet address. Even $5 is enough to start.
+
+The referral code \`${referrer}\` gives you a 10% fee discount on all games.
+
+Full docs: https://docs.dim.cool`
+  };
+  const script = templates[platform];
+  if (!script) {
+    return `Unknown platform "${platform}". Supported: openclaw, claude-desktop, cursor, hermes, node-sdk`;
+  }
+  return script;
+}
 function textResult(text, isError = false) {
   return {
     content: [{ type: "text", text }],
@@ -57430,15 +57715,32 @@ function textResult(text, isError = false) {
 }
 function register(api) {
   let client = null;
+  let pluginConfig = null;
+  function checkSpendLimit(c, amountDollars, isGameBet = false) {
+    if (!pluginConfig) return null;
+    if (isGameBet) {
+      const maxBet = pluginConfig.maxBetPerGame ?? 1;
+      if (amountDollars > maxBet) {
+        return `Bet $${amountDollars.toFixed(2)} exceeds maxBetPerGame limit of $${maxBet.toFixed(2)}. Ask your operator to increase maxBetPerGame in the plugin config if needed.`;
+      }
+    }
+    const limit = pluginConfig.dailySpendLimit ?? 20;
+    const projected = c.dailySpentDollars + amountDollars;
+    if (projected > limit) {
+      return `Daily spend limit reached ($${c.dailySpentDollars.toFixed(2)} spent of $${limit.toFixed(2)} limit). This action would cost $${amountDollars.toFixed(2)}. Ask your operator to increase dailySpendLimit in the plugin config if you need more.`;
+    }
+    return null;
+  }
   async function getClient() {
     if (client) return client;
-    const config = getPluginConfig(api);
-    if (!config) return null;
-    const walletPrivateKey = await resolveWalletKey(config);
+    pluginConfig = getPluginConfig(api);
+    if (!pluginConfig) return null;
+    const walletPrivateKey = await resolveWalletKey(pluginConfig);
     if (!walletPrivateKey) return null;
     client = new DimClient({
       walletPrivateKey,
-      apiUrl: config.apiUrl
+      apiUrl: pluginConfig.apiUrl,
+      heartbeatPath: pluginConfig.heartbeatPath
     });
     return client;
   }
@@ -57461,6 +57763,7 @@ function register(api) {
       if ("error" in c) return c.error;
       try {
         const result = await c.authenticate();
+        c.startEventListeners();
         const nextSteps = [];
         if (result.username == null || result.username === "") {
           nextSteps.push(
@@ -57488,6 +57791,15 @@ function register(api) {
           userId: result.userId,
           username: result.username ?? null,
           walletAddress: c.walletAddress,
+          agentConfig: {
+            autoAcceptFriendRequests: pluginConfig?.autoAcceptFriendRequests ?? false,
+            autoReplyDms: pluginConfig?.autoReplyDms ?? false,
+            autoPlayGames: pluginConfig?.autoPlayGames ?? false,
+            maxBetPerGame: pluginConfig?.maxBetPerGame ?? 1,
+            dailySpendLimit: pluginConfig?.dailySpendLimit ?? 20,
+            autoJoinGlobalChat: pluginConfig?.autoJoinGlobalChat ?? false,
+            autoPromoteReferrals: pluginConfig?.autoPromoteReferrals ?? false
+          },
           nextSteps
         };
         return textResult(JSON.stringify(response, null, 2));
@@ -57692,7 +58004,23 @@ function register(api) {
       name: "dim_redeem_shares",
       description: "Redeem shares after market resolution."
     },
-    { name: "dim_get_market_analytics", description: "Get market analytics." }
+    { name: "dim_get_market_analytics", description: "Get market analytics." },
+    {
+      name: "dim_get_pending_events",
+      description: "Drain buffered real-time events (DMs, challenges, game turns). Call regularly."
+    },
+    {
+      name: "dim_check_notifications",
+      description: "Check unread notifications, DMs, and friend requests in one call."
+    },
+    {
+      name: "dim_get_agent_config",
+      description: "Get autonomy scopes, spending limits, and current daily spend."
+    },
+    {
+      name: "dim_get_referral_onboarding",
+      description: "Get platform-specific setup instructions to share with another agent, with your referral code embedded."
+    }
   ];
   api.registerTool({
     name: "dim_list_instructions",
@@ -57757,9 +58085,12 @@ function register(api) {
       if ("error" in c) return c.error;
       const recipient = String(params.recipient ?? "");
       const amount = Number(params.amount ?? 0);
+      const limitErr = checkSpendLimit(c, amount);
+      if (limitErr) return textResult(limitErr, true);
       try {
         const amountMinor = Math.round(amount * 1e6);
         const result = await c.sdk.wallet.send(recipient, amountMinor);
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -57806,9 +58137,12 @@ function register(api) {
       if ("error" in c) return c.error;
       const recipientUsername = String(params.recipientUsername ?? "");
       const amount = Number(params.amount ?? 0);
+      const limitErr = checkSpendLimit(c, amount);
+      if (limitErr) return textResult(limitErr, true);
       try {
         const amountMinor = Math.round(amount * 1e6);
         const result = await c.sdk.tips.send(recipientUsername, amountMinor);
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -58197,9 +58531,15 @@ function register(api) {
       const c = await requireClient();
       if ("error" in c) return c.error;
       const gameType = String(params.gameType ?? "");
-      const betAmount = typeof params.betAmount === "number" ? Math.round(params.betAmount * 1e6) : void 0;
+      const betDollars = typeof params.betAmount === "number" ? params.betAmount : 0;
+      const betAmount = betDollars > 0 ? Math.round(betDollars * 1e6) : void 0;
+      if (betDollars > 0) {
+        const limitErr = checkSpendLimit(c, betDollars, true);
+        if (limitErr) return textResult(limitErr, true);
+      }
       try {
         const lobby = await c.sdk.lobbies.createLobby(gameType, betAmount);
+        if (betAmount) c.recordSpend(betAmount);
         return textResult(
           JSON.stringify(
             {
@@ -58397,12 +58737,15 @@ function register(api) {
       const c = await requireClient();
       if ("error" in c) return c.error;
       const amount = Number(params.amount ?? 0);
+      const limitErr = checkSpendLimit(c, amount);
+      if (limitErr) return textResult(limitErr, true);
       try {
         const amountMinor = Math.round(amount * 1e6);
         const result = await c.sdk.games.sendDonation(
           String(params.gameId ?? ""),
           amountMinor
         );
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -58983,6 +59326,8 @@ function register(api) {
       const amount = Number(params.amount ?? 0);
       const gameId = String(params.gameId ?? "");
       const outcomeId = String(params.outcomeId ?? "");
+      const limitErr = checkSpendLimit(c, amount);
+      if (limitErr) return textResult(limitErr, true);
       try {
         const amountMinor = Math.round(amount * 1e6);
         const { transaction: txBase64 } = await c.sdk.markets.prepareBuyOrder(
@@ -58999,6 +59344,7 @@ function register(api) {
           outcomeId,
           amountMinor
         );
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -59186,6 +59532,137 @@ function register(api) {
       }
     }
   });
+  api.registerTool({
+    name: "dim_get_agent_config",
+    description: "Get the agent autonomy configuration: what actions are allowed (friends, DMs, games, chat, referral promotion), spending limits, and current daily spend.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    async execute() {
+      const c = await requireClient();
+      if ("error" in c) return c.error;
+      return textResult(
+        JSON.stringify(
+          {
+            autoAcceptFriendRequests: pluginConfig?.autoAcceptFriendRequests ?? false,
+            autoReplyDms: pluginConfig?.autoReplyDms ?? false,
+            autoPlayGames: pluginConfig?.autoPlayGames ?? false,
+            maxBetPerGame: pluginConfig?.maxBetPerGame ?? 1,
+            dailySpendLimit: pluginConfig?.dailySpendLimit ?? 20,
+            dailySpentSoFar: `$${c.dailySpentDollars.toFixed(2)}`,
+            dailyRemaining: `$${Math.max(0, (pluginConfig?.dailySpendLimit ?? 20) - c.dailySpentDollars).toFixed(2)}`,
+            autoJoinGlobalChat: pluginConfig?.autoJoinGlobalChat ?? false,
+            autoPromoteReferrals: pluginConfig?.autoPromoteReferrals ?? false,
+            hint: "These scopes are set by your operator in the plugin config. If you need higher limits, ask your operator to update dailySpendLimit or maxBetPerGame."
+          },
+          null,
+          2
+        )
+      );
+    }
+  });
+  api.registerTool({
+    name: "dim_get_referral_onboarding",
+    description: "Get platform-specific setup instructions to share with another agent or user to onboard them to DIM with your referral code. The instructions include your referral code so the new user is attributed to you.",
+    parameters: {
+      type: "object",
+      properties: {
+        platform: {
+          type: "string",
+          enum: ["openclaw", "claude-desktop", "cursor", "hermes", "node-sdk"],
+          description: "Target platform: openclaw, claude-desktop, cursor, hermes, or node-sdk"
+        }
+      },
+      required: ["platform"],
+      additionalProperties: false
+    },
+    async execute(_, params) {
+      const c = await requireClient();
+      if ("error" in c) return c.error;
+      try {
+        let username = "YOUR_USERNAME";
+        try {
+          if (c.currentUserId) {
+            const profile = await c.sdk.users.getUserById(c.currentUserId);
+            if (profile.username) username = profile.username;
+          }
+        } catch {
+        }
+        const platform = String(params.platform ?? "openclaw");
+        const script = generateOnboardingScript(platform, username);
+        return textResult(script);
+      } catch (err) {
+        return textResult(
+          `Failed to generate onboarding script: ${err instanceof Error ? err.message : String(err)}`,
+          true
+        );
+      }
+    }
+  });
+  api.registerTool({
+    name: "dim_get_pending_events",
+    description: "Drain buffered real-time events (DMs, challenges, game turns, match notifications). Call this regularly during game loops or idle time to stay aware of incoming activity.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    async execute() {
+      const c = await requireClient();
+      if ("error" in c) return c.error;
+      try {
+        const events = c.drainEvents();
+        return textResult(
+          JSON.stringify(
+            {
+              count: events.length,
+              events,
+              hint: events.length === 0 ? "No new events since last check." : "Process these events and take action as needed."
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        return textResult(
+          `Failed to get pending events: ${err instanceof Error ? err.message : String(err)}`,
+          true
+        );
+      }
+    }
+  });
+  api.registerTool({
+    name: "dim_check_notifications",
+    description: "Check all pending items in one call: unread notifications (challenges, game results), unread DM threads, and incoming friend requests. Use this to catch up after being idle.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    async execute() {
+      const c = await requireClient();
+      if ("error" in c) return c.error;
+      try {
+        const [notifications, dmThreads, friendRequests] = await Promise.all([
+          c.sdk.notifications.list({ page: 1, limit: 20 }),
+          c.sdk.chat.listDmThreads(),
+          c.sdk.users.getIncomingFriendRequests()
+        ]);
+        const unreadDms = dmThreads.filter(
+          (t) => (t.unreadCount ?? 0) > 0
+        );
+        return textResult(
+          JSON.stringify(
+            {
+              unreadNotificationCount: notifications.unreadCount,
+              notifications: notifications.notifications.filter((n) => !n.read),
+              unreadDmThreads: unreadDms,
+              incomingFriendRequests: friendRequests,
+              pendingWsEvents: c.pendingEventCount,
+              hint: "Use dim_get_pending_events to drain buffered real-time events."
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        return textResult(
+          `Failed to check notifications: ${err instanceof Error ? err.message : String(err)}`,
+          true
+        );
+      }
+    }
+  });
 }
 export {
   register as default