@dimcool/dimclaw 0.1.14 → 0.1.17

package/dim-client.ts

@@ -3,6 +3,8 @@
  * Handles wallet-based authentication using a Solana keypair.
  */
 
+import { mkdir, writeFile, rename } from 'node:fs/promises';
+import path from 'node:path';
 import { SDK, NodeStorage } from '@dimcool/sdk';
 import { Keypair, Transaction } from '@solana/web3.js';
 import bs58 from 'bs58';
@@ -15,6 +17,14 @@ export interface DimClientConfig {
   apiUrl?: string;
   /** Referral code to use on first signup */
   referralCode?: string;
+  /** Path to HEARTBEAT.md for OpenClaw's heartbeat cycle */
+  heartbeatPath?: string;
+}
+
+export interface BufferedEvent {
+  event: string;
+  payload: unknown;
+  at: string;
 }
 
 export class DimClient {
@@ -23,6 +33,8 @@ export class DimClient {
   private config: DimClientConfig;
   private authenticated = false;
   private userId: string | null = null;
+  private eventQueue: BufferedEvent[] = [];
+  private unsubscribers: Array<() => void> = [];
 
   constructor(config: DimClientConfig) {
     this.config = config;
@@ -96,6 +108,83 @@ export class DimClient {
     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(): void {
+    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: unknown) => {
+          this.eventQueue.push({
+            event,
+            payload,
+            at: new Date().toISOString(),
+          });
+          this.writeHeartbeat().catch(() => {});
+        }),
+      );
+    }
+  }
+
+  /** Write HEARTBEAT.md with pending event summary for OpenClaw's heartbeat cycle. */
+  private async writeHeartbeat(): Promise<void> {
+    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 — call dim_check_notifications');
+    }
+    if (eventTypes.has('notification')) {
+      lines.push(
+        '- New notifications (challenges, friend requests, game results) — call dim_check_notifications',
+      );
+    }
+    if (eventTypes.has('lobby:matched') || eventTypes.has('lobby:invitation')) {
+      lines.push('- A game match is ready — call dim_get_pending_events');
+    }
+    if (eventTypes.has('game:turn')) {
+      lines.push("- It's your turn in a game — call dim_get_pending_events");
+    }
+    if (eventTypes.has('game:completed')) {
+      lines.push('- A game has completed — 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);
+  }
+
+  private resolveHeartbeatPath(): string {
+    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(): BufferedEvent[] {
+    return this.eventQueue.splice(0);
+  }
+
+  /** Peek at buffered event count without draining. */
+  get pendingEventCount(): number {
+    return this.eventQueue.length;
+  }
+
   getKeypair(): Keypair {
     return this.keypair;
   }

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,79 @@ 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;
+  }
   getKeypair() {
     return this.keypair;
   }
@@ -57373,8 +57452,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 +57473,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();
@@ -57461,6 +57540,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(
@@ -57692,7 +57772,15 @@ 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."
+    }
   ];
   api.registerTool({
     name: "dim_list_instructions",
@@ -59186,6 +59274,72 @@ function register(api) {
       }
     }
   });
+  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

package/index.ts

@@ -157,6 +157,7 @@ export default function register(api: {
       if ('error' in c) return c.error;
       try {
         const result = await c.authenticate();
+        c.startEventListeners();
         const nextSteps: string[] = [];
         if (result.username == null || result.username === '') {
           nextSteps.push(
@@ -404,6 +405,16 @@ export default function register(api: {
       description: 'Redeem shares after market resolution.',
     },
     { 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.',
+    },
   ];
   api.registerTool({
     name: 'dim_list_instructions',
@@ -2027,4 +2038,79 @@ export default function register(api: {
       }
     },
   });
+
+  // ── Real-time event awareness ─────────────────────────────────────────
+
+  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 as Array<{ unreadCount?: number }>).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,
+        );
+      }
+    },
+  });
 }

package/openclaw.plugin.json

@@ -13,6 +13,9 @@
       },
       "apiUrl": {
         "type": "string"
+      },
+      "heartbeatPath": {
+        "type": "string"
       }
     },
     "required": []
@@ -29,6 +32,10 @@
     "apiUrl": {
       "label": "API URL",
       "placeholder": "https://api.dim.cool"
+    },
+    "heartbeatPath": {
+      "label": "Heartbeat file path",
+      "placeholder": "~/.openclaw/workspace/HEARTBEAT.md"
     }
   },
   "setupHint": "After install, add your Solana wallet private key to plugins.entries.dimclaw.config.walletPrivateKey, then call dim_login to get started.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimcool/dimclaw",
-  "version": "0.1.14",
+  "version": "0.1.17",
   "description": "OpenClaw plugin for DIM — play games, chat, send USDC, and earn on DIM using the SDK directly (no MCP subprocess).",
   "type": "module",
   "openclaw": {