@yeego/yeego-openclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yeego Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,82 @@
+# Quick Start Guide
+
+## 🚀 Get Started in 3 Steps
+
+### Step 1: Get Your Configuration
+
+1. Open Yeego mobile app
+2. Go to your profile → Settings
+3. Tap "Connect to OpenClaw" 🦞
+4. Tap "Copy Configuration"
+
+You'll get something like:
+
+```
+# Yeego OpenClaw Plugin Configuration
+YEEGO_TOKEN=eyJhbG...
+YEEGO_PROFILE_ID=abc123...
+YEEGO_BASE_URL=http://localhost:8091
+YEEGO_PLUGIN_URL=http://localhost:8092/openclaw-plugin
+```
+
+### Step 2: Save Configuration
+
+```bash
+cd openclaw-plugin
+
+# Paste your config and save
+bun run setup "YEEGO_TOKEN=eyJhbG...
+YEEGO_PROFILE_ID=abc123...
+YEEGO_BASE_URL=http://localhost:8091"
+```
+
+✅ Configuration saved to `~/.yeego/config.json`
+
+### Step 3: Start Polling
+
+```bash
+bun run start
+```
+
+That's it! The plugin will:
+- ✅ Connect to your Yeego profile
+- ✅ Poll for new messages every 5 seconds  
+- ✅ Process them through OpenClaw
+- ✅ Send AI responses back to Yeego
+
+## 📱 Test It
+
+1. Open Yeego app
+2. Send a message to your AI persona
+3. Watch the poller process it
+4. See the AI response appear in the app
+
+## 🔧 Troubleshooting
+
+**No messages being processed?**
+- Make sure you sent a message in the Yeego app
+- Check the profile_id matches your actual profile
+
+**Connection errors?**
+- Verify backend is running (`http://localhost:8091`)
+- Check your token hasn't expired (30 days validity)
+
+**Want to reset?**
+```bash
+rm -rf ~/.yeego
+# Then run setup again
+```
+
+## 📦 Production Deployment
+
+When ready to deploy:
+
+```bash
+# Build standalone executable
+bun run build
+
+# Run it anywhere
+./yeego-poller start
+```
+
+No dependencies needed - it's a single binary! 🎉

package/README.md

@@ -0,0 +1,271 @@
+# Yeego OpenClaw Plugin
+
+OpenClaw channel plugin for integrating Yeego with OpenClaw AI agent.
+
+## Overview
+
+This plugin enables bidirectional communication between Yeego and OpenClaw:
+
+- **Inbound**: Listens to Yeego user messages via PocketBase realtime subscriptions
+- **Outbound**: Sends OpenClaw AI responses back to Yeego conversations
+- **Proactive**: Allows OpenClaw to initiate messages through cron jobs and tools
+
+## Architecture
+
+### Components
+
+1. **Channel Plugin** (`src/channel.ts`)
+   - Registers Yeego as an OpenClaw channel
+   - Handles outbound message sending via PocketBase
+   - Manages poller subprocess lifecycle
+   - Implements target resolution for conversation IDs
+
+2. **Realtime Listener** (`poller.ts`)
+   - Subscribes to PocketBase message events
+   - Processes incoming user messages
+   - Calls OpenClaw agent CLI
+   - Stores AI responses back to PocketBase
+   - Sets messageChannel metadata (workaround for CLI limitation)
+
+3. **Session Mapping** (`src/sessionMapping.ts`)
+   - Maintains persistent session ↔ conversation mapping
+   - File-based storage for cross-process sharing
+   - Enables proactive message targeting
+
+4. **Tools** (`src/tools/`)
+   - Profile management tools (create, list, get profiles)
+   - Target ID lookup for Yeego conversations
+
+## Key Implementation Details
+
+### Message Flow
+
+#### Inbound (User → OpenClaw)
+```
+User Message (Yeego App)
+  ↓
+PocketBase Realtime Event
+  ↓
+Poller (poller.ts)
+  ↓
+OpenClaw Agent CLI (--reply-channel yeego)
+  ↓
+AI Response → PocketBase
+  ↓
+Yeego App displays response
+```
+
+#### Outbound (OpenClaw → User)
+```
+OpenClaw wants to send message
+  ↓
+Resolves target via messaging.targetResolver.looksLikeId
+  ↓
+Calls outbound.sendText
+  ↓
+Creates message in PocketBase
+  ↓
+Yeego App displays message
+```
+
+### Critical Workarounds
+
+#### 1. messageChannel Metadata
+**Problem**: OpenClaw CLI's `--reply-channel` flag doesn't set the session's `messageChannel` property.
+
+**Solution**: `setSessionMessageChannel()` in `poller.ts` directly modifies the session JSONL file after creation to inject `messageChannel: "yeego"`.
+
+```typescript
+// Wait for session file creation, then patch it
+setTimeout(() => {
+  this.setSessionMessageChannel(conversation.id, 'yeego');
+}, 1000);
+```
+
+#### 2. Target Recognition
+**Problem**: OpenClaw's target resolver tries to look up conversation IDs in a directory, causing "Unknown target" errors.
+
+**Solution**: Implement `messaging.targetResolver.looksLikeId` to tell OpenClaw that our alphanumeric conversation IDs are valid IDs:
+
+```typescript
+messaging: {
+  targetResolver: {
+    looksLikeId: (_raw, normalized) => /^[a-z0-9]+$/i.test(normalized),
+  },
+}
+```
+
+This bypasses directory lookup entirely.
+
+#### 3. Cron Job Delivery
+
+**Important**: When using cron jobs or other isolated sessions to send messages to Yeego, you must specify both `channel` and `to` parameters in the payload:
+
+```javascript
+{
+  "deliver": true,
+  "channel": "yeego",
+  "to": "conversation_id_here"
+}
+```
+
+Unlike normal conversations where OpenClaw knows the origin context, cron jobs run in isolated sessions. The `channel` and `to` parameters tell OpenClaw where to deliver the message.
+
+**Example cron job configuration**:
+```json
+{
+  "id": "daily_reminder",
+  "enabled": true,
+  "schedule": "0 9 * * *",
+  "payload": {
+    "deliver": true,
+    "channel": "yeego",
+    "to": "lq45hgra9wpado5",
+    "message": "Good morning! Don't forget your daily tasks."
+  }
+}
+```
+
+Without these parameters, you'll get an error: "Cron delivery requires a recipient (--to)".
+
+## Installation
+
+### Quick Start (Recommended)
+
+1. Install the plugin:
+```bash
+openclaw plugins install @yeego/openclaw-plugin
+```
+
+2. Get your configuration from Yeego app:
+   - Open Yeego mobile app
+   - Go to Profile → Settings
+   - Tap "Connect to OpenClaw" 🦞
+   - Copy the configuration
+
+3. Add configuration to `~/.openclaw/openclaw.json`:
+```json
+{
+  "channels": {
+    "yeego": {
+      "config": {
+        "token": "your-token-here",
+        "profileId": "your-profile-id",
+        "baseUrl": "https://yeego.app",
+        "sidecarUrl": "https://yeego.app/_sidecar",
+        "connectUrl": "https://yeego.app/_sidecar/public/openclaw/connect"
+      }
+    }
+  }
+}
+```
+
+4. Restart OpenClaw gateway:
+```bash
+openclaw gateway restart
+```
+
+The plugin will automatically:
+- ✅ Enable the Yeego channel
+- ✅ Start the message poller process
+- ✅ Connect to your Yeego profile
+
+### Manual Installation (Development)
+
+For local development, contact the Yeego team for access to the plugin source code.
+
+### Configuration Files
+
+The plugin creates and manages these files automatically:
+- `~/.yeego/config.json` - Yeego credentials (auto-generated from OpenClaw config)
+- `~/.openclaw/yeego-sessions/session-mappings.json` - Session mappings
+- `~/.yeego/processed.json` - Processed message IDs (deduplication)
+
+## Development
+
+### File Structure
+
+```
+openclaw-plugin/
+├── index.ts                  # Plugin entry point
+├── poller.ts                 # Realtime listener (subprocess)
+├── src/
+│   ├── channel.ts            # Channel plugin implementation
+│   ├── sessionMapping.ts     # Session storage
+│   └── tools/
+│       ├── index.ts          # Tool factory
+│       ├── profileTools.ts   # Profile management
+│       └── pocketbase.ts     # PocketBase client wrapper
+├── package.json
+└── README.md
+```
+
+### Type Safety
+
+All code uses TypeScript with strict typing:
+- PocketBase record types
+- OpenClaw plugin SDK types
+- Explicit return types for all functions
+- No `any` types (except for globalThis polyfill)
+
+### Code Style
+
+- Clear section separators with `// ===` comments
+- Descriptive function and variable names
+- JSDoc comments for public APIs
+- Grouped related functions
+- Constants at top of file
+
+## Testing
+
+Send a message in Yeego app to test the integration. Check logs:
+
+```bash
+tail -f ~/.openclaw/logs/gateway.log | grep Yeego
+```
+
+Expected flow:
+1. `[Yeego] New message detected`
+2. `[Yeego] Processing message`
+3. `[Yeego] ✓ Set messageChannel="yeego"`
+4. `[Yeego] Message delivered`
+
+## Troubleshooting
+
+### "Unknown target" errors
+- Check that `messaging.targetResolver.looksLikeId` is implemented
+- Verify conversation ID format is alphanumeric
+
+### "Failed to connect to PocketBase"
+- Use `127.0.0.1` instead of `localhost` in config
+- Verify PocketBase is running: `curl http://127.0.0.1:8091/api/health`
+
+### Messages go to wrong channel
+- Check `~/.openclaw/agents/main/sessions/{sessionId}.jsonl`
+- First line should contain `"messageChannel": "yeego"`
+- If missing, poller's `setSessionMessageChannel()` may have failed
+
+### Poller not starting
+- Check gateway logs: `tail ~/.openclaw/logs/gateway.log`
+- Verify tsx is available: `which tsx`
+- Check poller config: `cat ~/.yeego/config.json`
+
+### "Cron delivery requires a recipient (--to)"
+This error occurs when a cron job or isolated session tries to send messages without specifying the delivery target.
+
+**Solution**: Add `channel` and `to` parameters to your cron job payload:
+```json
+{
+  "payload": {
+    "deliver": true,
+    "channel": "yeego",
+    "to": "conversation_id"
+  }
+}
+```
+
+See the "Cron Job Delivery" section under "Key Implementation Details" for more information.
+
+## License
+
+Part of the Yeego application.

package/index.ts

@@ -0,0 +1,334 @@
+/**
+ * Yeego OpenClaw Plugin Entry Point
+ *
+ * This plugin integrates Yeego with OpenClaw by:
+ * - Registering the Yeego channel for message sending/receiving
+ * - Providing tools for Yeego-specific operations (profile management, target lookup)
+ * - Auto-starting the yeego-poller process for message polling
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { yeegoPlugin } from "./src/channel.js";
+import { createYeegoTools } from "./src/tools/index.js";
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { spawn, ChildProcess } from 'child_process';
+import { fileURLToPath } from 'url';
+
+let pollerProcess: ChildProcess | null = null;
+let pollerRestartCount = 0;
+const MAX_RESTART_ATTEMPTS = 5;
+
+function ensureChannelConfig() {
+  try {
+    const configPath = join(homedir(), '.openclaw', 'openclaw.json');
+    if (!existsSync(configPath)) {
+      console.error(`[Yeego] Config file not found: ${configPath}`);
+      return;
+    }
+
+    const fullConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+    // Check if channels.yeego.config exists
+    if (!fullConfig?.channels?.yeego?.config) {
+      console.error(`[Yeego] No channel config found, skipping auto-enable`);
+      return;
+    }
+
+    let modified = false;
+
+    // Auto-enable the channel if not explicitly set
+    if (fullConfig.channels.yeego.enabled === undefined) {
+      fullConfig.channels.yeego.enabled = true;
+      modified = true;
+      console.error(`[Yeego] Auto-enabled channel`);
+    }
+
+    // Save if modified
+    if (modified) {
+      writeFileSync(configPath, JSON.stringify(fullConfig, null, 2), 'utf-8');
+      console.error(`[Yeego] Updated OpenClaw config with required settings`);
+    }
+  } catch (error) {
+    console.error(`[Yeego] Error ensuring channel config:`, error);
+  }
+}
+
+const plugin = {
+  id: "yeego",
+  name: "Yeego",
+  description: "Yeego chat channel integration for OpenClaw",
+
+  configSchema: {
+    type: "object" as const,
+    additionalProperties: false,
+    properties: {
+      token: {
+        type: "string" as const,
+        description: "Yeego authentication token",
+      },
+      profileId: {
+        type: "string" as const,
+        description: "Yeego profile ID",
+      },
+      baseUrl: {
+        type: "string" as const,
+        description: "Yeego base URL",
+      },
+      sidecarUrl: {
+        type: "string" as const,
+        description: "Yeego sidecar URL",
+      },
+      connectUrl: {
+        type: "string" as const,
+        description: "Yeego connect endpoint URL",
+      },
+    },
+    required: ["token", "profileId", "baseUrl", "sidecarUrl", "connectUrl"],
+  },
+
+  async register(api: OpenClawPluginApi) {
+    try {
+      // Ensure channel configuration is complete
+      ensureChannelConfig();
+
+      // Register channel plugin
+      api.registerChannel({ plugin: yeegoPlugin });
+      console.error(`[Yeego] Channel registered`);
+
+      // Register tool factory
+      api.registerTool((ctx) => {
+        console.error(`[Yeego] Creating tools for session: ${ctx.sessionKey}`);
+        const tools = createYeegoTools(ctx);
+        console.error(`[Yeego] Registered ${tools.length} tools: ${tools.map(t => t.name).join(", ")}`);
+        return tools;
+      });
+
+      console.error(`[Yeego] Plugin registration complete`);
+
+      // Call connect endpoint on startup
+      await callConnectEndpoint(api);
+
+      // Start the poller process
+      startPoller();
+    } catch (error) {
+      console.error(`[Yeego] Registration error:`, error);
+      throw error;
+    }
+  },
+};
+
+function getPluginDir(): string {
+  // Get the directory where this plugin is installed
+  // Try multiple methods to find the plugin directory
+  try {
+    // Method 1: Use import.meta.url (ESM)
+    const __filename = fileURLToPath(import.meta.url);
+    return dirname(__filename);
+  } catch {
+    // Method 2: Check common installation paths
+    const possiblePaths = [
+      join(homedir(), '.openclaw', 'plugins', '@yeego', 'yeego'),
+      join(homedir(), '.openclaw', 'plugins', '@yeego', 'openclaw-plugin'),
+    ];
+
+    for (const p of possiblePaths) {
+      if (existsSync(join(p, 'yeego-poller'))) {
+        return p;
+      }
+    }
+
+    // Fallback
+    return join(homedir(), '.openclaw', 'plugins', '@yeego', 'yeego');
+  }
+}
+
+function startPoller() {
+  try {
+    const pluginDir = getPluginDir();
+    const pollerPath = join(pluginDir, 'yeego-poller');
+
+    if (!existsSync(pollerPath)) {
+      console.error(`[Yeego] Poller binary not found at: ${pollerPath}`);
+      return;
+    }
+
+    // Check if poller is already running
+    if (pollerProcess && !pollerProcess.killed) {
+      console.error(`[Yeego] Poller is already running (pid: ${pollerProcess.pid})`);
+      return;
+    }
+
+    console.error(`[Yeego] Starting poller from: ${pollerPath}`);
+
+    pollerProcess = spawn(pollerPath, ['start'], {
+      detached: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    pollerProcess.stdout?.on('data', (data) => {
+      console.error(`[Yeego Poller] ${data.toString().trim()}`);
+    });
+
+    pollerProcess.stderr?.on('data', (data) => {
+      console.error(`[Yeego Poller] ${data.toString().trim()}`);
+    });
+
+    pollerProcess.on('error', (err) => {
+      console.error(`[Yeego] Failed to start poller:`, err);
+      pollerProcess = null;
+    });
+
+    pollerProcess.on('exit', (code, signal) => {
+      console.error(`[Yeego] Poller exited with code ${code}, signal ${signal}`);
+      pollerProcess = null;
+
+      // Auto-restart after 5 seconds if it crashed (with limit)
+      if (code !== 0 && code !== null) {
+        pollerRestartCount++;
+        if (pollerRestartCount <= MAX_RESTART_ATTEMPTS) {
+          const delay = Math.min(5000 * pollerRestartCount, 30000); // Exponential backoff, max 30s
+          console.error(`[Yeego] Poller crashed, restarting in ${delay}ms (attempt ${pollerRestartCount}/${MAX_RESTART_ATTEMPTS})...`);
+          setTimeout(() => startPoller(), delay);
+        } else {
+          console.error(`[Yeego] Poller crashed ${pollerRestartCount} times, giving up. Please check configuration.`);
+        }
+      } else {
+        // Normal exit, reset counter
+        pollerRestartCount = 0;
+      }
+    });
+
+    console.error(`[Yeego] Poller started (pid: ${pollerProcess.pid})`);
+
+    // Reset restart counter on successful start
+    setTimeout(() => {
+      if (pollerProcess && !pollerProcess.killed) {
+        pollerRestartCount = 0;
+        console.error(`[Yeego] Poller running stable, reset restart counter`);
+      }
+    }, 10000); // Consider stable if running for 10 seconds
+
+    // Cleanup on process exit
+    process.on('exit', () => {
+      if (pollerProcess && !pollerProcess.killed) {
+        console.error(`[Yeego] Stopping poller...`);
+        pollerProcess.kill('SIGTERM');
+      }
+    });
+
+    process.on('SIGINT', () => {
+      if (pollerProcess && !pollerProcess.killed) {
+        pollerProcess.kill('SIGTERM');
+      }
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', () => {
+      if (pollerProcess && !pollerProcess.killed) {
+        pollerProcess.kill('SIGTERM');
+      }
+      process.exit(0);
+    });
+
+  } catch (error) {
+    console.error(`[Yeego] Error starting poller:`, error);
+  }
+}
+
+function validateYeegoUrl(url: string, baseUrl: string): boolean {
+  try {
+    const parsed = new URL(url);
+    const baseParsed = new URL(baseUrl);
+
+    // Ensure URL and baseUrl have the same hostname
+    if (parsed.hostname !== baseParsed.hostname) {
+      console.error(`[Yeego] URL hostname mismatch: ${parsed.hostname} !== ${baseParsed.hostname}`);
+      return false;
+    }
+
+    // Ensure using https (except localhost)
+    if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost' && !parsed.hostname.endsWith('.localhost')) {
+      console.error(`[Yeego] Invalid protocol: ${parsed.protocol}, must use https`);
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    console.error(`[Yeego] Invalid URL:`, error);
+    return false;
+  }
+}
+
+async function callConnectEndpoint(api: OpenClawPluginApi) {
+    try {
+      // Read config directly from file instead of using api.getChannelConfig
+      // This is more reliable during the registration phase
+      const configPath = join(homedir(), '.openclaw', 'openclaw.json');
+      if (!existsSync(configPath)) {
+        console.error(`[Yeego] Config file not found: ${configPath}`);
+        return;
+      }
+
+      const fullConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const config = fullConfig?.channels?.yeego?.config;
+
+      if (!config || !config.connectUrl || !config.token || !config.profileId || !config.baseUrl) {
+        console.error(`[Yeego] Missing config for connect endpoint:`, {
+          hasConnectUrl: !!config?.connectUrl,
+          hasToken: !!config?.token,
+          hasProfileId: !!config?.profileId,
+          hasBaseUrl: !!config?.baseUrl,
+          configPath,
+        });
+        return;
+      }
+
+      // Validate connectUrl to prevent SSRF
+      if (!validateYeegoUrl(config.connectUrl, config.baseUrl)) {
+        console.error(`[Yeego] Invalid connectUrl: must match baseUrl domain`);
+        return;
+      }
+
+      console.error(`[Yeego] Calling connect endpoint`);
+
+      const response = await fetch(config.connectUrl, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${config.token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ profile_id: config.profileId }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`[Yeego] Connect endpoint failed: ${response.status} ${errorText}`);
+        return;
+      }
+
+      const result = await response.json();
+      console.error(`[Yeego] Successfully connected:`, result);
+
+      // Write config to ~/.yeego/config.json for poller (using underscore format)
+      const yeegoConfigDir = join(homedir(), '.yeego');
+      const yeegoConfigFile = join(yeegoConfigDir, 'config.json');
+
+      mkdirSync(yeegoConfigDir, { recursive: true });
+
+      const pollerConfig = {
+        token: config.token,
+        profile_id: config.profileId,
+        base_url: config.baseUrl,
+        sidecar_url: config.sidecarUrl,
+      };
+
+      writeFileSync(yeegoConfigFile, JSON.stringify(pollerConfig, null, 2), 'utf-8');
+      console.error(`[Yeego] Saved poller config to ${yeegoConfigFile}`);
+    } catch (error) {
+      console.error(`[Yeego] Error calling connect endpoint:`, error);
+    }
+}
+
+export default plugin;