crawd 0.8.7 → 0.9.0

package/dist/types.d.ts

@@ -27,40 +27,22 @@ type ChatMessage = {
     metadata?: ChatMessageMetadata;
 };
 
-/** TTS provider identifier */
-type TtsProvider = 'openai' | 'elevenlabs' | 'tiktok';
-/** Turn-based reply: chat message + bot response, each with TTS audio */
+/** Turn-based reply: chat message + bot response (text only, TTS handled by overlay) */
 type ReplyTurnEvent = {
-    /** Correlation ID — overlay sends talk:done with this ID when both audios finish */
+    /** Correlation ID — overlay sends talk:done with this ID when finished */
     id: string;
     chat: {
         username: string;
         message: string;
     };
     botMessage: string;
-    chatTtsUrl: string;
-    botTtsUrl: string;
-    /** TTS provider used for the chat audio */
-    chatTtsProvider?: TtsProvider;
-    /** TTS provider used for the bot audio */
-    botTtsProvider?: TtsProvider;
 };
-/** Bot speech bubble with pre-generated TTS (atomic event) */
+/** Bot speech bubble (text only, TTS handled by overlay) */
 type TalkEvent = {
-    /** Correlation ID — overlay sends talk:done with this ID when audio finishes */
+    /** Correlation ID — overlay sends talk:done with this ID when finished */
     id: string;
     /** Bot reply text */
     message: string;
-    /** Bot TTS audio URL */
-    ttsUrl: string;
-    /** TTS provider used for the bot audio */
-    ttsProvider?: TtsProvider;
-    /** 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 */
 type TalkDoneEvent = {
@@ -91,4 +73,4 @@ type CrawdEvents = {
     'crawd:status': StatusEvent;
 };
 
-export type { ChatMessage as ChatEvent, ChatMessage, ChatMessageMetadata, ChatPlatform, CrawdEvents, McapEvent, MockChatEvent, ReplyTurnEvent, StatusEvent, SuperChatInfo, TalkDoneEvent, TalkEvent, TtsProvider };
+export type { ChatMessage as ChatEvent, ChatMessage, ChatMessageMetadata, ChatPlatform, CrawdEvents, McapEvent, MockChatEvent, ReplyTurnEvent, StatusEvent, SuperChatInfo, TalkDoneEvent, TalkEvent };

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "crawd",
   "name": "Crawd Livestream",
-  "description": "crawd.bot plugin — AI agent livestreaming with TTS, chat integration, and OBS overlay",
+  "description": "crawd.bot plugin — AI agent livestreaming with chat integration and OBS overlay",
   "skills": ["./skills/crawd"],
   "configSchema": {
     "type": "object",
@@ -10,39 +10,10 @@
       "enabled": { "type": "boolean" },
       "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
       "bindHost": { "type": "string" },
-      "backendUrl": { "type": "string" },
-      "tts": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "chat": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "provider": { "type": "string", "enum": ["openai", "elevenlabs", "tiktok"] },
-                "voice": { "type": "string" }
-              },
-              "required": ["provider", "voice"]
-            }
-          },
-          "bot": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "provider": { "type": "string", "enum": ["openai", "elevenlabs", "tiktok"] },
-                "voice": { "type": "string" }
-              },
-              "required": ["provider", "voice"]
-            }
-          },
-          "openaiApiKey": { "type": "string" },
-          "elevenlabsApiKey": { "type": "string" },
-          "tiktokSessionId": { "type": "string" }
-        }
+      "autonomyMode": {
+        "type": "string",
+        "enum": ["vibe", "plan", "none"],
+        "description": "Autonomy mode: vibe (timed prompts), plan (goal-driven loop), or none (disabled)"
       },
       "vibe": {
         "type": "object",
@@ -52,6 +23,7 @@
           "intervalMs": { "type": "integer", "minimum": 1000 },
           "idleAfterMs": { "type": "integer", "minimum": 1000 },
           "sleepAfterIdleMs": { "type": "integer", "minimum": 1000 },
+          "batchWindowMs": { "type": "integer", "minimum": 1000 },
           "prompt": { "type": "string" }
         }
       },
@@ -86,16 +58,12 @@
     "enabled": { "label": "Enabled" },
     "port": { "label": "Backend Port", "placeholder": "4000" },
     "bindHost": { "label": "Bind Host", "placeholder": "0.0.0.0", "advanced": true },
-    "backendUrl": { "label": "Backend URL", "help": "Public URL for TTS file serving", "advanced": true },
-    "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 },
+    "autonomyMode": { "label": "Autonomy Mode", "help": "vibe = timed prompts, plan = goal-driven loop, none = disabled" },
     "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.batchWindowMs": { "label": "Chat Batch Window (ms)", "advanced": true },
     "vibe.prompt": { "label": "Vibe Prompt", "advanced": true },
     "chat.youtube.enabled": { "label": "YouTube Chat" },
     "chat.youtube.videoId": { "label": "YouTube Video ID" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawd",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "description": "CLI for crawd.bot - AI agent livestreaming platform",
   "type": "module",
   "types": "./dist/types.d.ts",
@@ -60,7 +60,8 @@
     "@types/ws": "^8.5.13",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
   },
   "openclaw": {
     "extensions": [
@@ -81,6 +82,7 @@
     "build:backend": "tsup src/backend/index.ts --format esm --out-dir dist/backend --clean",
     "build:plugin": "tsup src/plugin.ts --format esm --out-dir dist --dts",
     "build:all": "pnpm build && pnpm build:backend",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }

package/skills/crawd/SKILL.md

@@ -78,6 +78,42 @@ The coordinator manages your activity cycle through three states:
 
 When you receive a `[CRAWD:VIBE]` prompt, the coordinator is nudging you to do something autonomously. This is your self-directed time — browse, check socials, do something interesting for viewers. You don't have to speak every vibe, but you should be doing *something* visible.
 
+## Plan Mode
+
+When the coordinator is in plan mode, you work in structured goal-driven cycles instead of timed vibes.
+
+### How plans work
+
+1. You receive a trigger (chat message, wake-up, or `[CRAWD:PLAN]` nudge)
+2. Create a plan with `plan_set` — provide a goal and ordered steps
+3. Work on the current step (browse, talk, reply)
+4. Mark it done with `plan_step_done`
+5. The coordinator immediately nudges you with `[CRAWD:PLAN]` showing the next step
+6. Repeat until all steps are done or you abandon the plan
+
+### Plan tools
+
+| Tool | Purpose |
+|------|---------|
+| `plan_set` | Create a new plan (goal + steps). Replaces any existing plan. |
+| `plan_step_done` | Mark a step as complete by index. |
+| `plan_abandon` | Stop the current plan. Coordinator stops nudging. |
+| `plan_get` | View current plan progress. |
+
+### `[CRAWD:PLAN]` signals
+
+When you have an active plan, the coordinator sends `[CRAWD:PLAN]` nudges showing your progress and which step to work on next. These are immediate (not timed like vibes) — as soon as you finish a step, the next nudge arrives.
+
+If you receive chat with no active plan while in plan mode, create one with `plan_set` based on recent context (chat messages, what's on screen) or come up with your own idea.
+
+### Plan guidelines
+
+- **Keep plans short** (3-6 steps). Don't plan out 20 steps — plans can be replaced.
+- **Steps should be concrete and completable.** "Check bitcoin price" is good. "Become the best streamer" is not.
+- **Abandon plans that aren't working.** If a step is blocked or no longer relevant, use `plan_abandon` and create a new plan or go idle.
+- **Plans from chat:** When viewers suggest things to do, incorporate their ideas into a plan.
+- **You can replace plans.** Calling `plan_set` while a plan is active automatically abandons the old one.
+
 ## Coordinator Signals
 
 All coordinator messages use the `[CRAWD:*]` prefix:
@@ -86,6 +122,7 @@ All coordinator messages use the `[CRAWD:*]` prefix:
 |--------|---------|
 | `[CRAWD:CHAT]` | Batch of viewer chat messages. Reply with `livestream_reply`. |
 | `[CRAWD:VIBE]` | Autonomous activity nudge. Do something visible on stream. |
+| `[CRAWD:PLAN]` | Plan mode nudge. Shows current plan progress and next step. Work on it. |
 | `[CRAWD:MISALIGNED]` | Your previous response violated the protocol. You replied with plaintext instead of using a tool. Fix your behavior — use `livestream_reply` or `livestream_talk`, then respond with `LIVESTREAM_REPLIED`. |
 
 ## Safety (non-negotiable)

package/src/backend/coordinator.test.ts

@@ -0,0 +1,393 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Coordinator, type CoordinatorConfig, type CoordinatorEvent, type IClock, type TriggerAgentFn } from './coordinator.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Fake clock — timers are manually advanced via flush/advance */
+function createMockClock(): IClock & { advance(ms: number): void; flush(): void } {
+  const timers: Array<{ id: number; callback: () => void; fireAt: number; interval?: number }> = []
+  let now = 1_000_000
+  let nextId = 1
+
+  const clock: IClock & { advance(ms: number): void; flush(): void } = {
+    now: () => now,
+    setTimeout(cb, ms) {
+      const id = nextId++
+      timers.push({ id, callback: cb, fireAt: now + ms })
+      return id as unknown as NodeJS.Timeout
+    },
+    clearTimeout(t) {
+      const id = t as unknown as number
+      const idx = timers.findIndex(tt => tt.id === id)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval(cb, ms) {
+      const id = nextId++
+      timers.push({ id, callback: cb, fireAt: now + ms, interval: ms })
+      return id as unknown as NodeJS.Timeout
+    },
+    clearInterval(t) {
+      const id = t as unknown as number
+      const idx = timers.findIndex(tt => tt.id === id)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    /** Advance time by ms and fire all timers that would have fired */
+    advance(ms: number) {
+      const target = now + ms
+      while (true) {
+        // Find earliest timer that fires before target
+        const ready = timers
+          .filter(t => t.fireAt <= target)
+          .sort((a, b) => a.fireAt - b.fireAt)
+        if (ready.length === 0) break
+        const t = ready[0]
+        now = t.fireAt
+        const idx = timers.indexOf(t)
+        if (t.interval) {
+          // Reschedule interval
+          timers[idx] = { ...t, fireAt: t.fireAt + t.interval }
+        } else {
+          timers.splice(idx, 1)
+        }
+        t.callback()
+      }
+      now = target
+    },
+    /** Fire all currently ready timers without advancing */
+    flush() {
+      const ready = timers.filter(t => t.fireAt <= now).sort((a, b) => a.fireAt - b.fireAt)
+      for (const t of ready) {
+        const idx = timers.indexOf(t)
+        if (idx === -1) continue
+        if (t.interval) {
+          timers[idx] = { ...t, fireAt: t.fireAt + t.interval }
+        } else {
+          timers.splice(idx, 1)
+        }
+        t.callback()
+      }
+    },
+  }
+
+  return clock
+}
+
+const silentLogger = { log: vi.fn(), error: vi.fn(), warn: vi.fn() }
+
+function makeChatMessage(text: string) {
+  return {
+    id: `id-${text}`,
+    shortId: text.slice(0, 6),
+    username: 'tester',
+    message: text,
+    platform: 'youtube' as const,
+    timestamp: Date.now(),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Coordinator — Plan Mode', () => {
+  let clock: ReturnType<typeof createMockClock>
+  let triggerFn: ReturnType<typeof vi.fn<TriggerAgentFn>>
+  let events: CoordinatorEvent[]
+
+  const planConfig: Partial<CoordinatorConfig> = {
+    autonomyMode: 'plan',
+    planNudgeDelayMs: 100,
+    batchWindowMs: 50,
+    idleAfterMs: 5_000,
+    sleepAfterIdleMs: 5_000,
+  }
+
+  beforeEach(() => {
+    clock = createMockClock()
+    triggerFn = vi.fn<TriggerAgentFn>().mockResolvedValue(['LIVESTREAM_REPLIED'])
+    events = []
+  })
+
+  function createCoordinator(configOverrides?: Partial<CoordinatorConfig>) {
+    const coord = new Coordinator(triggerFn, { ...planConfig, ...configOverrides }, { clock, logger: silentLogger })
+    coord.setOnEvent(e => events.push(e))
+    coord.start()
+    return coord
+  }
+
+  describe('autonomyMode', () => {
+    it('defaults to plan from test config', () => {
+      const coord = createCoordinator()
+      expect(coord.getState().autonomyMode).toBe('plan')
+      coord.stop()
+    })
+
+    it('respects vibe mode', () => {
+      const coord = createCoordinator({ autonomyMode: 'vibe' })
+      expect(coord.getState().autonomyMode).toBe('vibe')
+      coord.stop()
+    })
+
+    it('respects none mode', () => {
+      const coord = createCoordinator({ autonomyMode: 'none' })
+      expect(coord.getState().autonomyMode).toBe('none')
+      coord.stop()
+    })
+  })
+
+  describe('setPlan', () => {
+    it('creates a plan and emits planCreated event', () => {
+      const coord = createCoordinator()
+      const plan = coord.setPlan('Do something cool', ['Step 1', 'Step 2', 'Step 3'])
+
+      expect(plan.goal).toBe('Do something cool')
+      expect(plan.steps).toHaveLength(3)
+      expect(plan.steps[0]).toEqual({ description: 'Step 1', status: 'pending' })
+      expect(plan.status).toBe('active')
+
+      const created = events.find(e => e.type === 'planCreated')
+      expect(created).toBeDefined()
+      expect((created as any).goal).toBe('Do something cool')
+      expect((created as any).stepCount).toBe(3)
+      coord.stop()
+    })
+
+    it('wakes coordinator if sleeping', () => {
+      const coord = createCoordinator()
+      expect(coord.state).toBe('sleep')
+
+      coord.setPlan('Wake up', ['Do it'])
+      expect(coord.state).toBe('active')
+      coord.stop()
+    })
+
+    it('abandons existing plan when setting a new one', () => {
+      const coord = createCoordinator()
+      const plan1 = coord.setPlan('First', ['Step A'])
+      coord.setPlan('Second', ['Step B'])
+
+      const abandoned = events.find(e => e.type === 'planAbandoned')
+      expect(abandoned).toBeDefined()
+      expect((abandoned as any).planId).toBe(plan1.id)
+
+      expect(coord.getPlan()?.goal).toBe('Second')
+      coord.stop()
+    })
+  })
+
+  describe('markStepDone', () => {
+    it('marks a step as done', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Test', ['A', 'B'])
+
+      const updated = coord.markStepDone(0)
+      expect(updated?.steps[0].status).toBe('done')
+      expect(updated?.steps[1].status).toBe('pending')
+      expect(updated?.status).toBe('active')
+      coord.stop()
+    })
+
+    it('completes plan when all steps done', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Test', ['A', 'B'])
+
+      coord.markStepDone(0)
+      coord.markStepDone(1)
+
+      expect(coord.getPlan()?.status).toBe('completed')
+      const completed = events.find(e => e.type === 'planCompleted')
+      expect(completed).toBeDefined()
+      coord.stop()
+    })
+
+    it('returns null for invalid index', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Test', ['A'])
+
+      expect(coord.markStepDone(-1)).toBeNull()
+      expect(coord.markStepDone(5)).toBeNull()
+      coord.stop()
+    })
+
+    it('returns null when no active plan', () => {
+      const coord = createCoordinator()
+      expect(coord.markStepDone(0)).toBeNull()
+      coord.stop()
+    })
+  })
+
+  describe('abandonPlan', () => {
+    it('abandons active plan', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Test', ['A'])
+
+      const abandoned = coord.abandonPlan()
+      expect(abandoned?.status).toBe('abandoned')
+
+      const event = events.filter(e => e.type === 'planAbandoned')
+      expect(event.length).toBeGreaterThanOrEqual(1)
+      coord.stop()
+    })
+
+    it('returns null when no active plan', () => {
+      const coord = createCoordinator()
+      expect(coord.abandonPlan()).toBeNull()
+      coord.stop()
+    })
+  })
+
+  describe('plan nudge loop', () => {
+    it('schedules nudge after flush when plan has pending steps', async () => {
+      const coord = createCoordinator()
+      coord.setPlan('Test', ['Step 1', 'Step 2'])
+
+      // Send a chat message to trigger flush
+      coord.onMessage(makeChatMessage('hello'))
+
+      // Wait for flush to complete
+      await vi.waitFor(() => expect(triggerFn).toHaveBeenCalledTimes(1))
+
+      // The flush should have triggered checkPlanProgress → schedulePlanNudge
+      const nudgeScheduled = events.find(e => e.type === 'planNudgeScheduled')
+      expect(nudgeScheduled).toBeDefined()
+
+      coord.stop()
+    })
+
+    it('sends [CRAWD:PLAN] prompt with plan progress', async () => {
+      const coord = createCoordinator()
+      coord.setPlan('Check BTC', ['Open tracker', 'Find price', 'Comment'])
+      coord.markStepDone(0)
+
+      // Advance past nudge delay to trigger planNudge
+      clock.advance(150)
+
+      // Wait for the nudge to fire
+      await vi.waitFor(() => {
+        const calls = triggerFn.mock.calls
+        return expect(calls.some((c: any[]) => c[0]?.includes('[CRAWD:PLAN]'))).toBe(true)
+      })
+
+      const planCall = triggerFn.mock.calls.find((c: any[]) => c[0]?.includes('[CRAWD:PLAN]'))
+      expect(planCall).toBeDefined()
+      const prompt = planCall![0] as string
+      expect(prompt).toContain('Check BTC')
+      expect(prompt).toContain('[x] 0. Open tracker')
+      expect(prompt).toContain('[-] 1. Find price')
+      expect(prompt).toContain('<-- next')
+
+      coord.stop()
+    })
+
+    it('does not nudge when plan is completed', async () => {
+      const coord = createCoordinator()
+      coord.setPlan('Quick', ['Only step'])
+      coord.markStepDone(0)
+
+      expect(coord.getPlan()?.status).toBe('completed')
+
+      clock.advance(200)
+      await new Promise(r => setTimeout(r, 50))
+
+      // No plan nudge should have been sent
+      const planNudges = triggerFn.mock.calls.filter((c: any[]) => c[0]?.includes('[CRAWD:PLAN]'))
+      expect(planNudges).toHaveLength(0)
+
+      coord.stop()
+    })
+
+    it('does not nudge when plan is abandoned', async () => {
+      const coord = createCoordinator()
+      coord.setPlan('Abandon me', ['Step 1', 'Step 2'])
+      coord.abandonPlan()
+
+      clock.advance(200)
+      await new Promise(r => setTimeout(r, 50))
+
+      const planNudges = triggerFn.mock.calls.filter((c: any[]) => c[0]?.includes('[CRAWD:PLAN]'))
+      expect(planNudges).toHaveLength(0)
+
+      coord.stop()
+    })
+
+    it('skips nudge when busy', async () => {
+      // Make trigger slow so coordinator stays busy
+      triggerFn.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(['LIVESTREAM_REPLIED']), 500)))
+
+      const coord = createCoordinator()
+      coord.setPlan('Busy test', ['Step 1', 'Step 2'])
+
+      // Trigger a chat message to make it busy
+      coord.onMessage(makeChatMessage('start'))
+
+      // Advance past nudge delay while flush is still in progress
+      clock.advance(150)
+
+      // Coordinator should handle the busy state gracefully without crashing
+      coord.stop()
+    })
+  })
+
+  describe('chat batch in plan mode', () => {
+    it('appends plan instruction to chat batch when no active plan', () => {
+      const coord = createCoordinator()
+      // No plan set
+
+      const batch = coord.formatBatch([makeChatMessage('do something cool')])
+      expect(batch).toContain('plan mode')
+      expect(batch).toContain('plan_set')
+
+      coord.stop()
+    })
+
+    it('does not append plan instruction when plan is active', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Active plan', ['Working on it'])
+
+      const batch = coord.formatBatch([makeChatMessage('hello')])
+      expect(batch).not.toContain('plan mode')
+
+      coord.stop()
+    })
+  })
+
+  describe('getState includes plan', () => {
+    it('includes plan and autonomyMode in state', () => {
+      const coord = createCoordinator()
+      coord.setPlan('Stateful', ['Step'])
+
+      const state = coord.getState()
+      expect(state.autonomyMode).toBe('plan')
+      expect(state.plan).toBeDefined()
+      expect(state.plan?.goal).toBe('Stateful')
+
+      coord.stop()
+    })
+  })
+
+  describe('vibe mode not affected', () => {
+    it('does not schedule vibes in plan mode', () => {
+      const coord = createCoordinator({ autonomyMode: 'plan' })
+      coord.wake()
+
+      clock.advance(35_000) // past default vibe interval
+
+      const vibeScheduled = events.find(e => e.type === 'vibeScheduled')
+      expect(vibeScheduled).toBeUndefined()
+
+      coord.stop()
+    })
+
+    it('schedules vibes in vibe mode', () => {
+      const coord = createCoordinator({ autonomyMode: 'vibe', vibeIntervalMs: 1_000 })
+      coord.wake()
+
+      const vibeScheduled = events.find(e => e.type === 'vibeScheduled')
+      expect(vibeScheduled).toBeDefined()
+
+      coord.stop()
+    })
+  })
+})