@openparachute/agent 0.1.2 → 0.2.0

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

@@ -1,417 +0,0 @@
----
-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

@@ -1,243 +0,0 @@
-/**
- * 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
-        };
-      }
-    )
-  ];
-}