@openparachute/agent 0.1.0

package/.claude/skills/x-integration/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: x-integration
+description: X (Twitter) integration for NanoClaw. Post tweets, like, reply, retweet, and quote. Use for setup, testing, or troubleshooting X functionality. Triggers on "setup x", "x integration", "twitter", "post tweet", "tweet".
+---
+
+# X (Twitter) Integration
+
+Browser automation for X interactions via WhatsApp.
+
+> **Compatibility:** NanoClaw v1.0.0. Directory structure may change in future versions.
+
+## Features
+
+| Action | Tool | Description |
+|--------|------|-------------|
+| Post | `x_post` | Publish new tweets |
+| Like | `x_like` | Like any tweet |
+| Reply | `x_reply` | Reply to tweets |
+| Retweet | `x_retweet` | Retweet without comment |
+| Quote | `x_quote` | Quote tweet with comment |
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **NanoClaw is installed and running** - WhatsApp connected, service active
+2. **Dependencies installed**:
+   ```bash
+   pnpm ls playwright dotenv-cli || pnpm install playwright dotenv-cli
+   ```
+3. **CHROME_PATH configured** in `.env` (if Chrome is not at default location):
+   ```bash
+   # Find your Chrome path
+   mdfind "kMDItemCFBundleIdentifier == 'com.google.Chrome'" 2>/dev/null | head -1
+   # Add to .env
+   CHROME_PATH=/path/to/Google Chrome.app/Contents/MacOS/Google Chrome
+   ```
+
+## Quick Start
+
+```bash
+# 1. Setup authentication (interactive)
+pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
+# Verify: data/x-auth.json should exist after successful login
+
+# 2. Rebuild container to include skill
+./container/build.sh
+# Verify: Output shows "COPY .claude/skills/x-integration/agent.ts"
+
+# 3. Rebuild host and restart service
+pnpm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+# Verify: launchctl list | grep nanoclaw (macOS) or systemctl --user status nanoclaw (Linux)
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CHROME_PATH` | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` | Chrome executable path |
+| `NANOCLAW_ROOT` | `process.cwd()` | Project root directory |
+| `LOG_LEVEL` | `info` | Logging level (debug, info, warn, error) |
+
+Set in `.env` file (loaded via `dotenv-cli` at runtime):
+
+```bash
+# .env
+CHROME_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
+```
+
+### Configuration File
+
+Edit `lib/config.ts` to modify defaults:
+
+```typescript
+export const config = {
+    // Browser viewport
+    viewport: { width: 1280, height: 800 },
+
+    // Timeouts (milliseconds)
+    timeouts: {
+        navigation: 30000,    // Page navigation
+        elementWait: 5000,    // Wait for element
+        afterClick: 1000,     // Delay after click
+        afterFill: 1000,      // Delay after form fill
+        afterSubmit: 3000,    // Delay after submit
+        pageLoad: 3000,       // Initial page load
+    },
+
+    // Tweet limits
+    limits: {
+        tweetMaxLength: 280,
+    },
+};
+```
+
+### Data Directories
+
+Paths relative to project root:
+
+| Path | Purpose | Git |
+|------|---------|-----|
+| `data/x-browser-profile/` | Chrome profile with X session | Ignored |
+| `data/x-auth.json` | Auth state marker | Ignored |
+| `logs/nanoclaw.log` | Service logs (contains X operation logs) | Ignored |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Container (Linux VM)                                       │
+│  └── agent.ts → MCP tool definitions (x_post, etc.)    │
+│      └── Writes IPC request to /workspace/ipc/tasks/       │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ IPC (file system)
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Host (macOS)                                               │
+│  └── src/ipc.ts → processTaskIpc()                         │
+│      └── host.ts → handleXIpc()                         │
+│          └── spawn subprocess → scripts/*.ts               │
+│              └── Playwright → Chrome → X Website           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Why This Design?
+
+- **API is expensive** - X official API requires paid subscription ($100+/month) for posting
+- **Bot browsers get blocked** - X detects and bans headless browsers and common automation fingerprints
+- **Must use user's real browser** - Reuses the user's actual Chrome on Host with real browser fingerprint to avoid detection
+- **One-time authorization** - User logs in manually once, session persists in Chrome profile for future use
+
+### File Structure
+
+```
+.claude/skills/x-integration/
+├── SKILL.md          # This documentation
+├── host.ts           # Host-side IPC handler
+├── agent.ts          # Container-side MCP tool definitions
+├── lib/
+│   ├── config.ts     # Centralized configuration
+│   └── browser.ts    # Playwright utilities
+└── scripts/
+    ├── setup.ts      # Interactive login
+    ├── post.ts       # Post tweet
+    ├── like.ts       # Like tweet
+    ├── reply.ts      # Reply to tweet
+    ├── retweet.ts    # Retweet
+    └── quote.ts      # Quote tweet
+```
+
+### Integration Points
+
+To integrate this skill into NanoClaw, make the following modifications:
+
+---
+
+**1. Host side: `src/ipc.ts`**
+
+Add import after other local imports:
+```typescript
+import { handleXIpc } from '../.claude/skills/x-integration/host.js';
+```
+
+Modify `processTaskIpc` function's switch statement default case:
+```typescript
+// Find:
+default:
+logger.warn({ type: data.type }, 'Unknown IPC task type');
+
+// Replace with:
+default:
+const handled = await handleXIpc(data, sourceGroup, isMain, DATA_DIR);
+if (!handled) {
+    logger.warn({ type: data.type }, 'Unknown IPC task type');
+}
+```
+
+---
+
+**2. Container side: `container/agent-runner/src/ipc-mcp.ts`**
+
+Add import after `cron-parser` import:
+```typescript
+// @ts-ignore - Copied during Docker build from .claude/skills/x-integration/
+import { createXTools } from './skills/x-integration/agent.js';
+```
+
+Add to the end of tools array (before the closing `]`):
+```typescript
+    ...createXTools({ groupFolder, isMain })
+```
+
+---
+
+**3. Build script: `container/build.sh`**
+
+Change build context from `container/` to project root (required to access `.claude/skills/`):
+```bash
+# Find:
+docker build -t "${IMAGE_NAME}:${TAG}" .
+
+# Replace with:
+cd "$SCRIPT_DIR/.."
+docker build -t "${IMAGE_NAME}:${TAG}" -f container/Dockerfile .
+```
+
+---
+
+**4. Dockerfile: `container/Dockerfile`**
+
+First, update the build context paths (required to access `.claude/skills/` from project root):
+```dockerfile
+# Find:
+COPY agent-runner/package*.json ./
+...
+COPY agent-runner/ ./
+
+# Replace with:
+COPY container/agent-runner/package*.json ./
+...
+COPY container/agent-runner/ ./
+```
+
+Then add COPY line after `COPY container/agent-runner/ ./` and before `RUN pnpm run build`:
+```dockerfile
+# Copy skill MCP tools
+COPY .claude/skills/x-integration/agent.ts ./src/skills/x-integration/
+```
+
+## Setup
+
+All paths below are relative to project root (`NANOCLAW_ROOT`).
+
+### 1. Check Chrome Path
+
+```bash
+# Check if Chrome exists at configured path
+cat .env | grep CHROME_PATH
+ls -la "$(grep CHROME_PATH .env | cut -d= -f2)" 2>/dev/null || \
+echo "Chrome not found - update CHROME_PATH in .env"
+```
+
+### 2. Run Authentication
+
+```bash
+pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
+```
+
+This opens Chrome for manual X login. Session saved to `data/x-browser-profile/`.
+
+**Verify success:**
+```bash
+cat data/x-auth.json  # Should show {"authenticated": true, ...}
+```
+
+### 3. Rebuild Container
+
+```bash
+./container/build.sh
+```
+
+**Verify success:**
+```bash
+./container/build.sh 2>&1 | grep -i "agent.ts"  # Should show COPY line
+```
+
+### 4. Restart Service
+
+```bash
+pnpm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+**Verify success:**
+```bash
+launchctl list | grep nanoclaw  # macOS — should show PID and exit code 0 or -
+# Linux: systemctl --user status nanoclaw
+```
+
+## Usage via WhatsApp
+
+Replace `@Assistant` with your configured trigger name (`ASSISTANT_NAME` in `.env`):
+
+```
+@Assistant post a tweet: Hello world!
+
+@Assistant like this tweet https://x.com/user/status/123
+
+@Assistant reply to https://x.com/user/status/123 with: Great post!
+
+@Assistant retweet https://x.com/user/status/123
+
+@Assistant quote https://x.com/user/status/123 with comment: Interesting
+```
+
+**Note:** Only the main group can use X tools. Other groups will receive an error.
+
+## Testing
+
+Scripts require environment variables from `.env`. Use `dotenv-cli` to load them:
+
+### Check Authentication Status
+
+```bash
+# Check if auth file exists and is valid
+cat data/x-auth.json 2>/dev/null && echo "Auth configured" || echo "Auth not configured"
+
+# Check if browser profile exists
+ls -la data/x-browser-profile/ 2>/dev/null | head -5
+```
+
+### Re-authenticate (if expired)
+
+```bash
+pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
+```
+
+### Test Post (will actually post)
+
+```bash
+echo '{"content":"Test tweet - please ignore"}' | pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/post.ts
+```
+
+### Test Like
+
+```bash
+echo '{"tweetUrl":"https://x.com/user/status/123"}' | pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/like.ts
+```
+
+Or export `CHROME_PATH` manually before running:
+
+```bash
+export CHROME_PATH="/path/to/chrome"
+echo '{"content":"Test"}' | pnpm exec tsx .claude/skills/x-integration/scripts/post.ts
+```
+
+## Troubleshooting
+
+### Authentication Expired
+
+```bash
+pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+### Browser Lock Files
+
+If Chrome fails to launch:
+
+```bash
+rm -f data/x-browser-profile/SingletonLock
+rm -f data/x-browser-profile/SingletonSocket
+rm -f data/x-browser-profile/SingletonCookie
+```
+
+### Check Logs
+
+```bash
+# Host logs (relative to project root)
+grep -i "x_post\|x_like\|x_reply\|handleXIpc" logs/nanoclaw.log | tail -20
+
+# Script errors
+grep -i "error\|failed" logs/nanoclaw.log | tail -20
+```
+
+### Script Timeout
+
+Default timeout is 2 minutes (120s). Increase in `host.ts`:
+
+```typescript
+const timer = setTimeout(() => {
+  proc.kill('SIGTERM');
+  resolve({ success: false, message: 'Script timed out (120s)' });
+}, 120000);  // ← Increase this value
+```
+
+### X UI Selector Changes
+
+If X updates their UI, selectors in scripts may break. Current selectors:
+
+| Element | Selector |
+|---------|----------|
+| Tweet input | `[data-testid="tweetTextarea_0"]` |
+| Post button | `[data-testid="tweetButtonInline"]` |
+| Reply button | `[data-testid="reply"]` |
+| Like | `[data-testid="like"]` |
+| Unlike | `[data-testid="unlike"]` |
+| Retweet | `[data-testid="retweet"]` |
+| Unretweet | `[data-testid="unretweet"]` |
+| Confirm retweet | `[data-testid="retweetConfirm"]` |
+| Modal dialog | `[role="dialog"][aria-modal="true"]` |
+| Modal submit | `[data-testid="tweetButton"]` |
+
+### Container Build Issues
+
+If MCP tools not found in container:
+
+```bash
+# Verify build copies skill
+./container/build.sh 2>&1 | grep -i skill
+
+# Check container has the file
+docker run nanoclaw-agent ls -la /app/src/skills/
+```
+
+## Security
+
+- `data/x-browser-profile/` - Contains X session cookies (in `.gitignore`)
+- `data/x-auth.json` - Auth state marker (in `.gitignore`)
+- Only main group can use X tools (enforced in `agent.ts` and `host.ts`)
+- Scripts run as subprocesses with limited environment

package/.claude/skills/x-integration/agent.ts

@@ -0,0 +1,243 @@
+/**
+ * X Integration - MCP Tool Definitions (Agent/Container Side)
+ *
+ * These tools run inside the container and communicate with the host via IPC.
+ * The host-side implementation is in host.ts.
+ *
+ * Note: This file is compiled in the container, not on the host.
+ * The @ts-ignore is needed because the SDK is only available in the container.
+ */
+
+// @ts-ignore - SDK available in container environment only
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+
+// IPC directories (inside container)
+const IPC_DIR = '/workspace/ipc';
+const TASKS_DIR = path.join(IPC_DIR, 'tasks');
+const RESULTS_DIR = path.join(IPC_DIR, 'x_results');
+
+function writeIpcFile(dir: string, data: object): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`;
+  const filepath = path.join(dir, filename);
+  const tempPath = `${filepath}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tempPath, filepath);
+  return filename;
+}
+
+async function waitForResult(requestId: string, maxWait = 60000): Promise<{ success: boolean; message: string }> {
+  const resultFile = path.join(RESULTS_DIR, `${requestId}.json`);
+  const pollInterval = 1000;
+  let elapsed = 0;
+
+  while (elapsed < maxWait) {
+    if (fs.existsSync(resultFile)) {
+      try {
+        const result = JSON.parse(fs.readFileSync(resultFile, 'utf-8'));
+        fs.unlinkSync(resultFile);
+        return result;
+      } catch (err) {
+        return { success: false, message: `Failed to read result: ${err}` };
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+    elapsed += pollInterval;
+  }
+
+  return { success: false, message: 'Request timed out' };
+}
+
+export interface SkillToolsContext {
+  groupFolder: string;
+  isMain: boolean;
+}
+
+/**
+ * Create X integration MCP tools
+ */
+export function createXTools(ctx: SkillToolsContext) {
+  const { groupFolder, isMain } = ctx;
+
+  return [
+    tool(
+      'x_post',
+      `Post a tweet to X (Twitter). Main group only.
+
+The host machine will execute the browser automation to post the tweet.
+Make sure the content is appropriate and within X's character limit (280 chars for text).`,
+      {
+        content: z.string().max(280).describe('The tweet content to post (max 280 characters)')
+      },
+      async (args: { content: string }) => {
+        if (!isMain) {
+          return {
+            content: [{ type: 'text', text: 'Only the main group can post tweets.' }],
+            isError: true
+          };
+        }
+
+        if (args.content.length > 280) {
+          return {
+            content: [{ type: 'text', text: `Tweet exceeds 280 character limit (current: ${args.content.length})` }],
+            isError: true
+          };
+        }
+
+        const requestId = `xpost-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeIpcFile(TASKS_DIR, {
+          type: 'x_post',
+          requestId,
+          content: args.content,
+          groupFolder,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await waitForResult(requestId);
+        return {
+          content: [{ type: 'text', text: result.message }],
+          isError: !result.success
+        };
+      }
+    ),
+
+    tool(
+      'x_like',
+      `Like a tweet on X (Twitter). Main group only.
+
+Provide the tweet URL or tweet ID to like.`,
+      {
+        tweet_url: z.string().describe('The tweet URL (e.g., https://x.com/user/status/123) or tweet ID')
+      },
+      async (args: { tweet_url: string }) => {
+        if (!isMain) {
+          return {
+            content: [{ type: 'text', text: 'Only the main group can interact with X.' }],
+            isError: true
+          };
+        }
+
+        const requestId = `xlike-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeIpcFile(TASKS_DIR, {
+          type: 'x_like',
+          requestId,
+          tweetUrl: args.tweet_url,
+          groupFolder,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await waitForResult(requestId);
+        return {
+          content: [{ type: 'text', text: result.message }],
+          isError: !result.success
+        };
+      }
+    ),
+
+    tool(
+      'x_reply',
+      `Reply to a tweet on X (Twitter). Main group only.
+
+Provide the tweet URL and your reply content.`,
+      {
+        tweet_url: z.string().describe('The tweet URL (e.g., https://x.com/user/status/123) or tweet ID'),
+        content: z.string().max(280).describe('The reply content (max 280 characters)')
+      },
+      async (args: { tweet_url: string; content: string }) => {
+        if (!isMain) {
+          return {
+            content: [{ type: 'text', text: 'Only the main group can interact with X.' }],
+            isError: true
+          };
+        }
+
+        const requestId = `xreply-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeIpcFile(TASKS_DIR, {
+          type: 'x_reply',
+          requestId,
+          tweetUrl: args.tweet_url,
+          content: args.content,
+          groupFolder,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await waitForResult(requestId);
+        return {
+          content: [{ type: 'text', text: result.message }],
+          isError: !result.success
+        };
+      }
+    ),
+
+    tool(
+      'x_retweet',
+      `Retweet a tweet on X (Twitter). Main group only.
+
+Provide the tweet URL to retweet.`,
+      {
+        tweet_url: z.string().describe('The tweet URL (e.g., https://x.com/user/status/123) or tweet ID')
+      },
+      async (args: { tweet_url: string }) => {
+        if (!isMain) {
+          return {
+            content: [{ type: 'text', text: 'Only the main group can interact with X.' }],
+            isError: true
+          };
+        }
+
+        const requestId = `xretweet-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeIpcFile(TASKS_DIR, {
+          type: 'x_retweet',
+          requestId,
+          tweetUrl: args.tweet_url,
+          groupFolder,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await waitForResult(requestId);
+        return {
+          content: [{ type: 'text', text: result.message }],
+          isError: !result.success
+        };
+      }
+    ),
+
+    tool(
+      'x_quote',
+      `Quote tweet on X (Twitter). Main group only.
+
+Retweet with your own comment added.`,
+      {
+        tweet_url: z.string().describe('The tweet URL (e.g., https://x.com/user/status/123) or tweet ID'),
+        comment: z.string().max(280).describe('Your comment for the quote tweet (max 280 characters)')
+      },
+      async (args: { tweet_url: string; comment: string }) => {
+        if (!isMain) {
+          return {
+            content: [{ type: 'text', text: 'Only the main group can interact with X.' }],
+            isError: true
+          };
+        }
+
+        const requestId = `xquote-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeIpcFile(TASKS_DIR, {
+          type: 'x_quote',
+          requestId,
+          tweetUrl: args.tweet_url,
+          comment: args.comment,
+          groupFolder,
+          timestamp: new Date().toISOString()
+        });
+
+        const result = await waitForResult(requestId);
+        return {
+          content: [{ type: 'text', text: result.message }],
+          isError: !result.success
+        };
+      }
+    )
+  ];
+}