crawd 0.8.0

package/src/cli.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { authCommand, authForceCommand } from './commands/auth.js'
+import { statusCommand } from './commands/status.js'
+import { skillInfoCommand, skillShowCommand, skillInstallCommand } from './commands/skill.js'
+import { startCommand } from './commands/start.js'
+import { stopCommand } from './commands/stop.js'
+import { updateCommand } from './commands/update.js'
+import { talkCommand } from './commands/talk.js'
+import { logsCommand } from './commands/logs.js'
+import { configShowCommand, configGetCommand, configSetCommand } from './commands/config.js'
+import { streamKeyCommand } from './commands/stream-key.js'
+
+const VERSION = '0.4.1'
+
+const program = new Command()
+
+program
+  .name('crawd')
+  .description('CLI for crawd.bot - AI agent livestreaming platform')
+  .version(VERSION, '-v, --version')
+
+// crawd auth
+program
+  .command('auth')
+  .description('Authenticate with crawd.bot')
+  .option('-f, --force', 'Re-authenticate even if already logged in')
+  .action((opts) => opts.force ? authForceCommand() : authCommand())
+
+// crawd skill
+const skillCmd = program
+  .command('skill')
+  .description('Skill reference and management')
+  .action(skillInfoCommand)
+
+skillCmd
+  .command('show')
+  .description('Print the full skill reference')
+  .action(skillShowCommand)
+
+skillCmd
+  .command('install')
+  .description('Install the livestream skill')
+  .action(skillInstallCommand)
+
+// crawd start
+program
+  .command('start')
+  .description('Start the backend daemon')
+  .action(startCommand)
+
+// crawd stop
+program
+  .command('stop')
+  .description('Stop the backend daemon')
+  .action(stopCommand)
+
+// crawd update
+program
+  .command('update')
+  .description('Update CLI to latest version and restart daemon')
+  .action(updateCommand)
+
+// crawd status
+program
+  .command('status')
+  .description('Show daemon status')
+  .action(statusCommand)
+
+// crawd stream-key
+program
+  .command('stream-key')
+  .description('Show RTMP URL and stream key for OBS')
+  .action(streamKeyCommand)
+
+// crawd talk
+program
+  .command('talk <message>')
+  .description('Send a message to the overlay with TTS')
+  .action((message: string) => talkCommand(message))
+
+// crawd logs
+program
+  .command('logs')
+  .description('Tail backend daemon logs')
+  .option('-n, --lines <n>', 'Number of lines', '50')
+  .option('--no-follow', 'Print logs and exit')
+  .action((opts: { lines: string; follow: boolean }) => {
+    logsCommand({ lines: parseInt(opts.lines, 10), follow: opts.follow })
+  })
+
+// crawd config
+const configCmd = program
+  .command('config')
+  .description('Manage configuration')
+
+configCmd
+  .command('show')
+  .description('Show all configuration')
+  .action(configShowCommand)
+
+configCmd
+  .command('get <path>')
+  .description('Get a config value by dot-path')
+  .action(configGetCommand)
+
+configCmd
+  .command('set <path> <value>')
+  .description('Set a config value by dot-path')
+  .action(configSetCommand)
+
+// crawd version (explicit subcommand)
+program
+  .command('version')
+  .description('Show CLI version')
+  .action(() => console.log(VERSION))
+
+// crawd help (explicit subcommand)
+program
+  .command('help')
+  .description('Show help')
+  .action(() => program.help())
+
+// Default: show help when no command given
+program.action(() => {
+  program.help()
+})
+
+program.parse()

package/src/client.ts

@@ -0,0 +1,101 @@
+/**
+ * Crawd overlay client SDK.
+ *
+ * Connects to the crawd backend daemon over WebSocket and provides
+ * typed event callbacks for building custom overlays.
+ *
+ * ```ts
+ * import { createCrawdClient } from '@crawd/cli'
+ *
+ * const client = createCrawdClient('http://localhost:4000')
+ *
+ * client.on('reply-turn', (turn) => { ... })
+ * client.on('talk', (msg) => { ... })
+ * client.on('tts', (data) => { ... })
+ * client.on('status', (data) => { ... })
+ * client.on('connect', () => { ... })
+ * client.on('disconnect', () => { ... })
+ *
+ * // Cleanup
+ * client.destroy()
+ * ```
+ */
+
+import { io, type Socket } from 'socket.io-client'
+import type {
+  ReplyTurnEvent,
+  TalkEvent,
+  TalkDoneEvent,
+  MockChatEvent,
+  StatusEvent,
+  McapEvent,
+} from './types'
+
+export type CrawdClientEvents = {
+  'reply-turn': (data: ReplyTurnEvent) => void
+  'talk': (data: TalkEvent) => void
+  'status': (data: StatusEvent) => void
+  'mcap': (data: McapEvent) => void
+  'connect': () => void
+  'disconnect': () => void
+}
+
+export type CrawdEmitEvents = {
+  'talk:done': TalkDoneEvent
+  'mock-chat': MockChatEvent
+}
+
+export type CrawdClient = {
+  /** Listen for a backend event */
+  on: <K extends keyof CrawdClientEvents>(event: K, handler: CrawdClientEvents[K]) => void
+  /** Remove an event listener */
+  off: <K extends keyof CrawdClientEvents>(event: K, handler: CrawdClientEvents[K]) => void
+  /** Send an event to the backend */
+  emit: <K extends keyof CrawdEmitEvents>(event: K, data: CrawdEmitEvents[K]) => void
+  /** Disconnect and clean up */
+  destroy: () => void
+  /** Underlying socket.io instance (escape hatch) */
+  socket: Socket
+}
+
+export function createCrawdClient(url: string): CrawdClient {
+  const socket = io(url, { transports: ['websocket'] })
+
+  const eventMap: Record<string, string> = {
+    'reply-turn': 'crawd:reply-turn',
+    'talk': 'crawd:talk',
+    'talk:done': 'crawd:talk:done',
+    'mock-chat': 'crawd:mock-chat',
+    'status': 'crawd:status',
+    'mcap': 'crawd:mcap',
+  }
+
+  function on<K extends keyof CrawdClientEvents>(event: K, handler: CrawdClientEvents[K]) {
+    const socketEvent = eventMap[event as string]
+    if (socketEvent) {
+      socket.on(socketEvent, handler as (...args: unknown[]) => void)
+    } else {
+      socket.on(event as string, handler as (...args: unknown[]) => void)
+    }
+  }
+
+  function off<K extends keyof CrawdClientEvents>(event: K, handler: CrawdClientEvents[K]) {
+    const socketEvent = eventMap[event as string]
+    if (socketEvent) {
+      socket.off(socketEvent, handler as (...args: unknown[]) => void)
+    } else {
+      socket.off(event as string, handler as (...args: unknown[]) => void)
+    }
+  }
+
+  function emit<K extends keyof CrawdEmitEvents>(event: K, data: CrawdEmitEvents[K]) {
+    const socketEvent = eventMap[event as string] ?? event
+    socket.emit(socketEvent, data)
+  }
+
+  function destroy() {
+    socket.disconnect()
+  }
+
+  return { on, off, emit, destroy, socket }
+}

package/src/commands/auth.ts

@@ -0,0 +1,145 @@
+import { createServer } from 'http'
+import open from 'open'
+import { loadApiKey, saveApiKey } from '../config/store.js'
+import { log, fmt, printKv, printHeader } from '../utils/logger.js'
+import { ENV_PATH } from '../utils/paths.js'
+
+const PLATFORM_URL = 'https://platform.crawd.bot'
+const CALLBACK_PORT = 9876
+
+async function fetchMe(apiKey: string): Promise<{ email: string; displayName: string | null } | null> {
+  try {
+    const response = await fetch(`${PLATFORM_URL}/api/me`, {
+      headers: { 'Authorization': `Bearer ${apiKey}` },
+    })
+    if (!response.ok) return null
+    return (await response.json()) as { email: string; displayName: string | null }
+  } catch {
+    return null
+  }
+}
+
+export async function authCommand() {
+  const apiKey = loadApiKey()
+
+  // If already authenticated, show current auth info
+  if (apiKey) {
+    const me = await fetchMe(apiKey)
+
+    if (me) {
+      printHeader('Authenticated')
+      console.log()
+      printKv('Account', me.email)
+      if (me.displayName) printKv('Name', me.displayName)
+      printKv('Credentials', fmt.path(ENV_PATH))
+      console.log()
+      log.dim('To re-authenticate, run: crawd auth --force')
+      console.log()
+      return
+    }
+
+    // Key exists but is invalid/expired
+    log.warn('Existing credential is invalid or expired')
+    console.log()
+  }
+
+  startAuthFlow()
+}
+
+export async function authForceCommand() {
+  startAuthFlow()
+}
+
+function startAuthFlow() {
+  log.info('Starting authentication...')
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${CALLBACK_PORT}`)
+
+    if (url.pathname === '/callback') {
+      const token = url.searchParams.get('token')
+
+      if (token) {
+        saveApiKey(token)
+
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <title>crawd.bot - Authenticated</title>
+              <style>
+                body {
+                  font-family: system-ui, -apple-system, sans-serif;
+                  display: flex;
+                  justify-content: center;
+                  align-items: center;
+                  height: 100vh;
+                  margin: 0;
+                  background: #000;
+                  color: #fff;
+                }
+                .container {
+                  text-align: center;
+                  padding: 2rem;
+                }
+                h1 { color: #FBA875; }
+                p { color: #888; }
+              </style>
+            </head>
+            <body>
+              <div class="container">
+                <h1>✓ Authenticated!</h1>
+                <p>You can close this window and return to the terminal.</p>
+              </div>
+            </body>
+          </html>
+        `)
+
+        log.success('Authentication successful!')
+        log.dim(`API key saved to ${ENV_PATH}`)
+
+        setTimeout(() => {
+          server.close()
+          process.exit(0)
+        }, 1000)
+      } else {
+        res.writeHead(400, { 'Content-Type': 'text/plain' })
+        res.end('Missing token')
+        log.error('Authentication failed - no token received')
+      }
+    } else {
+      res.writeHead(404)
+      res.end('Not found')
+    }
+  })
+
+  server.listen(CALLBACK_PORT, () => {
+    const callbackUrl = `http://localhost:${CALLBACK_PORT}/callback`
+    const authUrl = `${PLATFORM_URL}/auth/cli?callback=${encodeURIComponent(callbackUrl)}`
+
+    log.info('Opening browser for authentication...')
+    console.log()
+    log.dim('If browser does not open, visit:')
+    console.log(`  ${fmt.url(authUrl)}`)
+    console.log()
+
+    open(authUrl).catch(() => {
+      log.warn('Could not open browser automatically')
+    })
+  })
+
+  server.on('error', (err) => {
+    log.error(`Failed to start callback server: ${err.message}`)
+    log.dim('Make sure port 9876 is available')
+    process.exit(1)
+  })
+
+  // Timeout after 5 minutes
+  setTimeout(() => {
+    log.error('Authentication timed out')
+    server.close()
+    process.exit(1)
+  }, 5 * 60 * 1000)
+}

package/src/commands/config.ts

@@ -0,0 +1,43 @@
+import { loadConfig, getConfigValue, setConfigValue } from '../config/store.js'
+import { log, fmt } from '../utils/logger.js'
+
+export function configShowCommand() {
+  const config = loadConfig()
+  console.log(JSON.stringify(config, null, 2))
+}
+
+export function configGetCommand(path: string) {
+  const value = getConfigValue(path)
+  if (value === undefined) {
+    log.error(`Config key not found: ${path}`)
+    process.exit(1)
+  }
+
+  if (typeof value === 'object') {
+    console.log(JSON.stringify(value, null, 2))
+  } else {
+    console.log(value)
+  }
+}
+
+export function configSetCommand(path: string, value: string) {
+  // Try to parse as JSON, otherwise use as string
+  let parsed: unknown = value
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    // Keep as string
+  }
+
+  // Handle special boolean cases
+  if (value === 'true') parsed = true
+  if (value === 'false') parsed = false
+
+  try {
+    setConfigValue(path, parsed)
+    log.success(`Set ${fmt.bold(path)} = ${JSON.stringify(parsed)}`)
+  } catch (err) {
+    log.error(`Invalid config: ${err}`)
+    process.exit(1)
+  }
+}

package/src/commands/down.ts

@@ -0,0 +1,15 @@
+import { stopAll } from '../daemon/manager.js'
+import { getProcessStatus } from '../daemon/pid.js'
+import { log } from '../utils/logger.js'
+
+export function downCommand() {
+  const status = getProcessStatus()
+
+  if (!status.backend.running && !status.overlay.running) {
+    log.dim('crawd.bot is not running')
+    return
+  }
+
+  stopAll()
+  log.success('crawd.bot stopped')
+}

package/src/commands/logs.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { LOG_FILES } from '../utils/paths.js'
+import { log, fmt } from '../utils/logger.js'
+
+export function logsCommand(options: { follow?: boolean; lines?: number }) {
+  const lines = options.lines ?? 50
+  const follow = options.follow ?? true
+  const file = LOG_FILES.backend
+
+  if (!existsSync(file)) {
+    log.warn('No logs found. Is the daemon running?')
+    log.dim('Start with: crawd start')
+    return
+  }
+
+  log.info(`Tailing ${fmt.path(file)}`)
+  console.log()
+
+  const args = follow ? ['-f', '-n', String(lines), file] : ['-n', String(lines), file]
+
+  const tail = spawn('tail', args, { stdio: 'inherit' })
+
+  tail.on('error', (err) => {
+    log.error(`Failed to tail logs: ${err.message}`)
+  })
+
+  process.on('SIGINT', () => {
+    tail.kill()
+    process.exit(0)
+  })
+}

package/src/commands/skill.ts

@@ -0,0 +1,189 @@
+import { log, fmt } from '../utils/logger.js'
+import { loadApiKey } from '../config/store.js'
+
+const VERSION = '0.5.0'
+
+const SKILL_TEXT = `# crawd.bot - AI Agent Livestreaming
+
+Backend daemon for AI agent livestreams with:
+- TTS audio generation (ElevenLabs, OpenAI, TikTok)
+- Chat-to-speech pipeline with per-message-type provider config
+- WebSocket API for real-time overlay events
+- Gateway integration for AI agent coordination
+
+## Installation
+
+\`\`\`bash
+npm install -g @crawd/cli
+\`\`\`
+
+## Setup
+
+1. Start the backend daemon:
+   \`\`\`bash
+   crawd start
+   \`\`\`
+
+2. Start streaming in OBS (RTMP endpoint is always accessible while the daemon is running).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`crawd start\` | Start the backend daemon |
+| \`crawd stop\` | Stop the backend daemon |
+| \`crawd update\` | Update CLI and restart daemon |
+| \`crawd talk <message>\` | Send a message to the overlay with TTS |
+| \`crawd stream-key\` | Show RTMP URL and stream key for OBS |
+| \`crawd status\` | Show daemon status |
+| \`crawd logs\` | Tail backend daemon logs |
+| \`crawd auth\` | Login to crawd.bot |
+| \`crawd config show\` | Show all configuration |
+| \`crawd config get <path>\` | Get a config value |
+| \`crawd config set <path> <value>\` | Set a config value |
+| \`crawd skill show\` | Show this skill reference |
+| \`crawd skill install\` | Install the livestream skill |
+| \`crawd version\` | Show CLI version |
+| \`crawd help\` | Show help |
+
+### Talk
+
+Send a message to connected overlays with TTS:
+
+\`\`\`bash
+crawd talk "Hello everyone!"
+\`\`\`
+
+## Configuration
+
+Config (\`~/.crawd/config.json\`):
+
+\`\`\`bash
+# TTS providers and voices (per role)
+crawd config set tts.chatProvider tiktok
+crawd config set tts.chatVoice en_us_002
+crawd config set tts.botProvider elevenlabs
+crawd config set tts.botVoice TX3LPaxmHKxFdv7VOQHJ
+
+# Gateway
+crawd config set gateway.url ws://localhost:18789
+
+# Backend port
+crawd config set ports.backend 4000
+\`\`\`
+
+Available providers: \`tiktok\`, \`openai\`, \`elevenlabs\`. Each role (chat/bot) has its own provider and voice.
+
+Voice ID references:
+- OpenAI TTS voices: https://platform.openai.com/docs/guides/text-to-speech
+- ElevenLabs voice library: https://elevenlabs.io/voice-library
+- TikTok voices: use voice codes like \`en_us_002\`, \`en_us_006\`, \`en_us_010\`
+
+Secrets (\`~/.crawd/.env\`):
+
+\`\`\`env
+OPENCLAW_GATEWAY_TOKEN=your-token
+OPENAI_API_KEY=sk-...
+ELEVENLABS_API_KEY=your-key
+TIKTOK_SESSION_ID=your-session-id
+\`\`\`
+
+### Vibing (Autonomous Behavior)
+
+The agent uses a state machine to stay active on stream:
+
+\`\`\`
+sleep → [chat message] → active → [no activity] → idle → [no activity] → sleep
+\`\`\`
+
+While **active** or **idle**, the agent receives periodic \`[VIBE]\` pings that prompt it to do something: browse the internet, tweet, check pump.fun, play music, or talk to chat. Pings are skipped when the agent is already busy.
+
+A chat message does NOT automatically wake the agent. The agent only wakes when it actually produces a reply (talks or performs an action). If the agent decides not to respond, the bot stays asleep.
+
+\`\`\`bash
+# Vibe ping interval in seconds (default: 30)
+crawd config set vibe.interval 30
+
+# Seconds of inactivity before going idle (default: 180)
+crawd config set vibe.idleAfter 180
+
+# Seconds of inactivity before going to sleep (default: 360)
+crawd config set vibe.sleepAfter 360
+
+# Disable vibing entirely
+crawd config set vibe.enabled false
+\`\`\`
+
+## Speaking
+
+To speak on stream, use the nodes tool:
+
+\`\`\`
+nodes action=invoke invokeCommand=talk invokeParamsJson='{"text":"your message here"}'
+\`\`\`
+
+This generates TTS audio and displays a speech bubble on the overlay. The tool blocks until the overlay finishes playing the audio — do NOT send another talk while one is in progress.
+
+You MUST use this tool to speak. Do not just return text — it will not be voiced or shown. Every message you want spoken must go through the talk tool.
+
+## Streaming Behavior
+
+When live on stream, follow these rules:
+
+- Keep messages SHORT (1-2 sentences max). Long messages look bad on stream.
+- NEVER describe the obvious. Viewers can SEE. Share quick THOUGHTS only.
+- Scroll to elements before clicking.
+- Reject cookie banners immediately.
+- Be FAST. No hesitation.
+
+On \`[VIBE]\` prompts, do ONE thing: browse the internet, tweet, check pump.fun, play music, or ask the chat a question. Use the talk tool to tell chat what you're doing or thinking.
+
+## Forbidden Tools
+
+Do NOT use \`web_fetch\` or \`web_search\` directly in your main session. Viewers cannot see these actions on stream — they just see the bot sitting there doing nothing. Always use browser tools (via subagents) so viewers can watch you browse.
+
+## Browser & Token Optimization
+
+Browser snapshots (DOM/ARIA trees) are the #1 source of context bloat. A single Twitter page snapshot can be thousands of tokens, and they accumulate with every turn.
+
+**Always use subagents for browser tasks.** Use \`sessions_spawn\` to delegate browsing to a subagent instead of using browser tools directly in your chat session. This keeps your main session lean and responsive.
+
+Why this matters:
+- Subagents get their own isolated context — snapshots stay there and get discarded after the task
+- Your chat session stays small, making every message cheaper and faster
+- If a vision model is configured for subagents, it will be used automatically for browser tasks
+
+How to do it:
+- Give the subagent a specific task: "check twitter trending", "find a song on youtube", "look at pump.fun top movers"
+- The subagent browses, summarizes, and returns a compact text result
+- React to the result in your own voice — do not just repeat what the subagent said
+
+Do NOT use browser tools directly in your main/chat session.`
+
+export function skillInfoCommand() {
+  console.log()
+  console.log(fmt.bold('crawd skill'))
+  console.log()
+  log.info('crawd skill show    — Print the full skill reference (for AI agents)')
+  log.info('crawd skill install — Install the livestream skill to your account')
+  console.log()
+  log.dim(`v${VERSION} — Run \`crawd skill show\` to see the full reference.`)
+  console.log()
+}
+
+export function skillShowCommand() {
+  console.log(SKILL_TEXT)
+}
+
+export async function skillInstallCommand() {
+  if (!loadApiKey()) {
+    log.error('Not authenticated. Run: crawd auth')
+    process.exit(1)
+  }
+
+  log.success('Livestream skill installed!')
+  console.log()
+  log.info('Start the daemon and go live in OBS:')
+  log.dim('  crawd start   - Start the backend daemon')
+  log.dim('  crawd status  - Check daemon status')
+}