crawd 0.8.0

package/src/lib/tts/tiktok.ts

@@ -0,0 +1,91 @@
+/**
+ * TikTok Text-to-Speech
+ * Vendored from https://github.com/Steve0929/tiktok-tts
+ * Converted to TypeScript/ESM with native fetch
+ */
+
+const DEFAULT_BASE_URL = 'https://api16-normal-v6.tiktokv.com/media/api/text/speech/invoke';
+const DEFAULT_VOICE = 'en_us_002'; // Jessie
+
+type TikTokTTSConfig = {
+  sessionId: string;
+  baseUrl?: string;
+};
+
+let config: TikTokTTSConfig | null = null;
+
+export function configureTikTokTTS(sessionId: string, baseUrl?: string): void {
+  config = { sessionId, baseUrl };
+}
+
+function prepareText(text: string): string {
+  return text
+    .replace(/\+/g, 'plus')
+    .replace(/\s/g, '+')
+    .replace(/&/g, 'and');
+}
+
+function handleStatusError(statusCode: number): never {
+  switch (statusCode) {
+    case 1:
+      throw new Error(`TikTok session id invalid or expired. status_code: ${statusCode}`);
+    case 2:
+      throw new Error(`Text is too long. status_code: ${statusCode}`);
+    case 4:
+      throw new Error(`Invalid speaker voice. status_code: ${statusCode}`);
+    case 5:
+      throw new Error(`No session id found. status_code: ${statusCode}`);
+    default:
+      throw new Error(`TikTok TTS error. status_code: ${statusCode}`);
+  }
+}
+
+type TikTokResponse = {
+  status_code: number;
+  data?: {
+    v_str?: string;
+  };
+};
+
+/**
+ * Generate TTS audio using TikTok's API
+ * @returns Base64-encoded MP3 audio data
+ */
+export async function generateTikTokTTS(
+  text: string,
+  voice: string = DEFAULT_VOICE
+): Promise<Buffer> {
+  if (!config) {
+    throw new Error('TikTok TTS not configured. Call configureTikTokTTS() first.');
+  }
+
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+  const reqText = prepareText(text);
+  const url = `${baseUrl}/?text_speaker=${voice}&req_text=${reqText}&speaker_map_type=0&aid=1233`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'User-Agent': 'com.zhiliaoapp.musically/2022600030 (Linux; U; Android 7.1.2; es_ES; SM-G988N; Build/NRD90M;tt-ok/3.12.13.1)',
+      'Cookie': `sessionid=${config.sessionId}`,
+      'Accept-Encoding': 'gzip,deflate,compress',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`TikTok TTS request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const result = (await response.json()) as TikTokResponse;
+
+  if (result.status_code !== 0) {
+    handleStatusError(result.status_code);
+  }
+
+  const encodedVoice = result.data?.v_str;
+  if (!encodedVoice) {
+    throw new Error('TikTok TTS returned no audio data');
+  }
+
+  return Buffer.from(encodedVoice, 'base64');
+}

package/src/plugin.ts

@@ -0,0 +1,280 @@
+/**
+ * OpenClaw plugin entry point for crawd.
+ *
+ * Registers:
+ * - `livestream_talk` tool (unprompted speech on stream)
+ * - `livestream_reply` tool (reply to a chat message)
+ * - `crawd` service (Fastify + Socket.IO backend)
+ */
+import { Type } from '@sinclair/typebox'
+import { CrawdBackend, type CrawdConfig, type TtsVoiceEntry } from './backend/server.js'
+
+// Minimal plugin types — the real types come from openclaw/plugin-sdk at runtime.
+// Defined inline so this package builds without the openclaw peerDep installed.
+type PluginLogger = {
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+}
+
+type PluginApi = {
+  pluginConfig?: Record<string, unknown>
+  logger: PluginLogger
+  registerTool: (tool: Record<string, unknown>, opts?: { name?: string }) => void
+  registerService: (service: { id: string; start: () => Promise<void>; stop?: () => Promise<void> }) => void
+}
+
+type PluginDefinition = {
+  id: string
+  name: string
+  description: string
+  configSchema?: Record<string, unknown>
+  register?: (api: PluginApi) => void | Promise<void>
+}
+
+// ---------------------------------------------------------------------------
+// Config parsing — transform pluginConfig → CrawdConfig
+// ---------------------------------------------------------------------------
+
+function parseTtsChain(raw: unknown): TtsVoiceEntry[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((e): e is { provider: string; voice: string } =>
+      e && typeof e === 'object' && typeof e.provider === 'string' && typeof e.voice === 'string',
+    )
+    .map((e) => ({
+      provider: e.provider as TtsVoiceEntry['provider'],
+      voice: e.voice,
+    }))
+}
+
+/** Resolve gateway WebSocket URL from env/defaults (same logic as OpenClaw's callGateway) */
+function resolveGatewayUrl(port?: number): string {
+  if (port) return `ws://127.0.0.1:${port}`
+  const portRaw = process.env.OPENCLAW_GATEWAY_PORT?.trim()
+  const resolved = portRaw ? parseInt(portRaw, 10) || 18789 : 18789
+  return `ws://127.0.0.1:${resolved}`
+}
+
+/**
+ * Read gateway auth + port from the OpenClaw host config.
+ * The real PluginApi has a `config: OpenClawConfig` property — our minimal
+ * inline type omits it so we access it via casting.
+ */
+function resolveGatewayFromHost(api: PluginApi): { token?: string; port?: number } {
+  const oclConfig = (api as Record<string, unknown>).config as Record<string, unknown> | undefined
+  if (!oclConfig) return {}
+  const gw = (oclConfig.gateway ?? {}) as Record<string, unknown>
+  const auth = (gw.auth ?? {}) as Record<string, unknown>
+  return {
+    token: typeof auth.token === 'string' ? auth.token : undefined,
+    port: typeof gw.port === 'number' ? gw.port : undefined,
+  }
+}
+
+function parsePluginConfig(raw: Record<string, unknown> | undefined): CrawdConfig {
+  const cfg = raw ?? {}
+  const tts = (cfg.tts ?? {}) as Record<string, unknown>
+  const vibe = (cfg.vibe ?? {}) as Record<string, unknown>
+  const chat = (cfg.chat ?? {}) as Record<string, unknown>
+  const youtube = (chat.youtube ?? {}) as Record<string, unknown>
+  const pumpfun = (chat.pumpfun ?? {}) as Record<string, unknown>
+
+  const port = typeof cfg.port === 'number' ? cfg.port : 4000
+
+  return {
+    enabled: cfg.enabled !== false,
+    port,
+    bindHost: typeof cfg.bindHost === 'string' ? cfg.bindHost : '0.0.0.0',
+    backendUrl: typeof cfg.backendUrl === 'string' ? cfg.backendUrl : `http://localhost:${port}`,
+    tts: {
+      chat: parseTtsChain(tts.chat),
+      bot: parseTtsChain(tts.bot),
+      openaiApiKey: typeof tts.openaiApiKey === 'string' ? tts.openaiApiKey : undefined,
+      elevenlabsApiKey: typeof tts.elevenlabsApiKey === 'string' ? tts.elevenlabsApiKey : undefined,
+      tiktokSessionId: typeof tts.tiktokSessionId === 'string' ? tts.tiktokSessionId : undefined,
+    },
+    vibe: {
+      enabled: vibe.enabled !== false,
+      intervalMs: typeof vibe.intervalMs === 'number' ? vibe.intervalMs : 10_000,
+      idleAfterMs: typeof vibe.idleAfterMs === 'number' ? vibe.idleAfterMs : 30_000,
+      sleepAfterIdleMs: typeof vibe.sleepAfterIdleMs === 'number' ? vibe.sleepAfterIdleMs : 60_000,
+      prompt: typeof vibe.prompt === 'string' ? vibe.prompt : undefined,
+    },
+    chat: {
+      youtube: {
+        enabled: youtube.enabled === true,
+        videoId: typeof youtube.videoId === 'string' ? youtube.videoId : undefined,
+      },
+      pumpfun: {
+        enabled: pumpfun.enabled !== false,
+        tokenMint: typeof pumpfun.tokenMint === 'string' ? pumpfun.tokenMint : undefined,
+        authToken: typeof pumpfun.authToken === 'string' ? pumpfun.authToken : undefined,
+      },
+    },
+    // Gateway: plugin config overrides, then env vars, then OpenClaw defaults
+    gatewayUrl: typeof cfg.gatewayUrl === 'string' ? cfg.gatewayUrl
+      : process.env.OPENCLAW_GATEWAY_URL ?? resolveGatewayUrl(),
+    gatewayToken: typeof cfg.gatewayToken === 'string' ? cfg.gatewayToken
+      : process.env.OPENCLAW_GATEWAY_TOKEN,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+
+const crawdConfigSchema = {
+  parse(value: unknown) {
+    const raw = value && typeof value === 'object' && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : {}
+    return parsePluginConfig(raw)
+  },
+  uiHints: {
+    enabled: { label: 'Enabled' },
+    port: { label: 'Backend Port', placeholder: '4000' },
+    bindHost: { label: 'Bind Host', placeholder: '0.0.0.0', advanced: true },
+    backendUrl: { label: 'Backend URL', advanced: true, help: 'Public URL for TTS file serving' },
+    'tts.chat': { label: 'Chat TTS Voices', help: 'Ordered fallback chain [{provider, voice}]' },
+    'tts.bot': { label: 'Bot TTS Voices', help: 'Ordered fallback chain [{provider, voice}]' },
+    'tts.openaiApiKey': { label: 'OpenAI API Key', sensitive: true },
+    'tts.elevenlabsApiKey': { label: 'ElevenLabs API Key', sensitive: true },
+    'tts.tiktokSessionId': { label: 'TikTok Session ID', sensitive: true },
+    'vibe.enabled': { label: 'Vibe Mode' },
+    'vibe.intervalMs': { label: 'Vibe Interval (ms)', advanced: true },
+    'vibe.idleAfterMs': { label: 'Idle After (ms)', advanced: true },
+    'vibe.sleepAfterIdleMs': { label: 'Sleep After Idle (ms)', advanced: true },
+    'vibe.prompt': { label: 'Vibe Prompt', advanced: true },
+    'chat.youtube.enabled': { label: 'YouTube Chat' },
+    'chat.youtube.videoId': { label: 'YouTube Video ID' },
+    'chat.pumpfun.enabled': { label: 'PumpFun Chat' },
+    'chat.pumpfun.tokenMint': { label: 'PumpFun Token Mint' },
+    'chat.pumpfun.authToken': { label: 'PumpFun Auth Token', sensitive: true },
+    gatewayUrl: { label: 'Gateway URL', advanced: true, help: 'Override auto-detected gateway URL (usually not needed)' },
+    gatewayToken: { label: 'Gateway Token', advanced: true, sensitive: true, help: 'Override OPENCLAW_GATEWAY_TOKEN env var' },
+  },
+}
+
+const plugin: PluginDefinition = {
+  id: 'crawd',
+  name: 'Crawd Livestream',
+  description: 'crawd.bot plugin — AI agent livestreaming with TTS, chat integration, and OBS overlay',
+  configSchema: crawdConfigSchema,
+
+  register(api: PluginApi) {
+    const config = parsePluginConfig(api.pluginConfig)
+    if (!config.enabled) {
+      api.logger.info('crawd: disabled')
+      return
+    }
+
+    // Resolve gateway auth from OpenClaw host config (token lives there, not in env)
+    const hostGw = resolveGatewayFromHost(api)
+    if (!config.gatewayToken && hostGw.token) {
+      config.gatewayToken = hostGw.token
+      api.logger.info('crawd: resolved gateway token from host config')
+    }
+    if (hostGw.port && !process.env.OPENCLAW_GATEWAY_PORT) {
+      config.gatewayUrl = resolveGatewayUrl(hostGw.port)
+    }
+
+    api.logger.info(`crawd: gateway url=${config.gatewayUrl}, token=${config.gatewayToken ? 'set' : '(none — gateway may not require auth in local mode)'}`)
+
+    let backend: CrawdBackend | null = null
+    let backendPromise: Promise<CrawdBackend> | null = null
+
+    const ensureBackend = async (): Promise<CrawdBackend> => {
+      if (backend) return backend
+      if (!backendPromise) {
+        backendPromise = (async () => {
+          const b = new CrawdBackend(config, {
+            info: (msg) => api.logger.info(`[crawd] ${msg}`),
+            warn: (msg) => api.logger.warn(`[crawd] ${msg}`),
+            error: (msg) => api.logger.error(`[crawd] ${msg}`),
+          })
+          await b.start()
+          return b
+        })()
+      }
+      backend = await backendPromise
+      return backend
+    }
+
+    // livestream_talk — unprompted speech on stream
+    api.registerTool(
+      {
+        name: 'livestream_talk',
+        label: 'Livestream Talk',
+        description:
+          'Speak on the livestream unprompted. Shows a speech bubble on the overlay and generates TTS audio. Use for narration, vibes, and commentary — NOT for replying to chat (use livestream_reply for that).',
+        parameters: Type.Object({
+          text: Type.String({ description: 'Message to speak on stream' }),
+        }),
+        async execute(_toolCallId: string, params: unknown) {
+          const b = await ensureBackend()
+          const { text } = params as { text: string }
+          const result = await b.handleTalk(text)
+          return {
+            content: [{ type: 'text', text: result.spoken ? `Spoke on stream: "${text}"` : 'Failed to speak' }],
+            details: result,
+          }
+        },
+      },
+      { name: 'livestream_talk' },
+    )
+
+    // livestream_reply — reply to a chat message
+    api.registerTool(
+      {
+        name: 'livestream_reply',
+        label: 'Livestream Reply',
+        description:
+          'Reply to a chat message on the livestream. Reads the original message aloud with the chat voice, then speaks your reply with the bot voice. Use this ONLY when responding to a specific viewer message.',
+        parameters: Type.Object({
+          text: Type.String({ description: 'Your reply to the chat message' }),
+          username: Type.String({ description: 'Username of the person you are replying to' }),
+          message: Type.String({ description: 'The original chat message you are replying to' }),
+        }),
+        async execute(_toolCallId: string, params: unknown) {
+          const b = await ensureBackend()
+          const { text, username, message } = params as { text: string; username: string; message: string }
+          const result = await b.handleReply(text, { username, message })
+          return {
+            content: [{ type: 'text', text: result.spoken ? `Replied to @${username}: "${text}"` : 'Failed to reply' }],
+            details: result,
+          }
+        },
+      },
+      { name: 'livestream_reply' },
+    )
+
+    // Service lifecycle
+    api.registerService({
+      id: 'crawd',
+      start: async () => {
+        try {
+          await ensureBackend()
+          api.logger.info('crawd: backend started')
+        } catch (err) {
+          api.logger.error(
+            `crawd: failed to start — ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+      },
+      stop: async () => {
+        if (backendPromise) {
+          try {
+            const b = await backendPromise
+            await b.stop()
+          } finally {
+            backendPromise = null
+            backend = null
+          }
+        }
+      },
+    })
+  },
+}
+
+export default plugin

package/src/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared types for the CrawdBot backend ↔ frontend (overlay) API.
+ *
+ * Install `@crawd/cli` and import:
+ *   import type { CrawdEvents, ReplyTurnEvent } from '@crawd/cli'
+ */
+
+// Re-export chat types used in events
+export type {
+  ChatMessage,
+  ChatPlatform,
+  ChatMessageMetadata,
+  SuperChatInfo,
+} from './lib/chat/types'
+
+/** TTS provider identifier */
+export type TtsProvider = 'openai' | 'elevenlabs' | 'tiktok'
+
+// --- Socket.IO event payloads ---
+
+/** Turn-based reply: chat message + bot response, each with TTS audio */
+export type ReplyTurnEvent = {
+  chat: { username: string; message: string }
+  botMessage: string
+  chatTtsUrl: string
+  botTtsUrl: string
+}
+
+/** Bot speech bubble with pre-generated TTS (atomic event) */
+export type TalkEvent = {
+  /** Correlation ID — overlay sends talk:done with this ID when audio finishes */
+  id: string
+  /** Bot reply text */
+  message: string
+  /** Bot TTS audio URL */
+  ttsUrl: string
+  /** Optional: chat message being replied to (overlay plays this first) */
+  chat?: {
+    message: string
+    username: string
+    ttsUrl: string
+  }
+}
+
+/** Overlay → backend acknowledgement that a talk finished playing */
+export type TalkDoneEvent = {
+  id: string
+}
+
+/** Overlay → backend mock chat message (for testing) */
+export type MockChatEvent = {
+  username: string
+  message: string
+}
+
+/** Incoming chat message from a platform */
+export type { ChatMessage as ChatEvent } from './lib/chat/types'
+
+/** Market cap update */
+export type McapEvent = {
+  mcap: number
+}
+
+/** Coordinator status change */
+export type StatusEvent = {
+  status: string
+}
+
+/** Map of all socket event names to their payload types */
+export type CrawdEvents = {
+  'crawd:reply-turn': ReplyTurnEvent
+  'crawd:talk': TalkEvent
+  'crawd:talk:done': TalkDoneEvent
+  'crawd:chat': import('./lib/chat/types').ChatMessage
+  'crawd:mock-chat': MockChatEvent
+  'crawd:mcap': McapEvent
+  'crawd:status': StatusEvent
+}

package/src/utils/logger.ts

@@ -0,0 +1,43 @@
+import chalk from 'chalk'
+
+export const log = {
+  info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
+  success: (msg: string) => console.log(chalk.green('✓'), msg),
+  warn: (msg: string) => console.log(chalk.yellow('⚠'), msg),
+  error: (msg: string) => console.log(chalk.red('✗'), msg),
+  dim: (msg: string) => console.log(chalk.dim(msg)),
+}
+
+export const fmt = {
+  url: (url: string) => chalk.cyan.underline(url),
+  path: (path: string) => chalk.yellow(path),
+  cmd: (cmd: string) => chalk.green(cmd),
+  bold: (s: string) => chalk.bold(s),
+  dim: (s: string) => chalk.dim(s),
+  success: (s: string) => chalk.green(s),
+}
+
+/** Print a labeled key-value pair */
+export function printKv(label: string, value: string, indent = 2) {
+  const padding = ' '.repeat(indent)
+  console.log(`${padding}${chalk.dim(label + ':')} ${value}`)
+}
+
+/** Print a section header */
+export function printHeader(title: string) {
+  console.log()
+  console.log(chalk.bold(title))
+}
+
+/** Print a status line with icon */
+export function printStatus(
+  label: string,
+  ok: boolean,
+  detail?: string,
+  indent = 2
+) {
+  const padding = ' '.repeat(indent)
+  const icon = ok ? chalk.green('✓') : chalk.red('✗')
+  const status = detail ? ` ${chalk.dim(`(${detail})`)}` : ''
+  console.log(`${padding}${icon} ${label}${status}`)
+}

package/src/utils/paths.ts

@@ -0,0 +1,55 @@
+import { homedir } from 'os'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+/** User data directory: ~/.crawd */
+export const CRAWD_HOME = join(homedir(), '.crawd')
+
+/** Config file path */
+export const CONFIG_PATH = join(CRAWD_HOME, 'config.json')
+
+/** Secrets file path */
+export const ENV_PATH = join(CRAWD_HOME, '.env')
+
+/** PID files directory */
+export const PIDS_DIR = join(CRAWD_HOME, 'pids')
+
+/** Logs directory */
+export const LOGS_DIR = join(CRAWD_HOME, 'logs')
+
+/** User-editable overlay source */
+export const OVERLAY_DIR = join(CRAWD_HOME, 'overlay')
+
+/** TTS audio cache */
+export const TTS_CACHE_DIR = join(CRAWD_HOME, 'tts')
+
+/** Backend source (in package) */
+export const BACKEND_TEMPLATE_DIR = join(__dirname, '../backend')
+
+/** User backend directory */
+export const BACKEND_DIR = join(CRAWD_HOME, 'backend')
+
+/** PID file paths */
+export const PID_FILES: Record<string, string> = {
+  backend: join(PIDS_DIR, 'backend.pid'),
+  overlay: join(PIDS_DIR, 'overlay.pid'),
+  crawdbot: join(PIDS_DIR, 'crawdbot.pid'),
+}
+
+/** Log file paths */
+export const LOG_FILES: Record<string, string> = {
+  backend: join(LOGS_DIR, 'backend.log'),
+  overlay: join(LOGS_DIR, 'overlay.log'),
+  crawdbot: join(LOGS_DIR, 'crawdbot.log'),
+}
+
+/** Default ports */
+export const DEFAULT_PORTS = {
+  backend: 4000,
+  overlay: 3000,
+  gateway: 18789,
+}