@yeego/yeego-openclaw 1.0.3 → 1.3.0

package/QUICKSTART.md

@@ -1,82 +1,152 @@
-# Quick Start Guide
+# Yeego OpenClaw Plugin - Quick Start Guide
 
-## 🚀 Get Started in 3 Steps
+Get your Yeego personas talking to OpenClaw in 5 minutes.
 
-### Step 1: Get Your Configuration
+## Prerequisites
 
-1. Open Yeego mobile app
-2. Go to your profile → Settings
-3. Tap "Connect to OpenClaw" 🦞
-4. Tap "Copy Configuration"
+- ✅ OpenClaw installed
+- ✅ Yeego account
+- ✅ Node.js 18+
 
-You'll get something like:
+## Step-by-Step Installation
+
+### 1. Install the Plugin
 
+```bash
+npm install @yeego/yeego-openclaw
 ```
-# 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
+
+### 2. Get Your Yeego Configuration
+
+**In the Yeego mobile app:**
+
+1. Open **Settings**
+2. Tap **OpenClaw Integration**
+3. Tap **"Connect to OpenClaw"**
+4. Copy the configuration JSON
+
+You'll get something like:
+
+```json
+{
+  "token": "eyJhbGc...",
+  "profileId": "124p201f8050l93",
+  "baseUrl": "https://staging.yeego.app",
+  "sidecarUrl": "https://staging.yeego.app/_sidecar",
+  "connectUrl": "https://staging.yeego.app/_sidecar/public/openclaw/connect"
+}
 ```
 
-### Step 2: Save Configuration
+### 3. Configure OpenClaw
+
+Edit `~/.openclaw/openclaw.json`:
 
 ```bash
-cd openclaw-plugin
+# Open the config file
+nano ~/.openclaw/openclaw.json
+```
 
-# Paste your config and save
-bun run setup "YEEGO_TOKEN=eyJhbG...
-YEEGO_PROFILE_ID=abc123...
-YEEGO_BASE_URL=http://localhost:8091"
+Add this configuration (replace with your values from step 2):
+
+```json
+{
+  "channels": {
+    "yeego": {
+      "enabled": true,
+      "config": {
+        "token": "your-token-here",
+        "profileId": "your-profile-id",
+        "baseUrl": "https://staging.yeego.app",
+        "sidecarUrl": "https://staging.yeego.app/_sidecar",
+        "connectUrl": "https://staging.yeego.app/_sidecar/public/openclaw/connect"
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "yeego": {
+        "enabled": true
+      }
+    }
+  }
+}
 ```
 
-✅ Configuration saved to `~/.yeego/config.json`
+**Important**: Make sure to add commas if you have other channels/plugins configured!
 
-### Step 3: Start Polling
+### 4. Restart OpenClaw Gateway
 
 ```bash
-bun run start
+openclaw gateway restart
 ```
 
-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
+### 5. 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
+2. Go to your persona's chat
+3. Send a message: "Hello!"
+4. Wait a few seconds for the AI response
 
-## 🔧 Troubleshooting
+## Verification
 
-**No messages being processed?**
-- Make sure you sent a message in the Yeego app
-- Check the profile_id matches your actual profile
+Check if everything is working:
 
-**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
+# Check gateway logs
+tail -f ~/.openclaw/logs/gateway.log | grep yeego
+
+# You should see:
+# [yeego] Starting polling channel for account: default
+# [yeego] Starting message monitor...
 ```
 
-## 📦 Production Deployment
+## Common Issues
 
-When ready to deploy:
+### "No channel config found"
 
-```bash
-# Build standalone executable
-bun run build
+**Problem**: Configuration not found in openclaw.json
 
-# Run it anywhere
-./yeego-poller start
-```
+**Solution**: 
+1. Verify the JSON structure matches the example above
+2. Ensure `channels.yeego.config` exists
+3. Run `openclaw doctor --fix`
+
+### "Messages not reaching OpenClaw"
+
+**Problem**: Plugin not enabled or token expired
+
+**Solution**:
+1. Check `plugins.entries.yeego.enabled: true`
+2. Get a fresh token from Yeego app
+3. Restart gateway: `openclaw gateway restart`
+
+### "Token expired" errors
+
+**Problem**: Yeego token has expired
+
+**Solution**:
+1. Go to Yeego app → Settings → OpenClaw
+2. Tap "Refresh Token"
+3. Update the token in openclaw.json
+4. Restart gateway
+
+## Next Steps
 
-No dependencies needed - it's a single binary! 🎉
+- 📖 Read the [full documentation](README.md)
+- 🛠️ Explore [available tools](README.md#available-tools)
+- 💬 Join our [community](https://discord.gg/yeego)
+
+## Getting Help
+
+If you're stuck:
+
+1. Check logs: `tail -f ~/.openclaw/logs/gateway.log`
+2. Run diagnostics: `openclaw doctor`
+3. [Open an issue](https://github.com/yeego/yeego-openclaw/issues)
+
+---
+
+**Pro Tip**: Enable debug logging for more details:
+```bash
+DEBUG=yeego:* openclaw gateway restart
+```

package/README.md

@@ -1,274 +1,128 @@
 # Yeego OpenClaw Plugin
 
-OpenClaw channel plugin for integrating Yeego with OpenClaw AI agent.
+Connect your OpenClaw AI agent to [Yeego](https://yeego.app) messaging platform for seamless AI-powered conversations.
 
-## Overview
+## Features
 
-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)".
+- 🔄 **Bidirectional messaging** - Receive messages from Yeego users and send AI responses back
+- 🔌 **Native integration** - Built specifically for OpenClaw's plugin architecture  
+- 📦 **PocketBase powered** - Uses Yeego's PocketBase backend for reliable message delivery
+- 🛠️ **Rich tools** - Access Yeego profile data and conversation management from your AI
+- 🎯 **Session persistence** - Maintains conversation context across interactions
 
 ## Installation
 
-### Quick Start (Recommended)
-
-1. Install the plugin:
 ```bash
-openclaw plugins install @yeego/yeego-openclaw
+npm install @yeego/yeego-openclaw
 ```
 
-2. Get your configuration from Yeego app:
-   - Open Yeego mobile app
-   - Go to Profile → Settings
-   - Tap "Connect to OpenClaw" 🦞
-   - Copy the configuration
+## Quick Start
+
+### 1. Get Yeego Credentials
 
-3. Add configuration to `~/.openclaw/openclaw.json`:
+In the Yeego app:
+1. Go to **Settings** → **OpenClaw Integration**
+2. Click **"Connect to OpenClaw"**
+3. Copy the configuration
 
-   **IMPORTANT:** Configuration must be placed under `channels.yeego.config`, NOT under `plugins.entries`.
+### 2. Configure OpenClaw
+
+Add to `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "channels": {
     "yeego": {
+      "enabled": true,
       "config": {
-        "token": "your-token-here",
+        "token": "your-yeego-token",
         "profileId": "your-profile-id",
-        "baseUrl": "https://yeego.app",
-        "sidecarUrl": "https://yeego.app/_sidecar",
-        "connectUrl": "https://yeego.app/_sidecar/public/openclaw/connect"
+        "baseUrl": "https://staging.yeego.app",
+        "sidecarUrl": "https://staging.yeego.app/_sidecar",
+        "connectUrl": "https://staging.yeego.app/_sidecar/public/openclaw/connect"
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "yeego": {
+        "enabled": true
       }
     }
   }
 }
 ```
 
-4. Restart OpenClaw gateway:
+### 3. Restart OpenClaw
+
 ```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
+That's it! Send a message in Yeego to test.
 
-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
+## How It Works
 
 ```
-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
+Yeego App → PocketBase → Monitor → OpenClaw Agent
+     ↑                                    ↓
+     └────────────────────────────────────┘
+              Response delivered back
 ```
 
-### Type Safety
+The plugin polls PocketBase every 5 seconds for new messages, routes them to your OpenClaw agent, and delivers responses back to Yeego.
 
-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)
+## Available Tools
 
-### Code Style
+Your agent can use these Yeego-specific tools:
 
-- Clear section separators with `// ===` comments
-- Descriptive function and variable names
-- JSDoc comments for public APIs
-- Grouped related functions
-- Constants at top of file
+- `get_yeego_target_id` - Resolve conversation IDs
+- `view_user_profile_data` - Access profile information
+- `view_full_profile` - View complete profile
+- `update_profile_field` - Modify profile fields
 
-## Testing
+## Troubleshooting
 
-Send a message in Yeego app to test the integration. Check logs:
+### Messages not reaching OpenClaw
 
-```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`
+1. Verify configuration in `~/.openclaw/openclaw.json`
+2. Check `plugins.entries.yeego.enabled: true`
+3. Restart gateway: `openclaw gateway restart`
+4. Check logs: `tail -f ~/.openclaw/logs/gateway.log | grep yeego`
 
-## Troubleshooting
+### Agent not responding
 
-### "Unknown target" errors
-- Check that `messaging.targetResolver.looksLikeId` is implemented
-- Verify conversation ID format is alphanumeric
+1. Check for errors: `tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep yeego`
+2. Verify PocketBase connection (check baseUrl)
+3. Ensure token is valid and not expired
 
-### "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`
+## Development
 
-### 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
+```bash
+# Clone repository
+git clone https://github.com/yeego/yeego-openclaw
+cd yeego-openclaw
 
-### Poller not starting
-- Check gateway logs: `tail ~/.openclaw/logs/gateway.log`
-- Verify tsx is available: `which tsx`
-- Check poller config: `cat ~/.yeego/config.json`
+# Install dependencies
+npm install
 
-### "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.
+# Link for local development  
+npm link
 
-**Solution**: Add `channel` and `to` parameters to your cron job payload:
-```json
-{
-  "payload": {
-    "deliver": true,
-    "channel": "yeego",
-    "to": "conversation_id"
-  }
-}
+# Install in OpenClaw
+openclaw plugin install @yeego/yeego-openclaw
 ```
 
-See the "Cron Job Delivery" section under "Key Implementation Details" for more information.
+## Support
+
+- **Documentation**: [https://docs.yeego.app](https://docs.yeego.app)
+- **Issues**: [GitHub Issues](https://github.com/yeego/yeego-openclaw/issues)
+- **Yeego App**: [https://yeego.app](https://yeego.app)
 
 ## License
 
-Part of the Yeego application.
+MIT License - see [LICENSE](LICENSE) file
+
+---
+
+Made with ❤️ by the Yeego Team