@dimcool/dimclaw 0.1.14 → 0.1.18

package/index.ts

@@ -14,6 +14,15 @@ type PluginConfig = {
   walletPrivateKey?: string;
   walletStorePath?: string;
   apiUrl?: string;
+  heartbeatPath?: string;
+  // Autonomy scopes
+  autoAcceptFriendRequests?: boolean;
+  autoReplyDms?: boolean;
+  autoPlayGames?: boolean;
+  maxBetPerGame?: number;
+  dailySpendLimit?: number;
+  autoJoinGlobalChat?: boolean;
+  autoPromoteReferrals?: boolean;
 };
 
 function getPluginConfig(api: { config?: unknown }): PluginConfig | null {
@@ -93,6 +102,200 @@ async function resolveWalletKey(config: PluginConfig): Promise<string | null> {
   return record.walletPrivateKey;
 }
 
+function generateOnboardingScript(platform: string, referrer: string): string {
+  const templates: Record<string, string> = {
+    openclaw: `# Connect to DIM — 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 — 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 — 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 — 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 — 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, '— 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: string,
   isError = false,
@@ -119,16 +322,38 @@ export default function register(api: {
   }) => void;
 }) {
   let client: DimClient | null = null;
+  let pluginConfig: PluginConfig | null = null;
+
+  function checkSpendLimit(
+    c: DimClient,
+    amountDollars: number,
+    isGameBet = false,
+  ): string | null {
+    if (!pluginConfig) return null;
+    if (isGameBet) {
+      const maxBet = pluginConfig.maxBetPerGame ?? 1.0;
+      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.0;
+    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(): Promise<DimClient | null> {
     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;
   }
@@ -157,6 +382,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(
@@ -185,6 +411,16 @@ export default 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.0,
+            dailySpendLimit: pluginConfig?.dailySpendLimit ?? 20.0,
+            autoJoinGlobalChat: pluginConfig?.autoJoinGlobalChat ?? false,
+            autoPromoteReferrals: pluginConfig?.autoPromoteReferrals ?? false,
+          },
           nextSteps,
         };
         return textResult(JSON.stringify(response, null, 2));
@@ -404,6 +640,26 @@ 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.',
+    },
+    {
+      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',
@@ -474,9 +730,12 @@ export default 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 * 1_000_000);
         const result = await c.sdk.wallet.send(recipient, amountMinor);
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -525,9 +784,12 @@ export default 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 * 1_000_000);
         const result = await c.sdk.tips.send(recipientUsername, amountMinor);
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -945,12 +1207,17 @@ export default function register(api: {
       const c = await requireClient();
       if ('error' in c) return c.error;
       const gameType = String(params.gameType ?? '');
+      const betDollars =
+        typeof params.betAmount === 'number' ? params.betAmount : 0;
       const betAmount =
-        typeof params.betAmount === 'number'
-          ? Math.round(params.betAmount * 1_000_000)
-          : undefined;
+        betDollars > 0 ? Math.round(betDollars * 1_000_000) : undefined;
+      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(
             {
@@ -1169,12 +1436,15 @@ export default 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 * 1_000_000);
         const result = await c.sdk.games.sendDonation(
           String(params.gameId ?? ''),
           amountMinor,
         );
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -1814,6 +2084,8 @@ export default 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 * 1_000_000);
         const { transaction: txBase64 } = await c.sdk.markets.prepareBuyOrder(
@@ -1830,6 +2102,7 @@ export default function register(api: {
           outcomeId,
           amountMinor,
         );
+        c.recordSpend(amountMinor);
         return textResult(
           JSON.stringify(
             {
@@ -2027,4 +2300,155 @@ export default function register(api: {
       }
     },
   });
+
+  // ── Agent config ─────────────────────────────────────────────────────
+
+  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.0,
+            dailySpendLimit: pluginConfig?.dailySpendLimit ?? 20.0,
+            dailySpentSoFar: `$${c.dailySpentDollars.toFixed(2)}`,
+            dailyRemaining: `$${Math.max(0, (pluginConfig?.dailySpendLimit ?? 20.0) - 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,
+        ),
+      );
+    },
+  });
+
+  // ── Referral onboarding ──────────────────────────────────────────────
+
+  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 {
+          /* use fallback */
+        }
+        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,
+        );
+      }
+    },
+  });
+
+  // ── 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,30 @@
       },
       "apiUrl": {
         "type": "string"
+      },
+      "heartbeatPath": {
+        "type": "string"
+      },
+      "autoAcceptFriendRequests": {
+        "type": "boolean"
+      },
+      "autoReplyDms": {
+        "type": "boolean"
+      },
+      "autoPlayGames": {
+        "type": "boolean"
+      },
+      "maxBetPerGame": {
+        "type": "number"
+      },
+      "dailySpendLimit": {
+        "type": "number"
+      },
+      "autoJoinGlobalChat": {
+        "type": "boolean"
+      },
+      "autoPromoteReferrals": {
+        "type": "boolean"
       }
     },
     "required": []
@@ -29,6 +53,33 @@
     "apiUrl": {
       "label": "API URL",
       "placeholder": "https://api.dim.cool"
+    },
+    "heartbeatPath": {
+      "label": "Heartbeat file path",
+      "placeholder": "~/.openclaw/workspace/HEARTBEAT.md"
+    },
+    "autoAcceptFriendRequests": {
+      "label": "Auto-accept friend requests"
+    },
+    "autoReplyDms": {
+      "label": "Auto-reply to DMs"
+    },
+    "autoPlayGames": {
+      "label": "Auto-play games (join matchmaking)"
+    },
+    "maxBetPerGame": {
+      "label": "Max bet per game (USDC)",
+      "placeholder": "1.00"
+    },
+    "dailySpendLimit": {
+      "label": "Daily spend limit (USDC)",
+      "placeholder": "20.00"
+    },
+    "autoJoinGlobalChat": {
+      "label": "Auto-join global chat"
+    },
+    "autoPromoteReferrals": {
+      "label": "Auto-promote referral code"
     }
   },
   "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.18",
   "description": "OpenClaw plugin for DIM — play games, chat, send USDC, and earn on DIM using the SDK directly (no MCP subprocess).",
   "type": "module",
   "openclaw": {